home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1993 #2
/
Image.iso
/
os2
/
zfrms100.zip
/
ZFORMS.DOC
< prev
next >
Wrap
Text File
|
1993-05-24
|
43KB
|
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)