Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : FOG_WIN.ZIP
Filename : FOG_WIN.TXT

< FOG WINDOWING LIBRARY >


Peter Fogelsanger
Easy Automation
44 Triple Crown Ct.
Baltimore, MD 21207


OVERVIEW

The Fog Window library is comprised of several utilities that makes
the Clipper user interface consistent and friendly as well as being
easier to program. To use the Library you must link the FOG_WIN.LIB
with your programs. It is best to place FOG_WIN before CLIPPER and
EXTEND, this ensures everything is defined to the library. You can
then call any other function as many times as needed.

The setup_windows function is optional, you may wish to explicitly
call it in several cases. If you do not call it explicitly, it
will be called by w_open before the first window is opened and it
will default to ten windows. If you desire to have more than ten
windows open at once or you need to conserve memory by having less
than ten windows, you should call setup_windows(x). X would be the
maximum number of windows you want to be able to open.


Function: setup_windows
Description: Initializes public variables and stacks for using
windows.
Parameters: max_w
The maximum number of windows that will be allowed
open at any one time. The default is 15.



< WINDOW MANIPULATION >

Function: w_activ
Description: Pull overlayed window to top, making it active
window. If the window to be activated is overlaped
by other window, it will be moved over top of them.
Parameters: whandle,refresh, border
The refresh flag allows the programmer to override
the Pasting of windows. This is feasible if
windows do not overlap each other. The refresh
routine is not particularly fast, therefore it is
best to specify refresh = "N" if the windows don't
overlap.
The border flag is handy for putting the double
border around the window when it is activated.



Function: w_all_close
Description: Close all open windows
Parameters: none



Function: w_attrib
Description: Change the attributes of the active window.
Parameters: b_attrib - the border colors
tx_attrib - the colors for the text of the window
fd_attrib - the colors for active fields.
tt_attrib - the title colors
uns_attrib - the colors for unselected fields
misc - a misc. color to change. Use if you print
w_header with a color other than the standard tx
color.



Function: w_border
Description: This draws a border around the active window using
a given attribute.
Parameters: b_type - 1,2,3,4,5
b_attrib - the color in the form of "R/N"



Function: w_clear
Description: This clears the entire active window (not the title)
using the windows current text color.
Parameters: none



Function: w_c_eol
Description: Clear to the end of requested line.
Parameters: row - row to clear
col - column to start at



Function: w_close
Description: Close the current window and restore screen under
window and delete window from stacks.
Parameters: none



Function: w_copy
Description: This will make an exact copy of the current window
on top of itself. It can then be moved and used as
if it were created with w_open from scratch.
Parameters: none
Returns: handle of new window


Function: w_get
Description: Get text at window coordinates. Text should be
passed as a text string which is the name of the
variable to get. Issue a READ after all desired
w_gets are specified. Use this in place of @x,y
get.
Pic is a Picture Clause.
The action function that you specify can be used to
update fields or variables based on calculations,
seeks, etc. It can also validate the current
field. Be sure to return .T. or .F. to indicate
validity.
Note: Pic and act_fnc are both optional.
Parameters: row, col, text, pic, act_fnc
Text is in form of: 'variable'
Pic is a valid Clipper picture clause.
Act_Fnc is the name of a UDF in the form of
"func"



Function: w_header
Description: Display text header in a window. The color
parameter makes this a useful function when
certain text needs to be set off from the standard
text. Ex: Navigational Aids (F1-Help, etc)
Parameters: row, col, text, color



Function: w_input
Description: Input text at window coordinates. Text should be
passed as a text string which is the name of the
variable to get. Use this where data entry is
needed with out destroying pending read statments.
Parameters: row, col, text
Text is in form of: 'variable'
Returns: Text string.



Function: w_menu
Description: A vertical ("V") or a horizontal ("H") menu (pick
list) is created from array.
A user defined function can also be specified for a
vertical list. It should follow the conventions
for any Clipper UDF (see achoice() or dbedit()).
The Start and UDF parameters are optional.
The size of the menu (list) is adjusted
automatically to fit in the window. This is
accomplished by using the number specified (height
if not), and the width of the first element in the
array. This means the first element should be
blank padded to the width of the widest element.
Parameters: row, col, number, kind, array, start, udf
Row/Col: coordinates within current window.
Number: The number of elements to display.
Kind: V/H.
Array: array of menu choices.
Start: the array element to start menu from.
UDF: the text name of a user defined function.



Function: w_menu_choose
Description: Display a single line pick list in the current
window. The arrow keys scroll the array choices
through the pick list.
Parameters: mrow, mcol, width, array



Function: w_menu_ind
Description: This function creates an achoice() type menu (pick
list) with a positional indicator. This indicator
moves in relation to the entire list of choices.
Description: The w_menu_ind() function can be used in two ways to
pick from a list.
First it can be used in the traditional way where
the user picks an element, the menu ends and the
program does something with the users selection.
Or you can specify a function to use as a UDF. The
UDF will be passed the current element in the
array so that you can take any action dependent
upon the array. In this case the UDF is not a
conventional Clipper UDF, therefore it will only
need to accomidate the action to perform when a
menu (list) element has been selected.
Parameters: row, col, number, width, choice_arr, start, udf
Number: # to show.
Width: of longest element
Choice_arr: array of choices.
Start: position in array to start menu from.
UDF: User defined function.
Note: Start and UDF are optional.



