home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1993 #2 / Image.iso / os2 / zfrms100.zip / ZFORMS.DOC < prev    next >
Text File  |  1993-05-24  |  43KB  |  1,098 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.                      Z-Forms Screen Management Libraries
  30.                                 Users Guide
  31.  
  32.  
  33.  
  34.  
  35.  
  36.                             (C) 1993, Z-Space
  37.                            All Rights Reserved
  38.  
  39.  
  40. Z-Forms Screen Management Libraries
  41.         
  42. Zforms Philosophy:
  43.  
  44.     Zforms is a powerful tool that assists programmers in        
  45. producing applications with a fast, text-mode, windowed        
  46. user interface.  The package features built-in        
  47. windowing, menuing, dialog boxes, and data input support.        
  48.     Zforms is intended to be easy to use, utilizing a minimal 
  49. set of function calls.  However, ease-of-use is not achieved at 
  50. the expense of flexibility and power.  Zforms allows the 
  51. programmer to configure every parameter that effects the way 
  52. the program screen looks, and contains many built-in features 
  53. to handle a wide variety of user-interface tasks.
  54.  
  55. Zforms Overview:
  56.  
  57.     The programmer (that would be you) specifies the content 
  58. and look of any desired windows, dialog boxes, menus, etc. by 
  59. declaring and initializing structures in the source code.  Once 
  60. defined, Zforms handles the screen configuration and drives the 
  61. program flow based on user interaction.  Application functions, 
  62. menus, dialog boxes, etc.  can be specified to be the results 
  63. of button presses or menu selections.  For example, you might 
  64. define a menu with three items;  the first might call another 
  65. menu, the second a dialog box, and the third a function.  The 
  66. programmer provides the desired structure and functionality and 
  67. Zforms handles the rest!
  68.     It is our hope that Zforms will cut down your programming 
  69. time and provide robust handling of the user interface.
  70.  
  71.  
  72. This IS a shareware package, and does require a registration 
  73. fee if you choose to continue using it after 30 days.  The 
  74. registration fee is currently $35 US.  When you register, you 
  75. will be sent the latest "registered" version of Z-Forms.
  76.           
  77. ---------------------------------------------------------------
  78.  
  79. IMPORTANT: READ THE READ.ME FILE FOR NEW FEATURES AND BUG FIXES
  80.          
  81. ---------------------------------------------------------------
  82.  
  83. DISCLAIMER OF WARRANTY
  84. ======================
  85. THIS SOFTWARE AND MANUAL ARE DISTRIBUTED AND SOLD "AS IS" AND 
  86. WITHOUT WARRANTIES AS TO PERFORMANCE OF MERCHANTABILITY OR ANY 
  87. OTHER WARRANTIES WHETHER EXPRESSED OR IMPLIED.  BECAUSE OF THE 
  88. VARIOUS HARDWARE AND SOFTWARE ENVIRONMENTS INTO WHICH THIS 
  89. PROGRAM MAY BE PUT, NO WARRANTY OF FITNESS FOR A PARTICULAR 
  90. PURPOSE IS OFFERED.
  91.  
  92. GOOD OPERATING PROCEDURE DICTATES THAT ANY PROGRAM BE 
  93. THOROUGHLY TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT.  
  94. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM.  ANY 
  95. LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT 
  96. REPLACEMENT OR REFUND OF PURCHASE PRICE. 
  97.  
  98.  
  99. Installing Z-Forms:
  100.  
  101. Unpack the distribution file into an appropriate directory (for 
  102. example, C:\ZFORMS).  Then unpack the library files from the 
  103. library file that matches your compiler:
  104.     Microsoft C 6.0            :    MSC600
  105.     IBM C/Set                :    CSET
  106.     Borland C/C++ for OS/2    :    BCOS2
  107.     Borland C/C++ V2.0/V3.0    :    BORLANDC
  108.  
  109. Then, simply add the header file Z-Forms.H to any source files 
  110. that will make Z-Forms calls, and link with the libraries.  For 
  111. more information about using Z-Forms with your compiler, please 
  112. read the READ.ME file.
  113.  
  114.  
  115.  
  116. Zforms Object Types:
  117.     There are five basic object types in Zforms.  Each is 
  118. defined by initializing appropriate stuctures.  The number of 
  119. Zforms objects allowed is determined by available memory.
  120.  
  121.     WINDOW:
  122.     A Window is a rectangular region, with configurable size, 
  123. position, border, drop shadow, titles, colors, etc.  You can 
  124. have as many windows overlapping on the screen as you want. 
  125. Each window is maintained in memory as a complete virtual 
  126. screen, and the physical screen is generated by determining 
  127. which parts of each window are visible, and displaying them.  
  128. All windows can be written to, and any visible parts will be 
  129. updated on the screen.
  130.                 
  131.     DIALOG BOX:
  132.     A special window that can have groups of controls (buttons, 
  133. checkboxes, one-of-buttons, data entry fields, etc.) used to 
  134. request user input.
  135.  
  136.     MENU:
  137.     A vertical or horizontal group of selections.  Each menu 
  138. option can be used to select another menu, dialog box, or 
  139. function, or to exit the menu.
  140.  
  141.     PROMPT:
  142.     A Prompt is a group of data entry fields on a window.  Each 
  143. field may have a data mask and a verification function and 
  144. allows editing.
  145.  
  146.     PICKLIST:
  147.     A vertical list of items, scrolled by the up/down arrow 
  148. keys, that allows the user to select an item from a group of 
  149. items.
  150.  
  151.  
  152. Using Z-Forms
  153.  
  154.     Windows:
  155.  
  156.     A Window is defined by initializing a window structure, and 
  157. telling Zforms about it.  Zforms maintains a virtual screen 
  158. buffer for the window in memory, and updates the display from 
  159. it.
  160.  
  161.     The window structure contains the following fields:
  162.     fShown    :    Flags whether the window is visible or not.
  163.                 This field should not be directly manipulated,
  164.                 but is set and cleared by Z_ShowWindow and
  165.                 Z_ClearWindow.  Initialize to zero.
  166.     Height    :    Window height
  167.     Width    :    Window width
  168.     Prev        :    Pointer to the previous window (maintained by
  169.                 ZForms).  Initialize to NULL.
  170.     Next        :    Pointer to the next window (maintained by
  171.                 ZForms).  Initialize to NULL.
  172.     XOrg        :    X co-ordinate on the screen of the left edge
  173.                 of the window (0 based)
  174.     YOrg        :    Y co-ordinate on the screen of the top edge of
  175.                 the window (0 based)
  176.     DefaultChar:    a character/attribute pair used to fill the
  177.                 window when initially opened.  The high byte
  178.                 is the attribute, the low byte the character.
  179.     BorderStyle:    The border style identifier:
  180.                     BS_NOBORDER
  181.                     BS_SINGLELINE
  182.                     BS_DOUBLELINE
  183.     BorderColor:    The border foreground color (See ZFORMS.H)
  184.     BorderBack:    The border background color
  185.     DropShadow:    The drop shadow identifier:
  186.                     DS_UPPERLEFT
  187.                     DS_UPPERRIGHT
  188.                     DS_LOWERRIGHT
  189.                     DS_LOWERLEFT
  190.                     DS_NONE
  191.     DropAttr    :    The attribute to use for the background of the
  192.                 drop shadow (DARKGREY is good).
  193.     Title    :    Pointer to the title character string.  The
  194.                 title is centered on the top line of the
  195.                 window.  If this parameter is NULL, no title
  196.                 will be displayed.
  197.     SubTitle    :    Pointer to the subtitle character string.  The
  198.                 subtitle is centered on the bottom line of the
  199.                 window.  If this parameter is NULL, no
  200.                 subtitle will be displayed.
  201.                 
  202.     pVS        :    Pointer to the virtual screen buffer. 
  203.                 Initialize to NULL.
  204.  
  205.     Note: Prev, Next, and pVS should be initialized to NULL.
  206.     fShown should be initialized to 0.
  207.  
  208.  
  209.     There are three methods to create a window.  In method 1, a 
  210. predefined window structure is used, and all processing is 
  211. handled internally:
  212.         Z_OpenWindow(...);
  213. This is the simplest method, assuming that the window structure 
  214. was known or can be initialized.  All of the windows in the 
  215. sample code are opened using Z_OpenWindow.  Method 2 involves 
  216. creating a window structure, defining the window, then showing 
  217. it.  The code for this would be similar to:
  218.         Z_CreateWindow(...);
  219.         Z_DefineWindow(...);
  220.         Z_ShowWindow(...);
  221. This method would only be used when a window had to be created 
  222. on-the-fly, but even then you could probably use a pre-defined 
  223. structure, and simply change the fields.
  224.     Method 3 also uses a predefined window structure, which is 
  225. defined and shown:
  226.         Z_DefineWindow(...);
  227.         Z_ShowWindow(...);
  228.  
  229.     Once the window is open, you may write to it using either 
  230. Z_TextOut or Z_TextOver.  Z_TextOut writes text at the 
  231. specified window co-ordinates using the designated colors.  
  232. Z_TextOver writes the text using the pre-existing window 
  233. colors. The window may be hidden, if necessary, by calling 
  234. Z_HideWindow.  If the window is hidden, it may be shown using 
  235. Z_ShowWindow.  Finally, you may push a window to the 'back' of 
  236. the screen using Z_PushWindow, or make a window the 'top' 
  237. window using Z_PopWindow.
  238.  
  239.  
  240.     Menus:
  241.     There are two types of menus available in Zforms; Vertical 
  242. and Horizontal.  The menu is created by defining a menu 
  243. structure, as follows:
  244.     OrgX        :    Menu X origin on the physical display
  245.     OrgY        :    Menu Y origin on the physical display
  246.     Height    :    Menu window height (1 for horizontal)
  247.     Width    :    Menu window width
  248.     TextWidth:    The width of the menu text for a vertical
  249.                 menu.  This field determines the width of the
  250.                 highlight bar.
  251.     Flags    :    Menu Flags (may be combined with | ):
  252.                 MMF_VERTMENU
  253.                 MMF_HORIZMENU
  254.                 MMF_USEHINT
  255.                 MMF_NOHINT
  256.     TextColor:    Color of menu text
  257.     BackColor:    Color of menu text background
  258.     HotColor    :    Color of hot key letter
  259.     HotBack    :    Color of hot key letter background
  260.     HiTextColor:    Color of highlighted text
  261.     HiBackColor:    Color of highlighted text background
  262.     HintTextColor:Color of hint text
  263.     HintBackColor:Color of hint background
  264.     HintOrgX    :    Screen X origin for hint window
  265.     HintOrgY    :    Screen Y origin for hint window
  266.     HintWidth:    Width of hint window
  267.     BorderStyle:    Border style identifier:
  268.                 BS_NOBORDER
  269.                 BS_SINGLELINE
  270.                 BS_DOUBLELINE
  271.     BorderColor:    Color for border line, if any
  272.     BorderBack:    background color for border
  273.     DropShadow:    The drop shadow identifier:
  274.                 DS_UPPERLEFT
  275.                 DS_UPPERRIGHT
  276.                 DS_LOWERRIGHT
  277.                 DS_LOWERLEFT
  278.                 DS_NONE
  279.     DropAttr    :    The attribute to use for the background of the
  280.                 drop shadow
  281.     Title    :    Pointer to title character string, or NULL for
  282.                 none
  283.     Item[]    :    Array of menu items, terminated by a NULL
  284.                 ActionPtr (see below)
  285.  
  286.  
  287. A menu item has the following structure:
  288.     Text        :    Pointer to menu item text string
  289.     Flags    :    Menu item flags:
  290.                     MIF_USEHINT
  291.                     MIF_NOHINT
  292.                     MIF_CALLMENU
  293.                     MIF_CALLDIALOG
  294.                     MIF_CALLFUNC
  295.                     MIF_CALLNOTHING
  296.                     MIF_RIGHTJUST
  297.                     MIF_LEFTJUST
  298.                     MIF_SUBMENU
  299.                     MIF_NOSUBMENU
  300.     HotKey    :    Key press to activate this item
  301.     OffsetHiLite:Offset into item text to hilight, or -1 for
  302.                 none
  303.     XOrg        :    X position of item within window
  304.     YOrg        :    Y position of item within window
  305.     ActionPtr:    Pointer to the next action
  306.     Hint        :    Pointer to hint text
  307.  
  308.     After initializing the menu structure, call 
  309. Z_HandleMenu(...).  This function handles all menu processing.  
  310. If the menu is a horizontal menu, a window is created which is 
  311. 'Height' characters high and 'Width' wide.  The items are 
  312. displayed across the menu according to the XOrg parameter.  If 
  313. the menu is a vertical menu, a window is created using the 
  314. Height and Width parameters.  There can be extra space around 
  315. the actual menu items, if necessary.  There can also be a 
  316. border and title around the window.
  317.     If MMF_USEHINT is set, a hint window is also created, and 
  318. the hint text is displayed for each item, as the user selects 
  319. it.  
  320.     The menu then allows the user to select the desired menu 
  321. choice  by using the arrow keys, or by pressing the hot key for 
  322. the item.  When the user selects the menu item, Zforms checks 
  323. the MIF_CALLXXXX flag to determine what to do next.  If 
  324. MIF_CALLMENU is set, then Z_HandleMenu is called, and ActionPtr 
  325. is assumed to point to another menu structure.  This allows 
  326. nested menus and submenus, pulldown menus, etc.  If 
  327. MIF_CALLDIALOG is set, ActionPtr is assumed to point to a 
  328. dialog box structure, and Z_HandleDialog is called.  If 
  329. MIF_CALLFUNC is set, ActionPtr is assumed to point to a 
  330. function, and the function is called.  If MIF_CALLNOTHING is 
  331. set, no action occurs when the menu item is selected.  The 
  332. Escape key or an item with MIF_CALLEXIT exits the menu.  The 
  333. sample code contains an example of both a horizontal and 
  334. vertical menu.
  335.  
  336. Dialog Boxes:
  337.     A dialog box is defined by initializing a dialog box 
  338. structure and calling Z_HandleDialog(...).  The fields of the 
  339. structure are:
  340.         XOrg    : Screen X origin of dialog box
  341.         YOrg    : Screen Y origin of dialog box
  342.         Height  : Dialog box height
  343.         Width   : Dialog box width
  344.         Flags   : Dialog box flags
  345.                     DBF_USEHINT
  346.                     DBF_NOHINT
  347.         DefaultChar : Character/attribute pair used to fill the
  348.                  dialog box
  349.         HintTextColor : Color of hint text, if any
  350.         HintBackColor : Color of hint background color
  351.         HintOrgX : Screen X Origin for hint window
  352.         HintOrgY : Screen Y Origin for hint window
  353.         HintWidth : Width of hint window
  354.         BorderStyle : Type of border, if any
  355.                     BS_NOBORDER
  356.                     BS_SINGLELINE
  357.                     BS_DOUBLELINE
  358.         BorderColor : Color of border line
  359.         BorderBack : Color of border background
  360.         DropShadow : The drop shadow identifier:
  361.                     DS_UPPERLEFT
  362.                     DS_UPPERRIGHT
  363.                     DS_LOWERRIGHT
  364.                     DS_LOWERLEFT
  365.                     DS_NONE
  366.         DropAttr : The attribute to use for the background of
  367.                   the drop shadow.
  368.         Title   : Pointer to box title string
  369.         Control : Array of control types, terminated by a NULL
  370.                  ActionPtr
  371.  
  372.  
  373. The dialog box may then contain any number of controls, which 
  374. are defined as:
  375.         Text    : Pointer to control text
  376.         Style   : control styles
  377.                 CSF_BUTTON
  378.                 CSF_TEXT
  379.                 CSF_DATAENTRY
  380.                 CSF_CHECKBOX
  381.                 CSF_ONOFBUTTON
  382.                 CSF_PICKLIST
  383.         Flags   : control type flags
  384.                 CSS_NOACTIVATE
  385.                 CSS_ACTIVATE
  386.                 CSS_CALLFUNC
  387.                 CSS_CALLDIALOG
  388.                 CSS_CALLMENU
  389.                 CSS_EXIT
  390.                 CSS_CALLNOTHING
  391.         HotKey  : Hot key to activate control
  392.         OffsetHiLite : Offset into text for hilight
  393.         XOrg    : Window X origin for control
  394.         YOrg    : Window Y origin for control
  395.         Height  : Height of control
  396.         Width   : Width of control
  397.         TextColor : Color of control text
  398.         TextBack : Color of control text background
  399.         HiTextColor : Color of hilighted text
  400.         HiBackColor : Color of hilighted text background
  401.         ActionPtr : Pointer to control action
  402.         Hint    : Pointer to hint text
  403.  
  404.     Some of the fields in the DLG_CONTROL structure change 
  405. depending on the control style.  Each control is explained 
  406. below.
  407.     CSF_BUTTON
  408.     The Push Button control is generaly used to close a dialog 
  409. box, or activate the next stage of a program.  The Text field 
  410. points to a string containing the text to be displayed on the 
  411. button face, and the width of the button is determined from the 
  412. string length.  The Height and Width fields are ignored.
  413.     CSF_TEXT
  414.     The Text Control is a static text field, used for titles or 
  415. other information which is not editable by the user.  The text 
  416. can be changed by the program, however, and any changes will be 
  417. reflected on the dialog box.  Text controls should always be 
  418. marked with the CSS_NOACTIVATE flag, since they are not 
  419. editable.  The height and width fields specify the size of the 
  420. control, but the text is always displayed one line high.
  421.  
  422.  
  423.     CSF_DATAENTRY
  424.     The data entry control allows the user to edit a string of 
  425. text.  The ActionPtr field should point to the string that 
  426. holds the response.  The high byte of the Width field specifies 
  427. the number of characters that should be stored in the response 
  428. string, and the low byte specifies how many should be displayed 
  429. on the dialog box.  For example, if the width field is 0x2010, 
  430. then 0x10 (16) characters are displayed, but 0x20 (32) are 
  431. stored in the string.  The control scrolls automatically if the 
  432. user types past the displayed width.
  433.  
  434.     CSF_CHECKBOX
  435.     A check box is a toggle field, which changes from TRUE to 
  436. FALSE to TRUE when selected.  ActionPtr should point to an 
  437. 'int' variable containing the flag.  The Height and Width 
  438. fields in the control structure are ignored.
  439.  
  440.     CSF_ONOFBUTTON
  441.     The one-of button allows the user to selec one option from 
  442. a group of option.  The ActionPtr for each button in the group 
  443. should contain a pointer to the same 'int' variable, and the 
  444. Width field should contain the option number for the button.  
  445. When the button is selected, the value in the Width field is 
  446. placed into the variable pointed to by ActionPtr.  This allows 
  447. the programmer to determine which button in the group was 
  448. selected.  The option numbers are arbitrary, and need not be 
  449. consecutive.
  450.  
  451.     CSF_PICKLIST
  452.     The picklist control determines how a picklist should be 
  453. displayed on the dialog box.  Unlike the standard dialog 
  454. controls, the picklist control allows a separately defined 
  455. picklist to be displayed on the dialog box.  The picklist 
  456. structure must first be defined (as though it were a standard 
  457. picklist), and a pointer to it is placed in ActionPtr.  The 
  458. picklist will be handled internally, and will operate as though 
  459. it were a dialog control.
  460.  
  461.  
  462.     Once the dialog box is active, ZForms displays all 
  463. controls, then searches for the first control marked with the 
  464. CSS_ACTIVATE flag.  This control is hilighted, and is the 
  465. current control.  The hint window, if one is defined, is opened 
  466. and the hint text displayed.  The user may now cycle through 
  467. the active controls using the TAB key.  To activate a control, 
  468. the user may press <SPACE> or <ENTER> when the control is 
  469. hilighted, or press the hot key for the desired control.  When 
  470. the control is activated, the CSS_CALLXXXX flag is tested, and 
  471. ActionPtr is used, as folows.  If CSS_CALLFUNC is set, 
  472. ActionPtr is assumed to point to a function, which is called.  
  473. If CSS_CALLDIALOG is set, ActionPtr is assumed to point to 
  474. another dialog box, which is activated using 
  475. Z_HandleDialog(...).  If CSS_CALLMENU is set, ActionPtr is 
  476. assumed to point to a menu, which is activated using 
  477. Z_HandleMenu(...).  If CSS_EXIT is set, the dialog box 
  478. terminates, returning the number of the control which causes 
  479. it.  If CSS_CALLNOTHING is set, no action is taken.
  480.     There is a pre-defined dialog box which may be used to 
  481. inform the user of an event, or to ask a yes/no type question.  
  482. Z_InformUser(...) takes 4 strings as input;  A title, the box 
  483. text, and two buttons.  The box is centered on the physical 
  484. screen.  The box returns TRUE if button 1 is selected, or FALSE 
  485. if button 2 is selected.  If the text pointer for button 2 is 
  486. NULL, then only one button (Button 1) is displayed, and it is 
  487. centered.
  488.  
  489.     Prompts:
  490.     A prompt sequence is a set of questions to the user which 
  491. wait for a response.  The questions are answered without 
  492. intervention from application program.  Prompts are defined in 
  493. a prompt structure array, terminated by a NULL Response, whose 
  494. fields are as follows:
  495.         Response : Pointer to the destination string
  496.         Prompt   : Pointer to the prompt text string
  497.         Mask     : Pointer to the data mask
  498.                    # - Any ascii character
  499.                    9 - Numeric only
  500.                    U - Uppercase (convert lowercase)
  501.                    any other - literal
  502.         Length   : Maximum length of input
  503.         XPos     : Window X Position for this prompt
  504.         YPos     : Window Y Position for this prompt
  505.         PromptColor : Color for prompt
  506.         PromptBack : Color for prompt background
  507.         ResponseColor : Color of response
  508.         ResponseBack : Color of response background
  509.         HiColor  : Color of response hilight
  510.         HiBack   : Color of response hilight background
  511.         Verify   : Pointer to verification function, or NULL
  512.                   for none
  513.         Hint     : Pointer to hint text
  514.  
  515.  
  516. A prompt sequence is initialized, and passed to 
  517. Z_HandleInputs(...).  This function displays all of the prompts 
  518. and responses along with the hint, if any.  The user navigates 
  519. through the prompts by presing the up and down arrow keys, as 
  520. well as the enter key.  Before Zforms will allow the user to 
  521. move to another field, however, the verification function is 
  522. called (if Verify is not NULL).  The verification function is 
  523. an application-supplied function which recieves the response 
  524. and returns either TRUE (okay to move) or FALSE (stay in the 
  525. field).  This allows the application to verify that the data is 
  526. valid before accepting it. 
  527.         To terminate the prompts, the user presses one of the 
  528. ExitKeys passed to Z_HandleInputs.  ExitKeys is an array of 
  529. keys, terminated by k_NoKey.  Z_HandleInputs returns the key 
  530. used to terminate the function.
  531.  
  532.     Picklists:
  533.     A Picklist is a vertical list of items which may be 
  534. scrolled by the user to find a particular selection.  The user 
  535. may use the Escape key or Enter to either escape the picklist, 
  536. or make a selection.  A picklist is created by initializing a 
  537. picklist structure, which has the following fields:
  538.     OrgX        :    Screen X origin of dialog box
  539.     OrgY        :    Screen Y origin of dialog box
  540.     Height    :    PickList height
  541.     Width    :    PickList width
  542.     TextWidth :    Width of picklist display area
  543.     Flags    :    There are no picklist flags at this time
  544.                 (initialize to zero)
  545.     TextColor:    Color of picklist text
  546.     BackColor:    Background color of the picklist
  547.     HiTextColor:    Color of highlighted text
  548.     HiBackColor:    Background color of highlighted text
  549.     BorderStyle:    Type of border, if any
  550.                     BS_NOBORDER
  551.                     BS_SINGLELINE
  552.                     BS_DOUBLELINE
  553.     BorderColor:    Color of border line
  554.     BorderBack:    Color of border background
  555.     DefaultChar:    character/attribute for the picklist
  556.                 background
  557.     DropShadow:    The drop shadow identifier:
  558.                         DS_UPPERLEFT
  559.                         DS_UPPERRIGHT
  560.                         DS_LOWERRIGHT
  561.                         DS_LOWERLEFT
  562.                         DS_NONE
  563.     DropAttr    :    The attribute to use for the background of the
  564.                 drop shadow
  565.     Title    :    Pointer to the picklist title
  566.     pWin        :    Pointer to the window to display on
  567.     Item        :    Pointer to the first PICKLIST_ITEM in the list
  568.     LastItem    :    Pointer to the last PICKLIST_ITEM in the list
  569.  
  570.  
  571. The PICKLIST_ITEM structure is:
  572.         ItemText: Pointer to the item's text
  573.         Prev    : Pointer to the previous list entry
  574.         Next    : Pointer to the next list entry.
  575.  
  576.     Once the picklist structure is initialized, items can be 
  577. added to it by calling Z_AddPickListItem, or removed by calling 
  578. either Z_RemovePickListItem or Z_RemovePickListEntry.  To 
  579. display the picklist, call Z_HandlePickList.  This function 
  580. displays the picklist on the window specified, and accepts 
  581. keypresses from the user.  The user may scroll up and down by 
  582. using the up/down arrow keys.  The user may escape the picklist 
  583. by pressing Escape, in which case Z_HandlePickList returns 
  584. NULL.  The user may also select an entry by pressing Enter, in 
  585. which case Z_HandlePickList returns the pointer to the picklist 
  586. item.
  587.  
  588.     Programming using Z-Forms:
  589.     The Z-Forms header file ZFORMS.H contains prototype 
  590. definitions for all Z-Forms functions, as well as definitions 
  591. for other items, such as colors, keycodes, and flags.  This 
  592. file should be included in all source modules that use Z-Forms 
  593. calls.  In addition, the executable program should be linked 
  594. with the Z-Forms library, which is a large model library (for 
  595. those compilers supporting memory models).  Z-Forms is written 
  596. to generate OS/2 1.x or 2.x programs.  OS/2 1.X programs may be 
  597. bound to run under either OS/2 or DOS.  If the program is to be 
  598. DOS only, you should also link with the ZFDOS library, which 
  599. contains DOS versions of the OS/2 VIO, KBD and DOS calls used 
  600. by Z-Forms. When binding programs using Z-Forms, be sure to 
  601. specify the following command line option:
  602.  
  603.         /N VIOGETBUF VIOSHOWBUF
  604.  
  605. This option is required because those two functions are not 
  606. family mode functions.  They are not called if the machine is 
  607. in real mode.  Please take a few minutes to examine the sample 
  608. code, to see how the various functions work.  We hope that you 
  609. find Z-Forms a powerful, yet easy to use screen management 
  610. library.
  611.  
  612.     Z-Forms Compilation Macros
  613.     There are two macros used to control the compilation of 
  614. Z-Forms applications.  The libraries are built using the 
  615. correct macros, and the standard compilers (Microsoft, IBM and 
  616. Borland) define them automatically.  If you are using Z-Forms 
  617. with another compiler, you may need to define these macros 
  618. yourself.  The first is __Z_INIT_EXT__ (two underbars before 
  619. and after).  This option controls how menu and dialog box 
  620. controls are initialized.  Both definitions have an unsized 
  621. array in the structure, but some compilers do not support this.  
  622. If so, define __Z_INIT_EXT__.  If not, a separate array must be 
  623. defined (see the sample code).  The second macro is 
  624. __Z_SECVID__.  This option controls how the physical screen is 
  625. updated by Z-Forms.  If VioGetBuf and VioShowBuf are not 
  626. supported, define __Z_SECVID__ and Z-Forms will use 
  627. VioWrtCellStr instead.
  628.     The option definitions for the standard compilers are:
  629.     Microsoft C 6.0:         __Z_INIT_EXT__
  630.     Borland C/C++ for DOS:   __Z_SECVID__
  631.     IBM C/Set:               __Z_SECVID__
  632.     Borland C/C++ for OS/2:  __Z_SECVID__
  633.  
  634. Functions Refernce:
  635. **************************************************************
  636. WINDOW * Z_OpenWindow(WINDOW * pWin)
  637.         pWin    : Address of an initialized window structure
  638.  
  639.         This function defines and displays a window.  
  640. Z_DefineWindow and Z_CreateWindow are called from here, so this 
  641. is usually the only function that must be called to open a new 
  642. window.
  643.  
  644. Return Value: Pointer to the real window structure.
  645.  
  646. **************************************************************
  647. void Z_CloseWindow(WINDOW * pWin)
  648.         pWin    : pointer to the window structure to close
  649.  
  650.         This function hides the window and undefines it.  This        
  651. is usually the only function that must be called to close        
  652. a window.
  653.  
  654. Return Value: none
  655.  
  656. **************************************************************
  657. WINDOW * Z_CreateWindow(WINDOW * temp, int Height, int Width,
  658.            int XOrg, int YOrg, int DefaultChar, int Border,
  659.            int For, int Back, char *Title, char *SubTitle)
  660.         temp    : pointer to window structure to be defined
  661.         Height  : window height
  662.         Width   : window width
  663.         XOrg    : Physical X Origin on the screen
  664.         YOrg    : Physical Y origin
  665.         DefaultChar : character to fill the window with
  666.         Border  : Border style identifier:
  667.                   BS_NOBORDER
  668.                   BS_DOUBLELINE
  669.                   BS_SINGLELINE
  670.         For     : Forground color
  671.         Back    : Background color
  672.         DropShadow : Drop shadow identifier:
  673.                      DS_UPPERLEFT
  674.                      DS_UPPERRIGHT
  675.                      DS_LOWERRIGHT
  676.                      DS_LOWERLEFT
  677.                      DS_NONE
  678.         DropAttr : Background attribute to use for the shadow
  679.         Title   : pointer to window title, or NULL for none
  680.         SubTitle : pointer to window subtitle, or NULL for none
  681.  
  682.         This function fills a window structure from the data 
  683. given.  The window must then be defined and shown.  This 
  684. function would be used to create a window structure 'on the 
  685. fly'.  You could also assign the data yourself, but this saves        
  686. some code space.
  687.  
  688. Return Value: Pointer to the filled window structure (temp)
  689.  
  690. **************************************************************
  691. WINDOW * Z_DefineWindow(WINDOW * pWin)
  692.         pWin    : pointer to window to define
  693.  
  694.         This function fills a new window structure with the 
  695. data from pWin, initializes the window's virtual buffer, and        
  696. returns the new window structure pointer.  This pointer is 
  697. different from the original pointer, so that several windows 
  698. can be created from the same pWin structure.  The window is 
  699. initially hidden, and must be shown using Z_ShowWindow.  This 
  700. function does not need to be used if Z_OpenWindow is used.
  701.  
  702. Return Value: Pointer to the real window structure
  703.  
  704. **************************************************************
  705. void Z_UnDefineWindow(WINDOW * pWin)
  706.         pWin    : window to undefine
  707.  
  708.         This function removes the window from the linked window 
  709. list, and hides it.  All memory allocated for the window's 
  710. virtual buffers is freed.
  711.  
  712. Return Value: none
  713.  
  714. **************************************************************
  715. void Z_HideWindow(WINDOW * pWin)
  716.         pWin    : Window to hide
  717.  
  718.         This function makes the window non-displayable, but 
  719. does not destroy it.  The window may still be written to, but 
  720. it will not be visible until Z_ShowWindow is called.
  721.  
  722. Return Value: none
  723.  
  724. **************************************************************
  725. void Z_ShowWindow(WINDOW * pWin)
  726.         pWin    : Window to show
  727.  
  728.         This function causes a hidden window to be displayed, 
  729. and must be called after a new window is defined, as all new 
  730. windows are initially hidden.  If Z_OpenWindow is used, this 
  731. function does not need to be called.
  732.  
  733. Return Value: none
  734.  
  735. **************************************************************
  736. void Z_PushWindow(WINDOW * pWin)
  737.         pWin    : Window to push
  738.  
  739.         This function pushes a window to the back of the 
  740. screen, placing it behind all other windows.  The window is 
  741. still visible (except for the parts that are covered by other 
  742. windows), and will still be updated if written to.
  743.  
  744. Return Value: none
  745.  
  746.  
  747. **************************************************************
  748. void Z_PopWindow(WINDOW * pWin)
  749.         pWin    : Window to show
  750.  
  751.         This function pops a window to the front of the screen, 
  752. placing it in front of all other windows.
  753.  
  754. Return Value: none
  755.  
  756. **************************************************************
  757. int Z_GetCharOnTop(WINDOW * pWin, int x, int y)
  758.         pWin    : Window to show
  759.         x       : X-Coordinate of the character
  760.         y       : Y-Coordinate of the character
  761.                                                                   
  762.         This function determines the visible character at a 
  763. specific position on a window.  The x and y coordinates are 
  764. with respect to the window.  The return value is the character 
  765. that the user sees at that position (from the top-most window).
  766.  
  767. Return Value: Character/Attribute pair of the top character
  768.  
  769. **************************************************************
  770. void Z_UpdatePhysicalScreen(WINDOW * pWin, int x0, int y0, int 
  771. Wid, int Ht)
  772.         pWin    : Window to show
  773.         x0      : X-Coordinate of the region
  774.         y0      : Y-Coordinate of the region
  775.         Wid     : Width of the region
  776.         Ht      : Height of the region
  777.                                                                   
  778.         This function is used internally to update the physical 
  779. display from the virtual screen buffers.  It should never be 
  780. needed by the programmer, but is documented on the chance that 
  781. someone may find it useful.  The rectangle defined by x0,y0 and 
  782. Wid/Ht is displayed on the physical screen (x0 and y0 are with 
  783. respect to the window pWin).  For each character in the region, 
  784. Z_GetCharOnTop is used to find the actual visible character.  
  785. Strings are built for each row, which are displayed.
  786.  
  787. Return Value: none
  788.  
  789. **************************************************************
  790. void Z_TextOut(WINDOW *pWin, char * text, int X, int Y,
  791.                int For, int Back)
  792.         pWin    : window pointer to display on
  793.         text    : pointer to text to display
  794.         X       : local window X co-ordinate to display on
  795.         Y       : local window Y co-ordinate to display on
  796.         For     : forground color to use
  797.         Back    : background color to use
  798.  
  799.         This function displays the text in 'text' at the 
  800. co-ordinates (X,Y) on the window.  The text is displayed using 
  801. the foreground and background colors given.
  802.  
  803. Return Value: none
  804.  
  805. **************************************************************
  806. void Z_TextOver(WINDOW * pWin, char * text, int LocalX, int 
  807. LocalY)
  808.         pWin    : window to display text on
  809.         text    : pointer to text
  810.         X       : local X co-ordinate to use
  811.         Y       : local Y co-ordinate to use
  812.  
  813.         This function displays the text in 'text' on the window 
  814. without changing the color or attribute at the position.
  815.  
  816. Return Value: none
  817. **************************************************************
  818. void Z_ClearScreen(char Character, char Attribute)
  819.  
  820.         This function clears the screen, filling it with the 
  821. given character at the given attribute.
  822.  
  823. Return Value: none
  824.  
  825. **************************************************************
  826. void Z_GetVideoMode(void)
  827.  
  828.         This function determines the number of rows and columns 
  829. for the current display mode, and puts them in the Z-Forms 
  830. global variables 'Z_ScreenWidth' and 'Z_ScreenHeight'.
  831.  
  832. Return Value: none
  833.  
  834. **************************************************************
  835. void Z_SetVideoMode(int Rows, int Cols)
  836.         Rows    : Number of rows to set
  837.         Cols    : Number of columns to set                                      
  838.  
  839.         This function attempts to set the display mode to the 
  840. number of rows and columns specified.  Note that the operating 
  841. system may not allow the row/column count specified.  
  842. Regardless of the outcome, the Z-Forms global variables 
  843. 'Z_ScreenWidth' and 'Z_ScreenHeight' will be set to the actual 
  844. number of rows and columns.
  845.  
  846. Return Value: none
  847.  
  848. **************************************************************
  849. void Z_SetCursor(WINDOW *pWin, int X, int Y)
  850.         pWin    : pointer to window
  851.         X       : X offset for cursor
  852.         Y       : Y offset for cursor
  853.  
  854.         This function moves the hardware cursor to the position 
  855. specified by (X,Y) on the designated window.
  856.  
  857. Return Value: none
  858.  
  859.  
  860. **************************************************************
  861. int Z_HandleMenu(MENU *pMenu)
  862.         pMenu   : Pointer to the menu to use
  863.  
  864.         This function handles all menu processing for the 
  865. designated menu.  The menu structure is predefined, and 
  866. includes support for nested menus, vertical menus, and 
  867. horizontal menus.  For more information, see the MENU structure 
  868. documentation.  In most cases, this is the only menu function 
  869. that will need to be called.
  870.  
  871. Return Value: none
  872.  
  873. **************************************************************
  874. void Z_DisplayMenuSelection(MENU *pMenu, WINDOW *pWin, int 
  875. Item, int fHilite)
  876.         pMenu   : Pointer to the menu to use
  877.         pWin    : Window that the menu is displayed on
  878.         Item    : Item number to display
  879.         fHilite : Flag indicating whether the item is selected
  880.  
  881.         This function should not generally be needed by the 
  882. programmer, but is included in case it turns out to be useful.  
  883. The function updates the menu text for the menu item selected 
  884. by Item.  If fHilite is true, the hilighted colors ase used, 
  885. otherwise the standard colors are used.
  886.  
  887. Return Value: none
  888.  
  889. **************************************************************
  890. int Z_CountMenuItems(MENU *pMenu)
  891.         pMenu   : Pointer to the menu to use
  892.  
  893.         This function returns the number of items in the menu 
  894. structure pointed to by pMenu.
  895.  
  896. Return Value: The number of items in the menu
  897.  
  898. **************************************************************
  899. int Z_HandleDialog(DIALOG * pDialog)
  900.         pDialog : pointer to dialog box structure
  901.  
  902.         This function handles all processing for the dialog 
  903. box.  The dialog box structure is predefined, and supports 
  904. buttons and text.  For more information, see the DIALOG 
  905. structure documentation.
  906.  
  907. Return Value: the control number which terminated the dialog 
  908. box
  909.  
  910.  
  911. **************************************************************
  912. int Z_InformUser(char * Title, char * Text, char * Button1, 
  913. char * Button2)
  914.         Title   : Pointer to the title of the inform box
  915.         Text    : Pointer to the text to display in the box
  916.         Button1 : Pointer to the text for Button 1
  917.         Button2 : Pointer to the text for Button 2, or NULL for
  918.                  none
  919.  
  920.         This function implements a pre-defined dialog box for 
  921. informing the user or asking a yes/no type question.  The title 
  922. and text are centered on the window, which is centered on the 
  923. physical display.  If two buttons are defined, they are 
  924. displayed against the sides of the box, and if only one button 
  925. is defined, it is centered.
  926.  
  927. Return Value: 1 if Button 1 is pressed, 0 if Button 2 is 
  928. pressed
  929.  
  930. **************************************************************
  931. int Z_CountDialogItems(DIALOG *pDlg)
  932.         pDlg    : Pointer to the dialog box structure
  933.  
  934.         This function counts the number of dialog items in the 
  935. dialog box structure.
  936.  
  937. Return Value: The number of dialog items
  938.  
  939. *************************************************************
  940. int Z_GetKey(void)
  941.         This function waits for a key to be pressed, and 
  942. returns it.  The keys are defined in the header file.  If there 
  943. is a background function defined, it is called as long as there 
  944. is no keypress (See Z_SetBackgroundProcess).  The key codes are 
  945. listed in ZFORMS.H
  946.  
  947. Return Value: key pressed
  948.  
  949. **************************************************************
  950. void Z_Delay(int Milli)
  951.         Milli   : Number of milliseconds to delay
  952.  
  953.         This function pauses the program for the specified 
  954. number of milliseconds.  This function is included for the 
  955. benefit of DOS programs which do not have DosSleep.
  956.  
  957. Return Value: none
  958.  
  959.  
  960. **************************************************************
  961. int Z_HandleInputs(WINDOW * pWin, WINDOW * pHintWin, 
  962.                     PROMPT * Tmp, int * ExitKeys)
  963.         pWin    : pointer to window structure to display on
  964.         pHintwin : pointer to hint window
  965.         Tmp     : prompt structure
  966.         ExitKeys : array of keys used to exit
  967.  
  968.         This function handles all keyboard input for a prompt 
  969. structure.  The structure is predefined with all prompts and 
  970. positions, then this funxtion prompts the user to fill all of 
  971. the fields.  The function exits when one of the keys listed in 
  972. the ExitKeys list is pressed.  For more information, see the 
  973. PROMPT structure documentation.
  974.  
  975. Return Value: the Exit Key pressed
  976.  
  977. **************************************************************
  978. int Z_SetBackgroundProcess(void (*pFunc)(void), int Milli)
  979.         pFunc    : pointer to the function to execute
  980.         Milli    : number of milliseconds to delay
  981.  
  982.         This function sets up a background function for 
  983. execution when the program is waiting for a keystroke.  If the 
  984. function pointer is NULL, no function is executed (This is the 
  985. default).
  986.         
  987. Return Value: none
  988.  
  989. **************************************************************
  990. int Z_AddPickListItem(PICKLIST *pPickList, char * Text)
  991.         pPickList : pointer to picklist to use
  992.         Text      : pointer to text string to add
  993.  
  994.         This function handles adds a text string to a picklist.  
  995. The string is linked in to the end of the list. 
  996.  
  997. Return Value: 1 if the function was successful, 0 otherwise
  998.  
  999. **************************************************************
  1000. int Z_RemovePickListItem(PICKLIST *pPickList, char * Text)
  1001.         pPickList : pointer to picklist to use
  1002.         Text      : pointer to text string to remove
  1003.  
  1004.         This function handles removes a text string from a 
  1005. picklist.  The picklist item is found by matching the text to 
  1006. the picklist items.
  1007.  
  1008. Return Value: 1 if the function was successful, 0 otherwise
  1009.  
  1010. **************************************************************
  1011. int Z_RemovePickListEntry(PICKLIST *pPickList, PICKLIST_ITEM 
  1012. **pPLI)
  1013.         pPickList : pointer to picklist to use
  1014.         pPLI      : pointer to the picklist item to remove
  1015.  
  1016.         This function handles removes a picklist item from the 
  1017. list.
  1018.  
  1019. Return Value: 1 if the function was successful, 0 otherwise
  1020.  
  1021.  
  1022. **************************************************************
  1023. void Z_DestroyPickList(PICKLIST *pPickList)
  1024.         pPickList : pointer to picklist to destroy
  1025.  
  1026.         This function destroys all picklist items and frees all 
  1027. memory.
  1028.  
  1029. Return Value: none
  1030.  
  1031. **************************************************************
  1032. void Z_PurgePickList(PICKLIST *pPickList)
  1033.         pPickList : pointer to picklist to purge
  1034.  
  1035.         This function destroys all picklist items, leaving a 
  1036. blank picklist.
  1037.  
  1038. Return Value: none
  1039.  
  1040. **************************************************************
  1041. PICKLIST_ITEM * Z_HandlePickList(PICKLIST *pPickList)
  1042.         pPickList : pointer to picklist to use
  1043.  
  1044.         This function handles a picklist.  The picklist is 
  1045. displayed with the first item highlighted.  The user may use 
  1046. the up and down arrow keys to manuever the list.  Pressing 
  1047. enter causes the list to exit, returning a pointer to the 
  1048. selected item, while pressing escape returns NULL.
  1049.  
  1050. Return Value: a pointer to the selected PICKLIST_ITEM structure 
  1051. if ENTER is pressed, or NULL if ESCAPE is pressed.
  1052.  
  1053.  
  1054. REGISTERING Z-FORMS
  1055. ===================
  1056. To register Z-Forms, simply print out this form, fill it in, 
  1057. and mail it along with a check.  Registration is $35 US (add 
  1058. $1.00 for orders outside the US) made out to "Z-Space".  Checks 
  1059. from Canadian banks must include an extra $5 to cover exchange 
  1060. costs.
  1061.  
  1062.                     Z-Space
  1063.                     4278 W. 223rd Street
  1064.                     Cleveland, Ohio 44126
  1065.  
  1066.     Name:    ____________________________________________
  1067.  
  1068.     Address: ____________________________________________
  1069.  
  1070.              ____________________________________________
  1071.  
  1072.     City/State: _________________________________________
  1073.  
  1074.     Phone (optional)
  1075.            Home: _____________    Work:  ________________
  1076.  
  1077.  
  1078.     EMail addresses:_____________________________________
  1079.  
  1080.  
  1081.     Compiler you are using Z-Forms with:_________________
  1082.  
  1083.  
  1084.     Where did you get your copy of Z-Forms?:_____________
  1085.  
  1086.  
  1087.     Are you interested in any other Z-Forms related tools
  1088.    (screen editors, code generators, etc)? Please specify:
  1089.  
  1090.     _____________________________________________________
  1091.  
  1092.  
  1093.  
  1094.     
  1095. =============================================================
  1096. Comments or suggestions?  (please print below and/or on back)
  1097.  
  1098.