WINIO

This chapter describes:

The reasons and origins for using WINIO
Compiling and linking with WINIO
What the WMHANDLER functions are
How a sample program uses WINIO
Converting DOS and WINC programs to WINIO
Function reference

WINIO library functions are declared in winio.h. WINIO is an easy-to- use, higher level library built on top of the standard Windows 3.x API. You use it to write Windows programs, as well as to port DOS programs to Windows.

For in-depth information on how to use WINIO for all kinds of applications, see the book, Undocumented Windows by Andrew Shulman.

Introduction to WINIO

WINIO is a higher level, easy-to-use library built on top of the standard Windows 3.x API. It provides a DOS-like procedure based wrapper over event-driven Windows 3 application code.

WINIO supports a subset of the standard C stdio.h library functions under protected mode Windows 3.x, plus a set of extensions for handling events, manipulating windows, building menus, and more. It converts low level stdio.h library calls to Windows API calls.

Why Use WINIO?

You use WINIO for writing Windows programs, not just for porting DOS programs to Windows. WINIO makes Windows applications easier to read and code, because basic operations are not complicated or obscured by direct use of the Windows API calls.

WINIO applications let the user scroll and resize windows, click lines of text, and choose menu items. And WINIO properly handles many Windows WM_messages automatically. Your WINIO applications can also call the Windows API directly.

The Origin of WINIO

WINIO (sometimes called WINDOS) was developed by industry expert Andrew Shulman, and is described in his best-selling book, Undocumented Windows. This book is recommended reading for those interested in looking under the hood of Windows.

Andrew Shulman used the WINIO library to write nearly all the sample programs in Undocumented Windows, and the book offers numerous examples and detailed discussions on how to use WINIO for all kinds of programs.

Compiling and Linking with WINIO

To compile with WINIO:

Specify the -D_WINIO option on the SC command line, or define _WINIO in your code
Make your project a WINIO project in the IDDE

In addition, you need to include stdio.h in your compilation. Digital Mars's version of stdio.h includes winio.h automatically if the predefined macro _WINIO is defined. winio.h in turn includes windows. h automatically. If you use any of the wmhandler_ functions, you need to include wmhandler.h.

You can also compile with WINIO by replacing #include "stdio.h" with #include "windows.h" and #include "winio.h", as described on page 671 of Andrew Shulman's book, Undocumented Windows.

Linking with WINIO

WINIO resides in a separate .lib file that you must link with your application. The library you use depends on the memory model you're compiling with:

swindos.lib	Small model
mwindos.lib	Medium model
cwindos.lib	Compact model
lwindos.lib	Large model

Note
WINIO is supported for 16-bit compilations only. If you include winio.h in a 32-bit compilation, a compile time error is generated.

WINIO Resources

If you want your program to have the "Windows meets stdio" icon, use the windos.rc resource file. This file is included by default in WINIO projects created with the IDDE. If you create your own resource script, write #include to use the standard icon.

WMHANDLER Functions

You use the WMHANDLER functions to install and use handlers for WM_messages. The WMHANDLER functions are declared in wmhandlr. h. These functions are typically used along with the WINIO functions, although it is possible to create a WMHANDLER application that does not use WINIO calls. Most WINIO applications only need to call wmhandler_set() and/ or wmhandler_yield.

A Basic WINIO Program

WINIO programs begin with a call to main() rather than WinMain(). Standard argc, argv parameter passing is supported. Before main() is called, WINIO creates a window with a 32Kb buffer (see winio_window).

Here is an example of a WINIO program:

/* hello.c */
#define _WINIO 1
#include "stdio.h"