Function: w_move
Description: Moves the current window anywhere on the screen.
Parameters: row and column to move the window to. (top/left
corner)
Returns: none



Function: w_open
Description: Opens a new window and puts it on the window stack.
If the setup_windows function has not been called,
the w_open function will call it with ten as the
default for max windows.
The unselect_c, inactive field color, parameter is
optional. If it is not specified all fields will
be displayed in the field_c color
Parameters: row, col, length, width, b_color (border),
w_color (window), field_c (active fields and menu
bar), unselect_c (inactive fields)



Function: w_print
Description: Print text at window coordinates. Use in place of
@x,y say.
Parameters: row, col, text, pic
Pic is any valid Clipper Picture clause.



Function: w_query
Description: Return handle of window at given coordinates
Parameters: chk_row, chk_col



Function: w_shadow
Description: Displays a shadow on the active window. This
function adjusts itself when the window is on the
edge of the screen.
Parameters: none



Function: w_shad_off
Description: Turns off the shadow on the active window if one
exists. It is not necessary to turn off every
shadow you turn on, w_close automatically turns
off the shadow before the window is closed.
Parameters: none



Function: w_title
Description: Center a title on the window with given attribute,
or the current color if attribute is not
specified.
Parameters: wtitle, tt_attrib



< HELP SYSTEM >

OVERVIEW
The window help system is used to display context sensitive
help for the user when they press F1.
Components:
A help .dbf - contains a help category field (Char 10)
- and a help text memo field
The help .dbf should be indexed on the help category
field.

Public variables:
hw_bc - the help window border color
hw_bk - the help window background color
hw_tc - the help window text color
help_dbf - the name of the help datafiles (.dbf/.ntx)
dbf_dir - the path for the help files
w_help_cat - the text (or number) of the current help
category. The help system maintains context
sensitivity by the programmer setting the w_help_cat
to the category pertinent to the area of the program
running.

Installation: To use the window help system, place in your
program the following function:

Function Help
parameters calling
w_help(calling)


Help Definition: To assist in the development of the Help
text, the help system includes a function called
w_hlp_df. This program can be used by temporarily
putting -> w_help_def(calling) in place of ->
w_help(calling) as described above in Installation. This
causes the help definition system to be activated instead
of the normal help system.
The current help category will be displayed when the system
is activated. This allows you to go through the
application and define descriptive catagory names for
each module that will have help.
If you have not defined a catagory for the module of you
application you are in, you can create a catagory by
changing the one displayed. This will only create the
catagory in the help database, you will have to define
the catagory name in your application later for the
system to use it.
The help system will then display the text (blank when new)
for that category. You can change and add to the text on
the 'fly'. This allows you to simulate WYSIWYG help
development.


Example:

Function record_edit

w_help_cat="Rec_edit"
@ 1,1 say "Field1:"
@ 1,10 get field1
.
.
.
read
if error condition
w_help_cat="Rec_error"
.
display error message
.
@ 5,5 say "Correct Error?" get resp
read
.
.
endif
.
.
.



Function: w_help
Description: Controls the calling of the help routines and the
display of the help text. w_help first attempts to
open or use the help_dbf. If none is available it
will indicate that. If it can use the dbf, it will
locate the current w_help_cat then display the
help_text in a help window. If text is longer than
one page the user can scroll with the arrows and
page keys.



< STATUS FUNCTIONS >

Function: isCursor
Description: Determines the current status of the cursor so that
it may be saved and restored later.
Parameters: none
Returns: .T. if cursor is on - .F. if cursor is off
Example: .
savecur=isCursor()
set cursor on
.
.
.
set cursor &savecur
.
.
.



Function: isDeleted
Description: Determines the current status of Set Deleted so that
it may be saved and restored later.
Parameters: none
Returns: .T. if deleted is on - .F. if deleted is off



Function: isEscape
Description: Determines the current status of Set Escape so that
it may be saved, changed and restored later.
Parameters: none
Returns: .T. if escape is on - .F. if escape is off



Function: isExact
Description: Determines the current status of Set Exact so that
it may be saved, changed and restored later.
Parameters: none
Returns: .T. if exact is on - .F. if exact is off



Function: isExclus
Description: Determines the current status of Set Exclusive so
that it may be saved, changed and restored later.
This is only indicates the status of Set
Exclusive, it does not accomidate USE EXCLUSIVE.
Parameters: none
Returns: .T. if exclusive is on - .F. if exclusive is off



Function: isSoft
Description: Determines the current status of Set Softseek so
that it may be saved, changed and restored later.
Parameters: none
Returns: .T. if softseek is on - .F. if softseek is off



< SOUND FUNCTIONS >

Function: s_burp_burp
Purpose: Make a sound indicating Error.


Function: s_leave
Purpose: Make a sound indicating program termination


Function: s_select
Purpose: Make a blip sound indicating activity


Function: s_charge
Purpose: Sound CHARGE. May be used at program entry.
Parameters: octive