OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / zfrms110.zip / ZFORMS.DOC < prev next >

Wrap

Text File | 1993-09-06 | 57KB | 1,280 lines

Z-Forms Screen Management Libraries Version 1.1 Users Guide (C) 1993, Z-Space All Rights Reserved Z-Forms Screen Management Libraries Z-Forms Philosophy: Z-Forms is a powerful tool that assists programmers in producing applications with a fast, text-mode, windowed user interface. The package features built-in windowing, menuing, dialog boxes, mouse handling, and data input support. Z-Forms is intended to be easy to use, utilizing a minimal set of function calls. However, ease-of-use is not achieved at the expense of flexability and power. Z-Forms allows the programmer to configure every parameter that effects the way the program screen looks, and contains many built-in features to handle a wide variety of user-interface tasks. Z-Forms Overview: The programmer specifies the content and look of any desired windows, dialog boxes, menus, etc. by declaring and initializing structures in the source code. Once defined, Z-Forms handles the screen configuration and drives the program flow based on user interaction. Application functions, menus, dialog boxes, etc. can be specified to be the results of button presses or menu selections. For example, you might define a menu with three items; the first might call another menu, the second a dialog box, and the third a function. The programmer provides the desired structure, definition and application specific functions, and Z-Forms handles the rest! It is our hope that Z-Forms will cut down your programming time and provide robust handling of the user interface. This IS a shareware package, and does require a registration fee if you choose to continue using it after 30 days. The registration fee is currently $35 US (libraries only), or $65 for source code. When you register, you will be sent the latest "registered" version of Z-Forms. ------------------------------------------------------------------------ IMPORTANT: READ THE READ.ME FILE FOR NEW FEATURES AND BUG FIXES ------------------------------------------------------------------------ DISCLAIMER OF WARRANTY ====================== THIS SOFTWARE AND MANUAL ARE DISTRIBUTED AND SOLD "AS IS" AND WITHOUT WARRANTIES AS TO PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED OR IMPLIED. BECAUSE OF THE VARIOUS HARDWARE AND SOFTWARE ENVIRONMENTS INTO WHICH THIS PROGRAM MAY BE PUT, NO WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED. GOOD OPERATING PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM. ANY LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE. Installing Z-Forms: Unpack the distribution file into an appropriate directory (for example, C:\ZFORMS). Then unpack the library files from the library distribution that matches your compiler: Microsoft C 6.0 : MSC600.ZIP IBM C/Set : CSET.ZIP Borland C/C++ for OS/2 : BCOS2.ZIP Borland C/C++ V2.0/V3.0 : BORLANDC.ZIP EMX/GCC : EMX.ZIP Then, simply add the header file ZFORMS.H to any source files that will make Z-Forms calls, and link with the libraries. For more information about using Z-Forms with your compiler, please read the READ.ME file. We have included some sample code (in ZFORMS.C) which demonstrates most of the functionality of Z-Forms. We have supplied this sample code compiled for bound 16-bit DOS and OS/2 (ZFORMS.EXE) and 32-bit OS/2 (ZFORMS32.EXE). Please take a few minutes to examine the sample code and run the program. This is your best guide to how the functions work. Z-Forms Object Types: There are five basic object types in Z-Forms. Each is defined by initializing appropriate stuctures. The number of Z-Forms objects allowed is determined by available memory. WINDOW: A Window is a rectangular region, with configurable size, position, border, drop shadow, titles, colors, etc. You can have as many windows overlapping on the screen as you want. Each window is maintained in memory as a complete virtual screen, and the physical screen is generated by determining which parts of each window are visible, and displaying them. All windows can be written to, and any visible parts will be updated on the screen. DIALOG BOX: A special window that can have groups of controls (buttons, checkboxes, one-of-buttons, data entry fields, etc.) used to request user input. MENU: A vertical or horizontal group of selections. Each menu option can be used to select another menu, dialog box, or function, or to exit the menu. PROMPT: A Prompt is a group of data entry fields on a window. Each field may have a data mask and a verification function, and allows editing. PICKLIST: A vertical list of items, scrolled by the up/down arrow keys, that allows the user to select an item from a group of items. Using Z-Forms Windows: A Window is defined by initializing a window structure, and passing it to a Z-Forms function. Z-Forms maintains a virtual screen buffer for the window in memory, and updates the display from it. The window structure contains the following fields: fShown : Flags whether the window is visible or not. This field should not be directly manipulated, but is set and cleared by Z_ShowWindow and Z_HideWindow. Initialize to zero. Height : Window height, including the border Width : Window width, including the border Prev : Pointer to the previous window (maintained by Z-Forms). Initialize to NULL. Next : Pointer to the next window (maintained by Z-Forms). Initialize to NULL. XOrg : X co-ordinate on the screen of the left edge of the window (0 based) YOrg : Y co-ordinate on the screen of the top edge of the window (0 based) DefaultChar: A character/attribute pair used to fill the window when initially opened. The high byte is the attribute, the low byte the character. For example, 0x1E20 would be Yellow (E) on Blue (1), Space (20) character. BorderStyle: The border style identifier: BS_NOBORDER BS_SINGLELINE BS_DOUBLELINE BorderColor: The border foreground color (See ZFORMS.H for colors) BorderBack : The border background color DropShadow : The drop shadow identifier: DS_UPPERLEFT DS_UPPERRIGHT DS_LOWERRIGHT DS_LOWERLEFT DS_NONE DropAttr : The attribute to use for the background of the drop shadow (DARKGREY is good). Title : Pointer to the title character string. The title is centered on the top line of the window. If this parameter is NULL, no title will be displayed. SubTitle : Pointer to the subtitle character string. The subtitle is centered on the bottom line of the window. If this parameter is NULL, no subtitle will be displayed. pVS : Pointer to the virtual screen buffer, maintained internally. Initialize to NULL. Note: Prev, Next, and pVS should be initialized to NULL. fShown should be initialized to 0. There are three methods to create a window. In method 1, a predefined window structure is used, and all processing is handled internally: Z_OpenWindow(...); This is the simplest method, assuming that the window structure was known or can be initialized. All of the windows in the sample code are opened using Z_OpenWindow. Method 2 involves creating a window structure, defining the window, then showing it. The code for this would be similar to: Z_CreateWindow(...); Z_DefineWindow(...); Z_ShowWindow(...); This method would only be used when a window had to be created on-the-fly, but even then you could probably use a pre-defined structure, and simply change the fields. Method 3 also uses a predefined window structure, which is defined and shown: Z_DefineWindow(...); Z_ShowWindow(...); Once the window is open, you may write to it using the Z_Text or Z_Char functions: Z_TextOut writes text at the specified window co-ordinates using the designated colors. Z_TextOver writes the text using the colors already on that position. Z_CharOut and Z_CharOver write a single character to the window. Z_CharOutAtCursor and Z_CharOverAtCursor write a single character at the current cursor coordinates. Z_CharOutTTY and Z_CharOVerTTY write a single character at the current cursor coordinates and advance the cursor one unit. The window may be hidden, if necessary, by calling Z_HideWindow. If the window is hidden, it may be shown using Z_ShowWindow. Finally, you may push a window to the 'back' of the screen using Z_PushWindow, or make a window the 'top' window using Z_PopWindow. Menus: There are two types of menus available in Z-Forms; Vertical and Horizontal. The menu is created by defining a menu structure, as follows: OrgX : Menu X origin on the physical display OrgY : Menu Y origin on the physical display Height : Menu window height (1 for horizontal) Width : Menu window width TextWidth : The width of the menu text for a vertical menu. This field determines the width of the highlight bar. Flags : Menu Flags (may be combined with | where sensible): MMF_VERTMENU MMF_HORIZMENU MMF_USEHINT MMF_NOHINT TextColor : Color of menu text BackColor : Color of menu text background HotColor : Color of hot key letter HotBack : Color of hot key letter background HiTextColor: Color of highlighted text HiBackColor: Color of highlighted text background HintTextColor: Color of hint text HintBackColor: Color of hint background HintOrgX : Screen X origin for hint window HintOrgY : Screen Y origin for hint window HintWidth : Width of hint window BorderStyle: Border style identifier: BS_NOBORDER BS_SINGLELINE BS_DOUBLELINE BorderColor: Color for border line, if any BorderBack : Background color for border DropShadow : The drop shadow identifier: DS_UPPERLEFT DS_UPPERRIGHT DS_LOWERRIGHT DS_LOWERLEFT DS_NONE DropAttr : The attribute to use for the background of the drop shadow Title : Pointer to title character string, or NULL for none Item[] : Array of menu items, terminated by a dummy entry with a NULL Text field (see below). A menu item has the following structure: Text : Pointer to menu item text string Flags : Menu item flags: MIF_USEHINT MIF_NOHINT MIF_CALLMENU MIF_CALLDIALOG MIF_CALLFUNC MIF_CALLNOTHING MIF_RIGHTJUST MIF_LEFTJUST MIF_SUBMENU MIF_NOSUBMENU HotKey : Key press to activate this item (i.e. k_Alt_A) OffsetHiLite: Offset into item text to the character to highlight, or -1 for none. The first character is 0 XOrg : X position of item within window with respect to the menu YOrg : Y position of item within window with respect to the menu ActionPtr : Pointer to the action to take upon selection. Can be a pointer to a function, another menu, or a dialog box Hint : Pointer to hint text A menu is created by initializing the menu structure and Item array. The last entry in the Item array must have a NULL Text field. For example, this menu is taken from the sample code: static MENU_ITEM VertMenuItem[] = { "TTY Demo", MIF_CALLFUNC, 'T', 0, 1, 1, (void *)TTYDemo, " TTY demo with auto-scrolling ", "Background Demo", MIF_CALLFUNC, 'B', 0, 1, 2, (void *)BackgroundDemo, " Demo of background processes/windows", "Nothing", MIF_CALLEXIT, 'N', 0, 1, 3, NULL, " Dummy option does nothing ", ****> NULL, 0, 0, 0, 0, 0, NULL, "" }; static MENU VertMenu = { 33, 2, 5, 20, 18, MMF_VERTMENU | MMF_USEHINT, BRIGHTWHITE, BLUE, LT_RED, BLUE, BLUE, CYAN, WHITE, BLUE, 1, 23, 78, BS_SINGLELINE, YELLOW, BLUE, 0, 0, NULL, VertMenuItem }; Notice that the fourth menu item is completely NULL. This terminates the array. After initializing the menu structure, call Z_HandleMenu(...). This function handles all menu processing. If the menu is a horizontal menu, a window is created which is 'Height' characters high and 'Width' wide. The items are displayed across the menu according to the XOrg parameter. If the menu is a vertical menu, a window is created using the Height and Width parameters. There can be extra space around the actual menu items, if necessary. There can also be a border and title around the window. The Height and Width include this border. If MMF_USEHINT is set, a hint window is also created, and the hint text is displayed for each item as the user selects it. The hint is a short description of the menu selection for the user. NOTE: In order for the mouse to function properly, you must specify a unique hot-key for each menu item. The menu then allows the user to select the desired menu choice by using the arrow keys, the mouse, or by pressing the hot key for the item. When the user selects the menu item, Z-Forms checks the MIF_CALLXXXX flag to determine what to do next. If MIF_CALLMENU is set, then Z_HandleMenu is called, and ActionPtr is assumed to point to another menu structure. This allows nested menus and submenus, pulldown menus, etc. If MIF_CALLDIALOG is set, ActionPtr is assumed to point to a dialog box structure, and Z_HandleDialog is called. If MIF_CALLFUNC is set, ActionPtr is assumed to point to a function, and the function is called. The function prototype should be void UserFunc(int Item); where Item is the menu item number that was selected. If MIF_CALLNOTHING is set, no action occurs when the menu item is selected. The Escape key or an item with MIF_CALLEXIT exits the menu. Dialog Boxes: A dialog box is defined by initializing a dialog box structure and calling Z_HandleDialog(...). The fields of the structure are: XOrg : Screen X origin of dialog box YOrg : Screen Y origin of dialog box Height : Dialog box height Width : Dialog box width Flags : Dialog box flags DBF_USEHINT DBF_NOHINT DefaultChar : Character/attribute pair used to fill the dialog box HintTextColor : Color of hint text, if any HintBackColor : Color of hint background color HintOrgX : Screen X Origin for hint window HintOrgY : Screen Y Origin for hint window HintWidth : Width of hint window BorderStyle : Type of border, if any BS_NOBORDER BS_SINGLELINE BS_DOUBLELINE BorderColor : Color of border line BorderBack : Color of border background DropShadow : The drop shadow identifier: DS_UPPERLEFT DS_UPPERRIGHT DS_LOWERRIGHT DS_LOWERLEFT DS_NONE DropAttr : The attribute to use for the background of the drop shadow. Title : Pointer to dialog box title string Control : Array of control types, terminated by a NULL Text field (See Below). The dialog box may then contain any number of controls, which are defined as: Text : Pointer to control text Style : control styles CSF_BUTTON CSF_TEXT CSF_DATAENTRY CSF_CHECKBOX CSF_ONOFBUTTON CSF_PICKLIST Flags : control type flags CSS_NOACTIVATE CSS_ACTIVATE CSS_CALLFUNC CSS_CALLDIALOG CSS_CALLMENU CSS_EXIT CSS_CALLNOTHING HotKey : Hot key to activate control OffsetHiLite : Offset into text for hilight XOrg : Window X origin for control YOrg : Window Y origin for control Height : Height of control Width : Width of control TextColor : Color of control text TextBack : Color of control text background HiTextColor : Color of hilighted text HiBackColor : Color of hilighted text background ActionPtr : Pointer to control action Hint : Pointer to hint text Validate : Pointer to a validation function, or NULL for none A Dialog Box is created by initializing the dialog structure and control item array. The last entry in the array must have a NULL Text field. For example, this dialog box is taken from the sample code: static DLG_CONTROL TestDialogControl[] = { "This is a text control", CSF_TEXT, CSS_NOACTIVATE | CSS_CALLNOTHING, 0, 0, 20, 2, 1, 22, YELLOW, BLUE, CYAN, BLUE, NULL, NULL, NULL, "Data Entry: ", CSF_DATAENTRY, CSS_ACTIVATE | CSS_CALLNOTHING, k_Alt_D, 0, 3, 4, 0, 0x1E0A, WHITE, BLUE, CYAN, BLUE, DataVar, "This is a data entry control", NULL, "Checkbox", CSF_CHECKBOX, CSS_ACTIVATE | CSS_CALLNOTHING, k_Alt_C, 3, 42, 4, 0, 0, WHITE, BLUE, BRIGHTWHITE, BLUE, &CheckVar, "This is a check box control", NULL, "OneOfButton1", CSF_ONEOFBUTTON, CSS_ACTIVATE | CSS_CALLNOTHING, k_Alt_O, 0, 22, 6, 0, 0, WHITE, BLUE, BRIGHTWHITE, BLUE, &OneOfVar, "This is a group of one-of buttons", NULL, "OneOfButton2", CSF_ONEOFBUTTON, CSS_ACTIVATE | CSS_CALLNOTHING, k_Alt_N, 1, 22, 7, 0, 1, WHITE, BLUE, BRIGHTWHITE, BLUE, &OneOfVar, "This is a group of one-of buttons", NULL, " <Exit> ", CSF_BUTTON, CSS_ACTIVATE | CSS_EXIT, k_Esc, 0, 26, 9, 0, 0, WHITE, RED, BRIGHTWHITE, RED, NULL, "This is a button control", NULL, NULL, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, NULL, "", NULL}; Notice that the last control is completely NULL. This terminates the array. static DIALOG TestDialog = { 10, 5, 13, 60, DBF_USEHINT, 0x1E20, YELLOW, BLUE, 11, 16, 58, BS_DOUBLELINE, YELLOW, BLUE, DS_LOWERRIGHT, 0x8, "Test Dialog Box", NULL, TestDialogControl }; This is the dialog box definition. Some of the fields in the DLG_CONTROL structure change depending on the control style. Each control is explained below. CSF_BUTTON The Push Button control is generally used to close a dialog box, or activate the next stage of a program. The Text field points to a string containing the text to be displayed on the button face, and the width of the button is determined from the string length. The Height and Width fields are ignored. CSF_TEXT The Text Control is a static text field, used for titles or other information which is not editable by the user. The text can be changed by the program, however, and any changes will be reflected on the dialog box. Text controls should always be marked with the CSS_NOACTIVATE flag, since they are not editable. The height and width fields specify the size of the control, but the text is always displayed one line high. CSF_DATAENTRY The data entry control allows the user to edit a string of text. The ActionPtr field should point to the string that holds the response. The high byte of the Width field specifies the number of characters that should be stored in the response string, and the low byte specifies how many should be displayed on the dialog box. For example, if the width field is 0x2010, then 0x10 (16) characters are displayed, but 0x20 (32) are stored in the string. The control scrolls automatically if the user types past the displayed width. CSF_CHECKBOX A check box is a toggle field, which changes from TRUE to FALSE to TRUE when selected. ActionPtr should point to an 'int' variable containing the flag. The Height and Width fields in the control structure are ignored. CSF_ONOFBUTTON The one-of button allows the user to select one option from a group of options. The ActionPtr for each button in the group should contain a pointer to the same 'int' variable, and the Width field should contain the option number for the button. When the button is selected, the value in the Width field is placed into the variable pointed to by ActionPtr. This allows the programmer to determine which button in the group was selected. The option numbers are arbitrary, and need not be consecutive. CSF_PICKLIST The picklist control determines how a picklist should be displayed on the dialog box. Unlike the standard dialog controls, the picklist control allows a separately defined picklist to be displayed on the dialog box. The picklist structure must first be defined (as though it were a standard picklist), and a pointer to it is placed in ActionPtr. The picklist will be handled internally, and will operate as though it were a dialog control. NOTE: In order for the mouse to function properly, you must specify a unique hot-key for each dialog control. Once the dialog box is active, Z-Forms displays all controls, then searches for the first control marked with the CSS_ACTIVATE flag. This control is hilighted, and is the current control. The hint window, if one is defined, is opened and the hint text for that control is displayed. The user may now cycle through the active controls using the TAB key. To activate a control, the user may press <SPACE> or <ENTER> when the control is hilighted, or press the hot key for the desired control. When the control is activated, the CSS_CALLXXXX flag is tested, and ActionPtr is used, as folows. If CSS_CALLFUNC is set, ActionPtr is assumed to point to a function, which is called. The function prototype should be void UserFunc(void);. If CSS_CALLDIALOG is set, ActionPtr is assumed to point to another dialog box, which is activated using Z_HandleDialog(...). If CSS_CALLMENU is set, ActionPtr is assumed to point to a menu, which is activated using Z_HandleMenu(...). If CSS_EXIT is set, the dialog box terminates, returning the number of the control which causes it. If CSS_CALLNOTHING is set, no action is taken. There is a pre-defined dialog box which may be used to inform the user of an event, or to ask a yes/no type question. Z_InformUser(...) takes 4 strings as input; A title, the box text, and two buttons. The box is centered on the physical screen. The box returns TRUE if button 1 is selected, or FALSE if button 2 is selected. If the text pointer for button 2 is NULL, then only one button (Button 1) is displayed, and it is centered. Prompts: A prompt sequence is a set of questions to the user which wait for a response. The logic for displaying these questions and recieving responses from the user is handled by Z-Forms, without intervention from the application program. Prompts are defined in a prompt structure array, terminated by a NULL Response, whose fields are as follows: Response : Pointer to the destination string Prompt : Pointer to the prompt text string Mask : Pointer to the data mask # - Any ascii character 9 - Numeric only U - Uppercase (converts lowercase) any other - literal Length : Maximum length of input or -1 for display only XPos : Window X Position for this prompt YPos : Window Y Position for this prompt PromptColor : Color for prompt PromptBack : Color for prompt background ResponseColor : Color of response ResponseBack : Color of response background HiColor : Color of response hilight HiBack : Color of response hilight background Verify : Pointer to verification function, or NULL for none Hint : Pointer to hint text A prompt sequence is initialized, and passed to Z_HandleInputs(...). This function displays all of the prompts and responses along with the hint, if any. The user navigates through the prompts by presing the up and down arrow keys, as well as the enter key. Note that any response with a Length field of -1 will be displayed, but can not be edited. Before Z-Forms will allow the user to move to another field the verification function is called (if Verify is not NULL). The verification function is an application-supplied function with the following form: int ValFunc(char *Line) The parameter 'Line' contains the data typed by the user. The function should return either TRUE (okay to move away from the field) or FALSE (stay in the field). This allows the application to verify that the data is valid before accepting it. To terminate the prompts, the user presses one of the ExitKeys passed to Z_HandleInputs. ExitKeys is an array of keys, terminated by k_NoKey. Z_HandleInputs returns the key used to terminate the function. Picklists: A Picklist is a vertical list of items which may be scrolled by the user to find a particular selection. The user may use the Escape key or Enter to either escape the picklist, or make a selection. A picklist is created by initializing a picklist structure, which has the following fields: OrgX : Screen X origin of dialog box OrgY : Screen Y origin of dialog box Height : PickList height Width : PickList width TextWidth : Width of picklist display area Flags : Picklist flags to select mouse scroll buttons PLF_NOSCROLL PLF_VERTSCROLL TextColor : Color of picklist text BackColor : Background color of the picklist HiTextColor : Color of highlighted text HiBackColor : Background color of highlighted text BorderStyle : Type of border, if any BS_NOBORDER BS_SINGLELINE BS_DOUBLELINE BorderColor : Color of border line BorderBack : Color of border background DefaultChar : character/attribute for the picklist background DropShadow : The drop shadow identifier: DS_UPPERLEFT DS_UPPERRIGHT DS_LOWERRIGHT DS_LOWERLEFT DS_NONE DropAttr : The attribute to use for the background of the drop shadow Title : Pointer to the picklist title pWin : Pointer to the window to display on Item : Pointer to the first PICKLIST_ITEM in the list LastItem : Pointer to the last PICKLIST_ITEM in the list The PICKLIST_ITEM structure is: ItemText : Pointer to the item's text Prev : Pointer to the previous list entry Next : Pointer to the next list entry. Once the picklist structure is initialized, items can be added to it by calling Z_AddPickListItem, or removed by calling either Z_RemovePickListItem or Z_RemovePickListEntry. To display the picklist, call Z_HandlePickList. This function displays the picklist on the window specified, and accepts keypresses from the user. The user may scroll up and down by using the up/down arrow keys. The user may escape the picklist by pressing Escape, in which case Z_HandlePickList returns NULL. The user may also select an entry by pressing Enter, in which case Z_HandlePickList returns the pointer to the picklist item. When you have finished with the picklist, you should free all of its memory by destroying it with Z_DestroyPickList. Mouse: Mouse support is implemented transparently in Z-Forms. Mouse events are handled internally, simulating keypresses. For example, clicking the mouse on a menu item simulates that menu item's hot key. For this reason, you should always use unique hot keys for dialog controls and menu items. If you do not, the mouse will behave erratically or select the wrong item. Sound: Sound may be produced from Z-Forms in two ways. You may use Z_Beep to generate a tone of any frequency and duration, or you may use Z_Alert to produce one of a set of predefined tone sequences. Background Processes: You may run a background process when Z-Forms is waiting for a keystroke. Use Z_SetBackgroundProcess to do this. You can specify the time interval between executions of the background process. Programming using Z-Forms: The Z-Forms header file ZFORMS.H contains prototype definitions for all Z-Forms functions, as well as definitions for other items, such as colors, keycodes, and flags. This file should be included in all source modules that make Z-Forms calls. In addition, the executable program should be linked with the Z-Forms library, which is a large model library (for those compilers supporting memory models). Z-Forms is written to generate OS/2 1.x or 2.x programs, or DOS-only programs. OS/2 1.X programs may be bound to run under either OS/2 or DOS. To bind using MSC6, build the program for OS/2 1.X using ZFORMS.LIB, then bind with ZFBIND.LIB. Form more information about binding, please see the READ.ME file. If the program is to be DOS only, you should link with both the ZFORMS and ZFDOS libraries, which contains DOS versions of the OS/2 VIO, KBD and DOS calls used by Z-Forms. (NOTE: The library names will depend on which compiler you are using) Please take a few minutes to examine the sample code. This is your best guide to how the various Z-Forms functions work. We hope that you find Z-Forms a powerful, yet easy to use screen management library. Z-Forms Compilation Macros There are two macros used to control the compilation of Z-Forms applications. The libraries are built using the correct macros, and the standard compilers (Microsoft, IBM, EMX/GCC and Borland) define them automatically. If you are using Z-Forms with another compiler, you may need to define these macros yourself. The first is __Z_INIT_EXT__ (two underbars before and after). This option controls how menu and dialog box controls are initialized. Both definitions have an unsized array in the structure, but some compilers do not support this. If so, define __Z_INIT_EXT__. If not, a separate array must be defined (see the sample code). The second macro is __Z_SECVID__. This option controls how the physical screen is updated by Z-Forms. If VioGetBuf and VioShowBuf are not supported, define __Z_SECVID__ and Z-Forms will use VioWrtCellStr instead. The option definitions for the standard compilers are: Microsoft C 6.0: __Z_INIT_EXT__ Borland C/C++ for DOS: __Z_SECVID__ IBM C/Set: __Z_SECVID__ Borland C/C++ for OS/2: __Z_SECVID__ EMX/GCC: __Z_SECVID__ Functions Reference: ************************************************************** WINDOW * Z_OpenWindow(WINDOW * pWin) pWin : Address of an initialized window structure This function defines and displays a window. Z_DefineWindow and Z_CreateWindow are called from here, so this is usually the only function that must be called to open a new window. Return Value: Pointer to the real window structure. ************************************************************** void Z_CloseWindow(WINDOW * pWin) pWin : pointer to the window structure to close This function hides the window and undefines it. This is usually the only function that must be called to close a window. Return Value: none ************************************************************** WINDOW * Z_CreateWindow(WINDOW * temp, int Height, int Width, int XOrg, int YOrg, int DefaultChar, int Border, int For, int Back, char *Title, char *SubTitle) temp : pointer to window structure to be defined Height : window height Width : window width XOrg : Physical X Origin on the screen YOrg : Physical Y origin DefaultChar : character to fill the window with Border : Border style identifier: BS_NOBORDER BS_DOUBLELINE BS_SINGLELINE For : Forground color Back : Background color DropShadow : Drop shadow identifier: DS_UPPERLEFT DS_UPPERRIGHT DS_LOWERRIGHT DS_LOWERLEFT DS_NONE DropAttr : Background attribute to use for the shadow Title : pointer to window title, or NULL for none SubTitle : pointer to window subtitle, or NULL for none This function fills a window structure from the data given. The window must then be defined and shown. This function would be used to create a window structure 'on the fly'. Return Value: Pointer to the filled window structure (temp) ************************************************************** WINDOW * Z_DefineWindow(WINDOW * pWin) pWin : pointer to window to define This function fills a new window structure with the data from pWin, initializes the window's virtual buffer, and returns the new window structure pointer. This pointer is different from the original pointer, so that several windows can be created from the same pWin structure. The window is initially hidden, and must be shown using Z_ShowWindow. This function does not need to be used if Z_OpenWindow is used. Return Value: Pointer to the real window structure ************************************************************** void Z_UnDefineWindow(WINDOW * pWin) pWin : window to undefine This function removes the window from the linked window list, and hides it. All memory allocated for the window's virtual buffers is freed. Return Value: none ************************************************************** void Z_HideWindow(WINDOW * pWin) pWin : Window to hide This function makes the window non-displayable, but does not destroy it. The window may still be written to, but it will not be visible until Z_ShowWindow is called. Return Value: none ************************************************************** void Z_ShowWindow(WINDOW * pWin) pWin : Window to show This function causes a hidden window to be displayed, and must be called after a new window is defined, as all new windows are initially hidden. If Z_OpenWindow is used, this function does not need to be called. Return Value: none ************************************************************** void Z_PushWindow(WINDOW * pWin) pWin : Window to push This function pushes a window to the back of the screen, placing it behind all other windows. The window is still visible (except for the parts that are covered by other windows), and will still be updated if written to. Return Value: none ************************************************************** void Z_PopWindow(WINDOW * pWin) pWin : Window to show This function pops a window to the front of the screen, placing it in front of all other windows. Return Value: none ************************************************************** int Z_GetCharOnTop(WINDOW * pWin, int x, int y) pWin : Window to show x : X-Coordinate of the character y : Y-Coordinate of the character This function is used internally to determine what character is visible at this physical screen location. It should never be needed by the programmer, but is documented on the chance that someone may find it useful. The x and y coordinates are with respect to the window. The return value is the character that the user sees at that position (from the top-most window). Return Value: Character/Attribute pair of the top character ************************************************************** void Z_UpdatePhysicalScreen(WINDOW * pWin, int x0, int y0, int Wid, int Ht) pWin : Window to show x0 : X-Coordinate of the region y0 : Y-Coordinate of the region Wid : Width of the region Ht : Height of the region This function is used internally to update the physical display from the virtual screen buffers. It should never be needed by the programmer, but is documented on the chance that someone may find it useful. The rectangle defined by x0,y0 and Wid/Ht is displayed on the physical screen (x0 and y0 are with respect to the window pWin). For each character in the region, Z_GetCharOnTop is used to find the actual visible character. Return Value: none ************************************************************** void Z_TextOut(WINDOW *pWin, char * text, int X, int Y, int For, int Back) pWin : window pointer to display on text : pointer to text to display X : local window X co-ordinate to display on Y : local window Y co-ordinate to display on For : forground color to use, or attribute byte if Back is -1 Back : background color to use, or -1 This function displays the text in 'text' at the co-ordinates (X,Y) on the window. The text is displayed using the foreground and background colors given. Return Value: none ************************************************************** void Z_TextOver(WINDOW * pWin, char * text, int LocalX, int LocalY) pWin : window to display text on text : pointer to text X : local X co-ordinate to use Y : local Y co-ordinate to use This function displays the text in 'text' on the window without changing the color or attribute at the position. Return Value: none ************************************************************** void Z_CharOut(WINDOW *pWin, char text, int X, int Y, int For, int Back) pWin : window pointer to display on text : character to display X : local window X co-ordinate to display on Y : local window Y co-ordinate to display on For : forground color to use, or attribute byte if Back is -1 Back : background color to use, or -1 This function displays the character in 'text' at the co-ordinates (X,Y) on the window. The text is displayed using the foreground and background colors given. Return Value: none ************************************************************** void Z_CharOver(WINDOW * pWin, char text, int LocalX, int LocalY) pWin : window to display text on text : character to display X : local X co-ordinate to use Y : local Y co-ordinate to use This function displays the character in 'text' on the window without changing the color or attribute at the position. Return Value: none ************************************************************** void Z_CharOutAtCursor(WINDOW *pWin, char text, int For, int Back) pWin : window pointer to display on text : character to display For : forground color to use, or attribute byte if Back is -1 Back : background color to use, or -1 This function displays the character in 'text' at the co-ordinates of the cursor. The cursor must be within the specified window. The text is displayed using the foreground and background colors given. Return Value: none ************************************************************** void Z_CharOverAtCursor(WINDOW * pWin, char text) pWin : window to display text on text : character to display This function displays the character in 'text' on the window at the current cursor position without changing the color or attribute at the position. The cursor must be within the specified window. Return Value: none ************************************************************** void Z_CharOutTTY(WINDOW *pWin, char text, int For, int Back) pWin : window pointer to display on text : character to display For : forground color to use, or attribute byte if Back is -1 Back : background color to use, or -1 This function displays the character in 'text' at the current cursor position, then increments the cursor one column to the right. If the cursor has reached the right edge of the window, the cursor is moved to the start of the next line. If the cursor has moved beyond the last row, the window is scrolled up one line. The cursor must be on the specified window. The text is displayed using the foreground and background colors given. Return Value: none ************************************************************** void Z_CharOverTTY(WINDOW * pWin, char text) pWin : window to display text on text : character to display This function displays the character in 'text' at the current cursor position, then increments the cursor one column to the right. If the cursor has reached the right edge of the window, the cursor is moved to the start of the next line. If the cursor has moved beyond the last row, the window is scrolled up one line. The cursor must be on the specified window. The text is displayed without changing the color or attribute at the position. Return Value: none ************************************************************** void Z_ClearScreen(char Character, char Attribute) This function clears the screen, filling it with the given character at the given attribute. Return Value: none ************************************************************** void Z_GetVideoMode(void) This function determines the number of rows and columns for the current display mode, and puts them in the Z-Forms global variables 'Z_ScreenWidth' and 'Z_ScreenHeight'. Return Value: none ************************************************************** void Z_SetVideoMode(int Rows, int Cols) Rows : Number of rows to set Cols : Number of columns to set This function attempts to set the display mode to the number of rows and columns specified. Note that the operating system may not allow the row/column count specified. Regardless of the outcome, the Z-Forms global variables 'Z_ScreenWidth' and 'Z_ScreenHeight' will be set to the actual number of rows and columns. Return Value: none ************************************************************** void Z_ScrollUp(WINDOW *pWin, int Lines) pWin : pointer to window Lines : Number or lines to scroll This function scrolls the contents of the specified window up one line. Return Value: none ************************************************************** void Z_ScrollDown(WINDOW *pWin, int Lines) pWin : pointer to window Lines : Number or lines to scroll This function scrolls the contents of the specified window down one line. Return Value: none ************************************************************** void Z_ClearWindow(WINDOW *pWin) pWin : pointer to window to clear This function clears the window by setting all characters to the default character. Return Value: none ************************************************************** void Z_Beep(unsigned int Freq, unsigned int Dur) Freq : Frequency of the tone, or 0 for a delay only Dur : Duration of the tone This function sounds the speaker at the specified frequency, and for the specified length of time. Return Value: none ************************************************************** void Z_Alert(int Alert) Alert : Identifier of the alert to use ALERT_THREEBEEP ALERT_TWOTONES ALERT_PING ALERT_WARNING This function sound the speaker with a predefined sequence of tones. Return Value: none ************************************************************** void Z_SetCursor(WINDOW *pWin, int X, int Y) pWin : pointer to window X : X offset for cursor Y : Y offset for cursor This function moves the hardware cursor to the position specified by (X,Y) on the designated window. Return Value: none ************************************************************** void Z_GetCursor(WINDOW *pWin, int *X, int *Y) pWin : pointer to window X : pointer to X offset for cursor Y : pointer Y offset for cursor This function retrieves the coordinates of the hardware cursor with respect to the specified window. The values are placed in X and Y. Return Value: none ************************************************************** void Z_MoveCursorCol(WINDOW *pWin, int Delta) pWin : pointer to window Delta : number of columns to move the cursor This function moves the cursor along the current row by the specified number of columns. If the cursor would be moved past the edge of the window, it will be set to the edge. Return Value: none ************************************************************** int Z_HandleMenu(MENU *pMenu) pMenu : Pointer to the menu to use This function handles all menu processing for the designated menu. The menu structure is predefined, and includes support for nested menus, vertical menus, and horizontal menus. For more information, see the MENU structure documentation. In most cases, this is the only menu function that will need to be called. Return Value: none ************************************************************** void Z_DisplayMenuSelection(MENU *pMenu, WINDOW *pWin, int Item, int fHilite) pMenu : Pointer to the menu to use pWin : Window that the menu is displayed on Item : Item number to display fHilite : Flag indicating whether the item is selected This function should not generally be needed by the programmer, but is included in case it turns out to be useful. The function updates the menu text for the menu item selected by Item. If fHilite is true, the hilighted colors ase used, otherwise the standard colors are used. Return Value: none ************************************************************** int Z_CountMenuItems(MENU *pMenu) pMenu : Pointer to the menu to use This function returns the number of items in the menu structure pointed to by pMenu. Return Value: The number of items in the menu ************************************************************** int Z_HandleDialog(DIALOG * pDialog) pDialog : pointer to dialog box structure This function handles all processing for the dialog box. The dialog box structure is predefined, and supports buttons and text. For more information, see the DIALOG structure documentation. Return Value: the control number which terminated the dialog box ************************************************************** int Z_InformUser(char * Title, char * Text, char * Button1, char * Button2) Title : Pointer to the title of the inform box Text : Pointer to the text to display in the box Button1 : Pointer to the text for Button 1 Button2 : Pointer to the text for Button 2, or NULL for none This function implements a pre-defined dialog box for informing the user or asking a yes/no type question. The title and text are centered on the window, which is centered on the physical display. If two buttons are defined, they are displayed against the sides of the box, and if only one button is defined, it is centered. Return Value: 1 if Button 1 is pressed, 0 if Button 2 is pressed ************************************************************** int Z_CountDialogItems(DIALOG *pDlg) pDlg : Pointer to the dialog box structure This function counts the number of dialog items in the dialog box structure. Return Value: The number of dialog items ************************************************************* int Z_GetKey(void) This function waits for a key to be pressed, and returns it. The keys are defined in the header file. If there is a background function defined, it is called as long as there is no keypress (See Z_SetBackgroundProcess). The key codes are listed in ZFORMS.H Return Value: key pressed ************************************************************** void Z_Delay(int Milli) Milli : Number of milliseconds to delay This function pauses the program for the specified number of milliseconds. This function is included for the benefit of DOS programs which do not have DosSleep. Return Value: none ************************************************************** int Z_HandleInputs(WINDOW * pWin, WINDOW * pHintWin, PROMPT * Tmp, int * ExitKeys) pWin : pointer to window structure to display on pHintwin : pointer to hint window Tmp : prompt structure ExitKeys : array of keys used to exit This function handles all keyboard input for a prompt structure. The structure is predefined with all prompts and positions, then this funxtion prompts the user to fill all of the fields. The function exits when one of the keys listed in the ExitKeys list is pressed. For more information, see the PROMPT structure documentation. Return Value: the Exit Key pressed ************************************************************** int Z_SetBackgroundProcess(void (*pFunc)(void), int Milli) pFunc : pointer to the function to execute Milli : number of milliseconds to delay This function sets up a background function for execution when the program is waiting for a keystroke. If the function pointer is NULL, no function is executed (This is the default). Return Value: none ************************************************************** int Z_AddPickListItem(PICKLIST *pPickList, char * Text) pPickList : pointer to picklist to use Text : pointer to text string to add This function handles adds a text string to a picklist. The string is linked in to the end of the list. Return Value: 1 if the function was successful, 0 otherwise ************************************************************** int Z_RemovePickListItem(PICKLIST *pPickList, char * Text) pPickList : pointer to picklist to use Text : pointer to text string to remove This function handles removes a text string from a picklist. The picklist item is found by matching the text to the picklist items. Return Value: 1 if the function was successful, 0 otherwise ************************************************************** int Z_RemovePickListEntry(PICKLIST *pPickList, PICKLIST_ITEM **pPLI) pPickList : pointer to picklist to use pPLI : pointer to the picklist item to remove This function handles removes a picklist item from the list. Return Value: 1 if the function was successful, 0 otherwise ************************************************************** void Z_DestroyPickList(PICKLIST *pPickList) pPickList : pointer to picklist to destroy This function destroys all picklist items and frees all memory. Return Value: none ************************************************************** void Z_PurgePickList(PICKLIST *pPickList) pPickList : pointer to picklist to purge This function destroys all picklist items, leaving a blank picklist. Return Value: none ************************************************************** PICKLIST_ITEM * Z_HandlePickList(PICKLIST *pPickList) pPickList : pointer to picklist to use This function handles a picklist. The picklist is displayed with the first item highlighted. The user may use the up and down arrow keys to manuever the list. Pressing enter causes the list to exit, returning a pointer to the selected item, while pressing escape returns NULL. Return Value: a pointer to the selected PICKLIST_ITEM structure if ENTER is pressed, or NULL if ESCAPE is pressed. ************************************************************** void Z_InsertKey(int Key) Key : keyboard character to insert This function causes the character in Key to be inserted into the keyboard stream, as though the user had typed it. The character may be an ASCII character (such as '0' or 's'), or one of the pre-defined Z-Forms key definitions (such as k_Alt_F6). Return Value: none ************************************************************** void Z_InsertKeyString(char *Keys) Keys : pointer to string insert This function causes the characters in the string pointed to by Keys to be inserted into the keyboard stream, as though the user had typed them. The character must be ASCII (such as "Ab23"). Return Value: none REGISTERING Z-FORMS =================== To register Z-Forms, simply print out this form, fill it in, and mail it along with a check. Registration is $35 US for the libraries, or $65 for a source code registration (add $1.00 for orders outside the US) made out to "Z-Space". Checks from Canadian banks must include an extra $5 to cover exchange costs. Z-Space 4278 W. 223rd Street Cleveland, Ohio 44126 Name: ____________________________________________ Address: ____________________________________________ ____________________________________________ City/State: _________________________________________ Phone (optional) Home: _____________ Work: ________________ EMail addresses:_____________________________________ Registration: [ ] Library ($35) [ ] Library + Source ($65) Compiler you are using Z-Forms with:_________________ Where did you get your copy of Z-Forms?:_____________ Are you interested in any other Z-Forms related tools (screen editors, code generators, etc)? Please specify: _____________________________________________________ ============================================================= Comments or suggestions? (please print below and/or on back)