int main(int argc, char *argv[])
{
  int i;
  winio_settitle(winio_current(),
    "Hello from WINIO");

  for (i = 0; i < argc; i++)
    printf(%d\t%s\n", i, argv[i]);
  return 0;
}

Accessing WinMain() Parameters

Though WINIO programs include a call to main(), you still have access to WinMain() parameters. WINIO saves them in global variables, along with other basic information.

WINIO defines the following global variables:

HANDLE __hInst;
int __nCmdShow;
HANDLE __hPrevInst;
HWND __hMainWnd;
LPSTR __lpCmdLine;
char szModule[];

How the Compiler Generates WINIO Programs

When it compiles a program, the compiler generates symbols to call different versions of the C++ startup function. These startup functions are:

_arctused	MS-DOS, Windows 3, and Windows NT executables
_arctused_winc	WINIO executables
_arctused_dll	Windows 3 and Windows NT DLLs

The compiler determines what symbols to generate by examining the entry point, if any, it finds in a source file. If it finds a main() entry point, and the compilation is a Windows compilation, the compiler generates the external variable _arctused_winc, which is defined in the WINIO startup code. The WINIO startup code contains a WinMain() entry point that in turns calls your program's main().

Converting DOS Programs to WINIO

To get a DOS program working as a WINIO program you simply compile it for Windows (either with the -W compiler option or by making it a Windows project in the IDDE), define the _WINIO macro, and link with the appropriate WINIO library.

Converting WINC Programs to WINIO

The Digital Mars C++ run-time library no longer supports WINC. To convert your WINC programs to WINIO,

Convert all stdio.h function calls to the subset of stdio.h that WINIO supports (see "WINIO's Implementation of stdio.h Functions" below for a list).
Convert winc_variables to their corresponding winio_ function calls.

WINIO's Implementation of stdio.h Functions

WINIO's versions of gets(), printf(), and other stdio.h functions call the standard Windows message retrieval functions. WINIO supports the following functions from stdio.h:
fgetchar
fputchar
getchar
gets
kbhit
printf
puts
putchar
ungets
vprintf

In WINIO programs, all input and output to and from stdio must go through the functions above. For example, you can use fgetchar(), but not fgetc(stdin). Also, stderr is not supported. scanf() is not supported, but you can use sscanf() in combination with gets(), like this:

HWND hwnd;
char buf[80];
gets(buf);
sscanf(buf, "% 04X", &hwnd);

How WINIO Implements gets()

Generally, the WINIO versions of these functions are similar to their stdio.h counterparts, and do not require additional documentation. However, the WINIO version of gets() differs significantly from the standard version, and is documented separately. Some other important differences are:

getchar() behaves differently by default than it does under DOS. The C construct
```
int c;
while ((c = getchar()) != EOF)
    putchar(c);
```
does not work as expected under WINIO because characters input via getchar() are echoed to the screen by default. Thus the code above echoes each character twice. You could remove the call to putchar(), or call winio_setecho(FALSE).
Tests for EOF might now be inappropriate, because the user can double click on the window's Close box. You can code a standard C echo loop for WINIO like this:
```
for (;;)
    getchar();
```
DOS displays the ASCII control codes 1 through 26 using the strings ^A through ^Z, except for 8 (backspace), 9 (tab), 10 (line feed), 11 (vertical tab), 16 (toggle print), and 19 (stop output); these are interpreted but not displayed. WINIO does not print anything below ASCII code 32, (space). With the exception of ^P and ^S, WINIO does interpret the same characters in the same way as DOS, including interpreting ASCII 26 as EOF.

WINIO Functions

The WINIO and WMHANDLER functions are categorized by name in Chapter 2, and are also alphabetized and described along with the other Digital Mars C++ functions in this manual.

fail

Header: winio.h
Prototype: void fail(const char *fmt, ...);
Description: The fail function displays a message box and terminates a WINIO program. fmt is a zero-terminated format string; fail accepts a variable number of arguments, which are interpreted according to fmt.
The format string is a sequence of characters with embedded commands to manipulate the arguments that follow. For a list of valid commands see the documentation for fprintf.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: fprintf

ungets

Header: winio.h
Prototype: char *ungets(char *string);
Description: The WINIO version of the ungets function works like ungetc (which WINIO does not support), except that it pushes a string into the input stream, rather than a single character.
Calling ungets is equivalent to sending a WM_CHAR message to the current window for each character in the string.
Return Value: A pointer to string if successful, or EOF if string cannot be pushed back.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: ungetc

winio_about

Header: winio.h
Prototype: void winio_about(char *string);
Description: The winio_about function lets you edit the text in the default WINIO About dialog box. The string argument becomes the text displayed inside the About box. It can include newline characters. Characters beyond the 512th character in the string are truncated.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_bufsize

Header: winio.h
Prototype: WORD winio_bufsize(HWND hwnd);
Description: The winio_bufsize function returns the size in bytes of the buffer associated with the window hwnd.
By default, the buffer for a WINIO program's main window is 32Kb. For child windows, the default size is 8Kb. You set the size of the buffer with winio_setbufsize.
Return Value: The size of the buffer allocated for hwnd.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: winio_setbufsize

winio_clear

Header: winio.h
Prototype: void winio_clear(HWND hwnd);
Description: The winio_clear function clears the contents of the buffer associated with the window hwnd. Calling this function reinitializes the window and causes it to be redisplayed (blank).
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: winio_bufsize winio_setbufsize

winio_close

Header: winio.h
Prototype: void winio_close(HWND hwnd);
Description: The winio_close function closes the window hwnd by calling the Windows API function DestroyWindow(). Buffer space allocated for the window is freed.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_closeall

Header: winio.h
Prototype: void winio_closeall();
Description: The winio_closeall function closes all a WINIO application's windows by closing the main window. All associated buffer space is freed.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_current

Header: winio.h
Prototype: HWND winio_current();
Description: The winio_current function returns the handle of the current (active) WINIO window.
Return Value: The handle of the active window.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: winio_setcurrent

winio_defwindowsize

Header: winio.h
Prototype: DWORD winio_defwindowsize(DWORD size);
Description: The winio_defwindowsize function sets the default height and width in characters for all windows subsequently created via calls to winio_window(). The high order word holds the height and the low order word holds the width.
Return Value: The default window size that was in effect prior to the call to winio_defwindowsize.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_end

Header: winio.h
Prototype: void winio_end();
Description: The winio_end function signals WINIO that a task is terminating. It calls wmhandler_yield() until the number of windows is zero (meaning that the user has closed all the application's windows). winio_end will only be called from WinMain() on return from main().
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_getinfo

Header

winio.h

Prototype

void winio_getinfo(HWND hwnd, PWINIOINFO pwinfo);

Description

The winio_getinfo function returns information about the WINIO window hwnd in a WINIOINFO structure of the form:

typedef struct {
 POINT dimChar;   // Character cell dimensions
 POINT posCurr;   // Current position of text
                  // cursor from top of buffer
 RECT rectView;   // Visible part of buffer
                  // (ht. lines, wid. chars)
 long cDiscarded; // Lines taken from buffer
} WINIOINFO, *PWINIOINFO, FAR *LPWINIOINFO;

where RECT and POINT are standard Windows defined types defined in windows.h.

The dimensions of a character cell depend on the window's font (see winio_setfont() for information).

The current cursor position refers to the number of characters to the right of the first character in the buffer, and the number of lines down from the first line. The first position is 0, 0 (the top left corner).

The visible part of the buffer is described in relation to the top left corner of the buffer; the left and right fields contain the numbers of the leftmost and rightmost visible columns in characters, and the top and bottom fields contain the line numbers of the topmost and bottommost visible lines.

The cDiscarded member refers to the number of lines of the display that have been discarded from the top of the buffer to create space for new text lines.

Return Value

None

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

winio_hmenufile

Header

winio.h

Prototype

HMENU winio_hmenufile(HWND hwnd);

Description

The winio_hmenufile function lets you modify a WINIO window's File menu.

If hwnd was created with the WW_HASDMENU flag, winio_hmenufile returns the menu handle of the File pop-up menu. You can pass the handle to the Windows API functions InsertMenu() and AppendMenu() to add additional choices to the menu.

Note: You must use winio_setmenufunc() to register the IDs of any menu items you add to a WINIO application's File menu with a handler function. Otherwise the application cannot regain control after the user chooses that menu item.

Return Value

The handle of the File menu on hwnd's menu bar, or NULL if the window has no menu.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

winio_setmenufunc winio_window

winio_hmenuhelp

Header

winio.h

Prototype

HMENU winio_hmenuhelp(HWND hwnd);

Description

The winio_hmenuhelp function lets you modify a WINIO window's Help menu.

If hwnd was created with the WW_HASDMENU flag, winio_hmenuhelp returns the menu handle of the Help main menu item. You can pass the handle to the Windows API functions InsertMenu() and AppendMenu() to add choices to the menu.

Note: You must use winio_setmenufunc() to register the IDs of any menu items you add to a WINIO application's Help menu with a handler function. Otherwise the application cannot regain control after the user chooses that menu item.

Return Value

The handle of the Help menu on hwnd's menu bar, or NULL if the window has no menu.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

winio_setmenufunc winio_window

winio_hmenumain

Header: winio.h
Prototype: HMENU winio_hmenumain(HWND hwnd);
Description: The winio_hmenumain function lets you modify a WINIO window's main menu.
If hwnd was created with the WW_HASMENU flag, winio_hmenumain returns the menu handle of the main menu bar.
Return Value: The handle of hwnd's main menu, or NULL if the window has no menu.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: winio_setmenufunc winio_window

winio_home

Header: winio.h
Prototype: void winio_home(HWND hwnd);
Description: A call to the winio_home function is equivalent to the user pressing the HOME key. You use it to reposition the current text cursor position to the start (the top left corner) of hwnd's buffer.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: winio_setmenufunc winio_window

winio_init

Header: winio.h
Prototype: int winio_init();
Description: The winio_init function is used internally by the WINIO library to register the WINIO class and initialize global variables. Typically, it should only be called from WinMain() before main() is called.
Return Value: TRUE if successful; otherwise it returns FALSE and issues a warning.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_onclose

Header

winio.h

Prototype

void winio_onclose(HWND hwnd, DESTROY_FUNC exitfunc);

Description

The winio_onclose function lets you handle situations where the user has closed the window from which the application expected input. It calls the WINIO library's WM_DESTROY handler. You need to call this function to inform you when the user clicks the system menu bar.

hwnd is the handle of the window that closed. exitfunc is a callback function; its prototype must look like this:

void callback(HWND hwnd); If exitfunc is NULL, the current callback function is disabled.

winio_onclose is invoked after the window is closed. To ask the user whether he or she really wants to close hwnd, establish a WMHANDLER for the WM_CLOSE message.

Return Value

None

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

winio_onpaintentry

Header

winio.h

Prototype

PAINT_FUNC winio_onpaintentry(HWND hwnd, PAINT_FUNC paintfunc);

Description

The winio_onpaintentry function gives WINIO programs access to Graphic Device Interface (GDI). It allows an application to gain control after WINIO has obtained a display context, but before the internal winio_wmpaint() function starts painting the window.

hwnd is the handle of the window that closed. paintfunc is a callback function; its prototype must look like this:

BOOL callback(HWND hwnd, HDC hdc, PAINTSTRUCT *pps, PWINIOINFO pwi);

where hwnd is the window to be updated, hdc is the display context returned by the Windows API BeginPaint() function, pps is a pointer to the PAINTSTRUCT filled in by the BeginPaint() call, and pwi is a pointer to a WINIOINFO structure (see winio_getinfo()).

paintfunc can modify any display context or painting operation. If it returns TRUE, WINIO updates the window; if it returns FALSE, WINIO will not update the window, leaving it empty of buffer text. If paintfunc is NULL, the current callback function is disabled.

Return Value

PAINT_FUNC

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

winio_onpaintexit

Header

winio.h

Prototype

PAINT_FUNC winio_onpaintexit(HWND hwnd, PAINT_FUNC paintfunc);

Description

The winio_onpaintexit function works like winio_onpaintentry, except that it is called just before WINIO calls the Windows API function EndPaint to release the display context.

Unless a callback function registered using winio_onpaintentry has returned FALSE, winio_onpaintexit() is invoked after the window has been updated with text from the window's buffer.

hwnd is the handle of the window that closed. paintfunc is a callback function; its prototype must look like this:

BOOL callback(HWND hwnd, HDC hdc, PAINTSTRUCT *pps, PWINIOINFO pwi);

paintfunc can modify any display context or painting operation. Its return value is ignored. If paintfunc is NULL, the current callback function is disabled.

Return Value

None

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

winio_openwindows

Header: winio.h
Prototype: int winio_openwindows();
Description: The winio_openwindows function returns the number of WINIO windows that are open when it is called.
Return Value: The number of open WINIO windows.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_resetbusy

Header: winio.h
Prototype: void winio_resetbusy();
Description: The winio_resetbusy function resets the WINIO cursor to the shape it had prior to the call, and releases the cursor. You use it in combination with winio_setbusy to block user input.
When you call winio_setbusy, an internal counter is incremented. Calling winio_resetbusy decrements the counter. winio_resetbusy only releases the cursor if the counter's value is zero.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: winio_setbusy

winio_setbufsize

Header: winio.h
Prototype: WORD winio_setbufsize(HWND hwnd, WORD bufsize, BOOL clear);
Description: The winio_setbufsize function sets the size of the buffer for the window hwnd. If clear is FALSE, the buffer cannot be smaller than hwnd's current buffer size.. If clear is TRUE, hwnd's buffer is cleared, and it can be any size greater than 4Kb.
The default buffer size for a WINIO main window is 32Kb, and 8Kb for a child window.
Return Value: The size in bytes of the new buffer.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_setbusy

Header: winio.h
Prototype: void winio_setbusy();
Description: The winio_setbusy function lets you block user input during an operation. It captures the cursor and changes its shape to the standard Windows "hourglass." To release the capture and return the cursor to its previous shape, call winio_resetbusy.
When you call winio_setbusy, an internal counter is incremented. Calling winio_resetbusy decrements the counter. winio_resetbusy only releases the cursor if the counter's value is zero.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: winio_resetbusy

winio_setcurrent

Header: winio.h
Prototype: HWND winio_setcurrent(HWND hwnd);
Description: The winio_setcurrent function makes hwnd the current window. Calls to stdio operate on the current window.
Return Value: The handle that was current prior to the winio_setcurrent call.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_setecho

Header: winio.h
Prototype: BOOL winio_setecho(HWND hwnd, BOOL bEcho);
Description: The winio_setecho function controls echoing of the standard input to the standard output.hwnd is the window you want to be stdout (the active window). If bEcho is TRUE, stdin is echoed to stdout (the WINIO default). If bEcho is FALSE, echoing to stdout is disabled.
Return Value: The setting for bEcho that was in effect before the call to winio_setecho.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_setfont

Header: winio.h
Prototype: WORD winio_setfont(HWND hwnd, WORD wFont);
Description: The winio_setfont function changes the font currently in use in the window hwnd. Only standard Windows system fonts are supported.
wFont can be one of the following constants defined in windows.h: ANSI_FIXED_FONT, OEM_FIXED_FONT, and SYSTEM_FIXED_FONT.
Return Value: The font that was in effect before the call to winio_setfont.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_setlinefn

Header

winio.h

Prototype

LINEHANDLER winio_setlinefn(HWND hwnd, LINEHANDLER linefunc);

Description

The winio_setlinefn function installs a handler, which is invoked when the user double-clicks on a line of text in hwnd. You can disable such a handler with a call to winio_linefn(hwnd, NULL).

linefunc is a callback function of type LINEHANDLER; its prototype must look like this:

void callback(HWND hwnd, LPSTR lpstrLine, int nLineNo);

where lpstrLine is a pointer to the line of text in the buffer that the user double-clicked on, and nLineNo is the line number of that line, where line 0 is the first line in the buffer. If text is discarded from the top of the buffer to create space for new text lines, nLineNo will decrease accordingly. However, you can use the cDiscarded member of the WINIOINFO structure (see winio_getinfo) to obtain a line number that will not change when text is discarded.

Return Value

None

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

winio_setmenufunc

Header

winio.h

Prototype

MENU_FUNC winio_setmenufunc(HWND hwnd, int nID, MENU_FUNC menufunc);

Description

The winio_setmenufunc function installs a handler, which is invoked when the user selects a menu item that you added to the default WINIO main menu or File menu. If you do not set up a handler for a new menu item, your WINIO application cannot know the user has chosen it.hwnd is the window where the item was added.

nID is the item's ID. menufunc is a callback function of type MENU_FUNC; its prototype must look like this:

void callback(HWND hwnd, int nID);

where hwnd is a window and nID is a menu ID.

Note
You must allocate menu ids in order from 1 through 32. This permits a total of up to 32 additional menu items per window.

Return Value

None

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

winio_setpaint

Header

winio.h

Prototype

BOOL winio_setpaint(HWND hwnd, BOOL bPaint);

Description

The winio_setpaint function turns automatic updating of the display on and off. It lets you delay updating the text in a window, so WINIO applications can repaint the display less frequently (and more smoothly).

If bPaint is FALSE, hwnd is not updated when new text is added to the buffer. The text is updated (using the stdio functions) when winio_setpaint is called again with bPaint set to TRUE.

WINIO does not yield control to other applications between a winio_setpaint(FALSE) and a winio_setpaint(TRUE). You can call this function if your code is working with a data structure that can be changed by other applications (for example, the Windows global heap).

Return Value

The setting for bPaint that was in effect before the call to winio_setpaint.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

winio_settitle

Header: winio.h
Prototype: void winio_settitle(HWND hwnd, char *strTitle);
Description: The winio_settitle function lets you change the title bar text for hwnd to strTitle. The default title bar text is the module name; if the window is a main window, any command line arguments are also included.
winio_settitle works by calling the Windows API function SetWindowText().
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

winio_warn

Header: winio.h
Prototype: BOOL winio_warn(BOOL bConfirm, char *strCaption, const char *fmt, ...);
Description: The winio_warn function displays a Windows-type message box. If bConfirm is FALSE, the message box will have only an OK button, and winio_warn will always return TRUE. If bConfirm is TRUE, the message box will have both an OK button and a Cancel button, and winio_warn will return FALSE if the user chooses Cancel, and TRUE otherwise.
strCaption specifies the title bar text for the message box. fmt is a zero-terminated format string; winio_warn accepts a variable number of arguments, which are interpreted according to fmt. fmt is a sequence of characters with embedded commands. For a list of valid commands see the fprintf function.
Return Value: TRUE if the user chooses OK; FALSE if the user chooses Cancel.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: fprintf

winio_window

Header

winio.h

Prototype

HWND winio_window(LPSTR lpstrTitle, WORD wBufSize, WORD wFlags);

Description

The winio_window function lets a WINIO application create additional windows other than its main window.

lpstrTitle specifies the window's title bar text. wBufSize specifies the size in bytes of the buffer to allocate for the window. The buffer is allocated from global memory and determines how much information about the window's display history is maintained. If wBufSize is 0, WINIO uses the default buffer size of 8Kb; otherwise the specifed number of bytes are allocated. If wBufSize is less than 4Kb, it is rounded up to 4Kb.

wFlags is a combination of zero or more of the following lags, combined in a series of logical OR operations:

WW_HASMENU(0x0001)	Give the new window a default WINIOmenu (see winio_setmenufunc() forinformation on modifying a default menu).
WW_EXITALLOWED (0x0002)	Enable the Exit option on the File popup menu. If this flag is used, the user can exit the application from any window. If WW_HASMENU is not used, this flag is ignored.
WW_STAYSONTOP (0x0004)	By default, WINIO windows are "owned pop-ups," not child windows. Thus, when the main WINIO window is active, it can cover part or all of its pop-ups, and minimizing the main window does not automatically minimize the pop-ups. Use this flag to make all new windows true child windows and avoid these behaviors.

Return Value

The new window's handle.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

winio_setmenufunc

wmhandler_create

Header: winio.h
wmhandlr.h
Prototype: WMTAB wmhandler_create();
Description: The wmhandler_create function allocates memory for the arrays that WMHANDLER applications use to store pointers to the functions installed to handle messages for a window. (In other words, it allocates and initializes a WM_handler table.)
Your code should store the pointer that wmhandler_create returns in the wmTab field in the CREATEPARAMS structure (see wmhandler_wndproc()). The wmhandler_wndproc() function retrieves this pointer along with a 32-bit value (usually a far pointer) supplied by the application when the application receives a WM_CREATE message, and places them in the extra-data area associated with the window. Thus, wmhandler_wndproc() uses the WMTAB pointer returned by wmhandler_create to locate a handler for all messages a window receives.
Return Value: A pointer to the memory area where the message handlers are stored.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: wmhandler_wndproc

wmhandler_destroy

Header: winio.h
wmhandlr.h
Prototype: void wmhandler_destroy(HWND hwnd);
Description: The wmhandler_destroy function works in combination with wmhandler_create. It retrieves the WMTAB pointer from hwnd that wmhandler_create returns, and frees the associated memory.
Return Value: None
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: wmhandler_create

wmhandler_get

Header: winio.h
wmhandlr.h
Prototype: WMHANDLER wmhandler_get(HWND hwnd, WORD wMsg);
Description: The wmhandler_get function returns a pointer to the function that is currently handling the message wMsg for hwnd.
wmhandler_get never returns NULL; messages for which handlers have not been installed are handled by an internal function that passes them to the Windows API function DefWindowProc().
Return Value: A pointer to the handler for wMsg. (See wmhandler_set for a description of the WMHANDLER type).
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32
See Also: wmhandler_set

wmhandler_hwnd

Header: winio.h
wmhandlr.h
Prototype: HWND wmhandler_hwnd(char *strTitle);
Description: The wmhandler_hwnd function creates a window that a WMHANDLER application uses internally (it is not visible to the user). strTitle is the internal name for the window.
A table of message handlers is associated with the window. You can send messages to the window, and use its handle in calls to wmhandler_set(). A window created with wmhandler_hwnd is useful when you want to handle events without a corresponding user interface element.
Return Value: The handle to the newly created window.
Compatibility: DOS Windows 3.x Phar Lap DOSX Win32

wmhandler_set

Header

winio.h
wmhandlr.h

Prototype

WMHANDLER wmhandler_set(HWND hwnd, WORD message, WMHANDLER wmhandler);

Description

The wmhandler_set function installs a function wmhandler to handle messages of type message that are sent to the window hwnd. message can be any number, even a number greater than WM_USER (0x400). message can also be a number returned by the Windows API function RegisterWindowMessage(). However, a WMHANDLER program can install no more than 16 handlers for messages whose numbers are greater than 0x400. wmhandler is a callback function of type WMHANDLER; its prototype must look like this:

long wmhandler(HWND hwnd, unsigned message, WORD wParam, DWORD lParam);

The callback function should return whatever is appropriate for the type of WM_message it is handling. If wmhandler is NULL, an internal handler passes the message to the Windows API function DefWIndowProc().

The callback function can chain onto the handler wmhandler_set returns if required. If a WMHANDLER application handles one of the WM_messages also handled by WINIO, the callback function must chain. WINIO installs handlers for the following messages:

WM_CHAR

WM_COMMAND

WM_DESTROY

WM_HSCROLL

WM_KEYDOWN

WM_KILLFOCUS

WM_LBUTTONDBLCLK

WM_PAINT

WM_SETFOCUS

WM_SIZE

WM_VSCROLL

If wmhandler_set() is used in a non-WINIO program, hwnd must use wmhandler_wndproc() as its window proceudre, and it must have a WMTAB pointer as the first four bytes of associated user data (see wmhandler_create).

Return Value

The handler in effect before the call to wmhandler_set.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

Standard C

Standard C++

Win32

DOS, DOS32, Win16

Other C

Other C++

Introduction to WINIO

Why Use WINIO?

The Origin of WINIO

Compiling and Linking with WINIO

Linking with WINIO

WINIO Resources

WMHANDLER Functions

A Basic WINIO Program

Accessing WinMain() Parameters

How the Compiler Generates WINIO Programs

Converting DOS Programs to WINIO

Converting WINC Programs to WINIO

WINIO's Implementation of stdio.h Functions

How WINIO Implements gets()

WINIO Functions