OS/2 Professional

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

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / zforms / zforms.doc < prev next >

Wrap

Text File | 1993-05-24 | 41.9 KB | 1,098 lines

Z-Forms Screen Management Libraries Users Guide (C) 1993, Z-Space All Rights Reserved Z-Forms Screen Management Libraries Zforms Philosophy: Zforms 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, and data input support. Zforms 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 flexibility and power. Zforms 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. Zforms Overview: The programmer (that would be you) specifies the content and look of any desired windows, dialog boxes, menus, etc. by declaring and initializing structures in the source code. Once defined, Zforms 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 and functionality and Zforms handles the rest! It is our hope that Zforms 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. 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 file that matches your compiler: Microsoft C 6.0 : MSC600 IBM C/Set : CSET Borland C/C++ for OS/2 : BCOS2 Borland C/C++ V2.0/V3.0 : BORLANDC Then, simply add the header file Z-Forms.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. Zforms Object Types: There are five basic object types in Zforms. Each is defined by initializing appropriate stuctures. The number of Zforms 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 telling Zforms about it. Zforms 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_ClearWindow. Initialize to zero. Height : Window height Width : Window width Prev : Pointer to the previous window (maintained by ZForms). Initialize to NULL. Next : Pointer to the next window (maintained by ZForms). 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. BorderStyle: The border style identifier: BS_NOBORDER BS_SINGLELINE BS_DOUBLELINE BorderColor: The border foreground color (See ZFORMS.H) 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. 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 either Z_TextOut or Z_TextOver. Z_TextOut writes text at the specified window co-ordinates using the designated colors. Z_TextOver writes the text using the pre-existing window colors. 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 Zforms; 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 | ): 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 NULL ActionPtr (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 OffsetHiLite:Offset into item text to hilight, or -1 for none XOrg : X position of item within window YOrg : Y position of item within window ActionPtr: Pointer to the next action Hint : Pointer to hint text 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. 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 menu then allows the user to select the desired menu choice by using the arrow keys, or by pressing the hot key for the item. When the user selects the menu item, Zforms 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. 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. The sample code contains an example of both a horizontal and vertical 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 box title string Control : Array of control types, terminated by a NULL ActionPtr 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 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 generaly 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 selec one option from a group of option. 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. Once the dialog box is active, ZForms 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 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. 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 questions are answered without intervention from 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 (convert lowercase) any other - literal Length : Maximum length of input 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. Before Zforms will allow the user to move to another field, however, the verification function is called (if Verify is not NULL). The verification function is an application-supplied function which recieves the response and returns either TRUE (okay to move) 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 : There are no picklist flags at this time (initialize to zero) 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. 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 use 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. OS/2 1.X programs may be bound to run under either OS/2 or DOS. If the program is to be DOS only, you should also link with the ZFDOS library, which contains DOS versions of the OS/2 VIO, KBD and DOS calls used by Z-Forms. When binding programs using Z-Forms, be sure to specify the following command line option: /N VIOGETBUF VIOSHOWBUF This option is required because those two functions are not family mode functions. They are not called if the machine is in real mode. Please take a few minutes to examine the sample code, to see how the various 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 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__ Functions Refernce: ************************************************************** 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'. You could also assign the data yourself, but this saves some code space. 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 determines the visible character at a specific position on a window. 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. Strings are built for each row, which are displayed. 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 Back : background color to use 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_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_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 ************************************************************** 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. 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 (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:_____________________________________ 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)