Dec 112017
 
Dialog Box Toolkit Docs.
File DB20PRO1.ZIP from The Programmer’s Corner in
Category C Source Code
Dialog Box Toolkit Docs.
File Name File Size Zip Size Zip Type
DBPRO.TXT 271810 36681 deflated

Download File DB20PRO1.ZIP Here

Contents of the DBPRO.TXT file








The DialogPro

* * * * * Users Guide and Reference Manual * * * * *

by Kenneth Stott
version 2.0










Seabreeze Software
397 Dal-Rich Village
Suite 169
Richardson, Texas 75080
(214) 437-2729






Copyright (c) 1987-1988 by Kenneth Stott
All Rights Reserved









The DialogPro shareware diskette, containing a copy of this
manual, may be freely copied and shared. But, printed copies of
this document may not be copied by any method without the express
written permission of Seabreeze Software.





















DialogPro v 2.0 Users Guide
Reference Manual


I. Introduction . . . . . . . . . . . . . . . . . . . . . 1
II. Overview . . . . . . . . . . . . . . . . . . . . . . . 3
III. Technical Notes . . . . . . . . . . . . . . . . . . . 5
IV. Shareware . . . . . . . . . . . . . . . . . . . . . . 12
V. Registration . . . . . . . . . . . . . . . . . . . . . 13
VI. Support Details . . . . . . . . . . . . . . . . . . . 15
VII. Diskette . . . . . . . . . . . . . . . . . . . . . . . 16
VIII. Installation . . . . . . . . . . . . . . . . . . . . . 18
IX. Compiling and linking the demo . . . . . . . . . . . . 19
X. Changes between version 1.0 and 2.0 . . . . . . . . . 20
XI. Future enhancements . . . . . . . . . . . . . . . . . 22
XII. Reference . . . . . . . . . . . . . . . . . . . . . . 23
A. Introduction . . . . . . . . . . . . . . . . . . . . . 23
B. Functions . . . . . . . . . . . . . . . . . . . . . . 24
1. db_display . . . . . . . . . . . . . . . . . . . . 24
2. db_displayq . . . . . . . . . . . . . . . . . . . 24
3. db_flushqueue . . . . . . . . . . . . . . . . . . 25
4. db_freestorage . . . . . . . . . . . . . . . . . . 25
5. db_pop . . . . . . . . . . . . . . . . . . . . . . 26
6. db_priority . . . . . . . . . . . . . . . . . . . 26
7. db_push . . . . . . . . . . . . . . . . . . . . . 26
8. db_restoreanswers . . . . . . . . . . . . . . . . 27
9. db_run . . . . . . . . . . . . . . . . . . . . . . 27
10. db_selectq . . . . . . . . . . . . . . . . . . . . 29
11. db_storeanswers . . . . . . . . . . . . . . . . . 30
12. db_switchqueue . . . . . . . . . . . . . . . . . . 31
13. lst_display . . . . . . . . . . . . . . . . . . . 32
14. lst_displayitem . . . . . . . . . . . . . . . . . 33
15. lst_freestorage . . . . . . . . . . . . . . . . . 34
16. lst_restoreanswers . . . . . . . . . . . . . . . . 34
17. lst_run . . . . . . . . . . . . . . . . . . . . . 35
18. lst_select . . . . . . . . . . . . . . . . . . . . 37
19. lst_storeanswers . . . . . . . . . . . . . . . . . 37
20. lst_toggle . . . . . . . . . . . . . . . . . . . . 38
C. Standard Return Values . . . . . . . . . . . . . . . . 39
D. Data structures . . . . . . . . . . . . . . . . . . . 40
1. button . . . . . . . . . . . . . . . . . . . . . . 40
2. db_colors . . . . . . . . . . . . . . . . . . . . 41
3. db_delimiters . . . . . . . . . . . . . . . . . . 42
4. dialog_box . . . . . . . . . . . . . . . . . . . . 43
5. free_form . . . . . . . . . . . . . . . . . . . . 45
6. list . . . . . . . . . . . . . . . . . . . . . . . 46
7. list_rec . . . . . . . . . . . . . . . . . . . . . 49
8. multi_choice . . . . . . . . . . . . . . . . . . . 52
9. rcbutton . . . . . . . . . . . . . . . . . . . . . 54
10. reducer . . . . . . . . . . . . . . . . . . . . . 55
11. scroll_txt . . . . . . . . . . . . . . . . . . . . 58
12. title . . . . . . . . . . . . . . . . . . . . . . 59
E. Global variables . . . . . . . . . . . . . . . . . . . 60
1. db_head, db_tail, db_queue . . . . . . . . . . . . 60
2. default_db_cmds . . . . . . . . . . . . . . . . . . 60
3. idle . . . . . . . . . . . . . . . . . . . . . . . 60
4. monitor_switch, _fg, _bg, _speed, _wdw, _tile . . . 60
5. mouse_sensitivity . . . . . . . . . . . . . . . . . 61



- Table of Contents 1 -





DialogPro v 2.0 Users Guide
Reference Manual


F. Messages . . . . . . . . . . . . . . . . . . . . . . . 62
1. Dialog Box . . . . . . . . . . . . . . . . . . . . 62
2. Line Editor . . . . . . . . . . . . . . . . . . . . 65
3. list question . . . . . . . . . . . . . . . . . . . 67
4. Pull down list . . . . . . . . . . . . . . . . . . 68




















































- Table of Contents 2 -





DialogPro v 2.0 Users Guide
Reference Manual


I. Introduction

The DialogPro will help you implement one of today's hottest user
interface analogies, the dialog box. The dialog box, popularized
by Apple, is now a mainstay in almost all modern PC based
software. And it is here to stay. Despite not being invented by
IBM, it is included in their latest SAA user interface standards.

If you don't already know, The dialog box is a pop-up window with
a form inside of it. The form consists principally of questions,
these questions can be checklists, multiple choice questions
(sometimes known as radio buttons,) scrolling lists, and
buttons. Buttons are special because they can indicate to
perform some sort of action. Typically the action will be
something like, confirm the answers to the other questions, or
abort the dialog box (restore the old answers and return to the
previous process.) The dialog box is a familiar sight to most
personal computer users and is a tremendously simple way to get a
solid, consistent, user interface into your applications.

The bad news is that dialog boxes, while making life easier for
the user, are difficult to implement. This is particularly true
in a mouse environment -- where a user can literally click (or
point, or press, or drag, etc., etc.) on any thing he sees on the
screen -- how do you deal with that in a traditional structured
programming style?

The answer is you don't have to, at least not directly. Most
programmers work in a competitive, cost conscious environment and
don't have the time to ponder messaging and object orientation.
The DialogPro lets you use the latest techniques, without
sweating the details. It lets you put the latest, most
professional, Microsoftish/Borlandish/Macontish interface on your
programs without the pain. Your users will be able to hang onto
to their mice and learn your programs faster (even if you don't
get it -- A lot people have fallen in love with the mouse.) And
you'll be relieved of a big part of the programming, the
training, and the support.

The DialogPro is tremendously flexible. Every dialog box
understands over 60 commands -- you program these commands to any
keystrokes you like. Create additional commands, hot-keys, etc.
by defining macro-commands and attaching them to keystrokes.
Automatically update target variables in your applications.
"Hook" in your own routines directly into dialog box questions.
Perform edit checking and field updating/formatting on the fly,
anything you can imagine.

There are just so many uses for the DialogPro that it is hard to
list them all here. But things like interreferenced help systems
a la Lotus 1-2-3 are pretty straight forward. Likewise, creating
a user interface that conforms to SAA standards would be easy.
The DialogPro is perfect for desktop oriented applications
because at the heart of the DialogPro are sophisticated,



- 1 -





DialogPro v 2.0 Users Guide
Reference Manual


object-oriented, messaging algorithms. But the DialogPro is just
as comfortable sprucing up existing programs because the
sophistication is literally "at the heart" of The DialogPro;
ready to be put to use when you need it--but ingeniously "hidden"
until you want it. And that really is the key to The
DialogPro--it gives you what YOU want, adapts to your style.



















































- 2 -





DialogPro v 2.0 Users Guide
Reference Manual


II. Overview

The user sees a dialog box like this. A form to fill in. A
dynamic form where lists can scroll, amounts fill in
automatically, and buttons can be pushed to continue or perform
other actions.

+[ Personal Information ]-----------------+
| |
| Name : _________________________________ |
| Street : _______________________________ |
| City : _________________________________ |
| State : __ Zip Code __________________ |
| |
| Occupation : +----------------------+ |
| |[ ] Doctor ^^ |
| +=========+ |[ ] Dentist || |
| | Confirm | |[ ] Lawyer || |
| +=========+ |[ ] Accountant oo |
| +---------+ |[ ] Mechanic || |
| | Abort | |[ ] Engineer vv |
| +---------+ +----------------------- |
+-------------------------------------------+

The programmer sees this as a hierarchical data structure. The
dialog box is a structure with a series of subordinate data
structures representing the various questions, buttons, and
lists. As the programmer your principal task is to create these
data structures. The db_run and db_display functions are then
used to execute and/or display the dialog boxes.

In the above example your would first define a dialog box
structure. You would then define free_form (or
fill-in-the-blank) structures for the Name, Street, City, and Zip
Code fields. The State field could be represented as either a
multiple choice question, a reduction question (where the user
supplies part of the answer and the dialog box attempts to
determine the correct answer or displays a list of possible
answers to select from -- like all the states that begin with M,
for example,) or it could be just another fill in the blank
question.

Confirm and Abort would be defined as button structures and
Occupation would be list structure.

To see an example of how to create a simple dialog box see the
included source file, SIMPLEDB.C.

Of course, if this were the end of the story The DialogPro
wouldn't be all that useful. There are several default data
types to help you get started but ultimately the programmer has
final control over virtually every aspect of how a dialog box
looks and operates. For example,




- 3 -





DialogPro v 2.0 Users Guide
Reference Manual


. You can position questions anywhere in the pop-up window, or
in separate tiles of a pop up window, even create paged
dialog boxes by swapping tiles in and out.

. You can control how the questions are presented to the
user. Including delimiter characters, the position of the
statement describing the question, where the response to the
question should be located, the maximum length of the
response, the color of the statement, the color of the
response, and many more aspects.

. You may assign target variables to questions. Target
variables are automatically updated with the responses to
questions as they are answered.

. You can control the order that the user navigates to the
questions.

. You can "hook" in pre and/or post routines to each
question. Using the pre/post routines you can do edit
checking, field updating, even modify the user interface.

. You can indicate that questions are "unavailable" for
modification. In a graphics environment this is sometimes
known as "greying" out a choice.

. You can extend both the mouse and keyboard interface by
creating macros to define completely new commands and
features, or combine or modify existing features. Macros
can call your own routines or simply expand into a series of
alternative messages. This feature alone makes the
DialogPro almost infinitely extendable.

























- 4 -





DialogPro v 2.0 Users Guide
Reference Manual


III. Technical Notes

This section describes what you'll need to use The DialogPro, any
limitations you should be aware of, and describes (in further
detail) the theory of operation.


The WindowPro

The DialogPro is based on The WindowPro. You must have The
WindowPro to use The DialogPro. Just like The DialogPro, The
WindowPro is also available from Seabreeze Software.

If you have The WindowPro, and it works on your machine and
compiler, then so will The DialogPro. (Note: The DialogPro is
currently only tested with Quick-C 1.X, MSC C 5.X, and Turbo C
1.X compilers.)

Size

The DialogPro adds 30 to 40K of code to your application, in
addition to requiring virtually the full WindowPro library (which
adds about another 60K.)


What is a dialog box?

Dialog boxes and questions are hierarchical data structures.
Each dialog box routine operates on a given data structure.
Because they are data structures you can modify them, on the
fly. In fact your pre/post routines can "grey-out" options,
update fields, and remove questions dynamically by doing just
that. The dialog box routines interpret the data structures to
display the dialog box, select methods of dealing with user
commands, etc. As such, the application programmers main task is
to "fill-in" these data structures properly.


Messages at first glance

The major dialog box routine is db_run. db_run handles the bulk
of the work, interpreting all messages and parceling out the work
to the lower level routines. They each have their own keyboard
and mouse handlers so that they operate as closed systems or
black boxes. You call the routines, they execute, put the
results into the target variables, and return to the calling
function. The application programmer doesn't deal with message
queues, keyboards, or mice--A BLACK BOX.

But inside the black box keyboard and mouse handlers interpret
keyboard and mouse activity into messages. The messages are then
placed into a queue and processed. Despite being somewhat





- 5 -





DialogPro v 2.0 Users Guide
Reference Manual


"invisible" the capability to manipulate the message queues is
there. Manipulating messages directly can give you added
flexibility.


Using the KEYBOARD

Each of the "standard" commands recognized by a dialog box (see
DBOPS.H for a complete list) can be associated with a keyboard
code (a scan code & ascii code two byte sequence.) This keyboard
interface is represented as an array of integers where its
position in the array relates to the standard message value, i.e.
a message with a value of 1 is created when the keyboard code in
the first position (the 0th element) in the array is recognized,
a message with a value of 2 for the second position, etc.


Using the MOUSE

First, in the same way that the keyboard generates dialog box
messages, so do the mouse handler routines. You can even modify
the mouse interface (although not as directly as the keyboard
interface) by defining macros which intercept the mouse generated
messages and redefine those messages.

However, practically speaking the difference between the mouse
and the keyboard is that the mouse can click on "things" it sees
on the screen that may not be related to the current process. In
general terms the way this is dealt with is -- when a mouse event
is recognized we determine if it is "within" the screen space
representing the "object" (like a dialog box's window for
instance.) Next, if it is within the "object's" boundaries we
compare the mouse hit's location to the areas occupied by all of
the sub-objects related to the current object. If the hit was on
a sub-object. We call the sub-objects calling routine and pass
it a message indicating that a mouse hit happened within its
boundaries. The sub-object then goes through the same process
until eventually one of these subordinate objects deals with the
mouse hit by modifying its data structure in some way -- for
example by indicating that a certain item in a list is selected.

A mouse hit which happens outside of the boundaries of the
current object is handled in a similar way by exiting the current
routine with a value indicating to the superior object that it
has a mouse hit outside of its boundaries. The superior object
then deals with the mouse hits in the same way as described
above.

To be more specific on how this is dealt with in The DialogPro,
consider the db_run routine. Simply executing
db_run(db_data_ptr, 0) would display the dialog box represented
by db_data_ptr and begin gathering input from the keyboard and
mouse, interpreting those into messages, and executing the
messages. The second parameter indicates the first message to be



- 6 -





DialogPro v 2.0 Users Guide
Reference Manual


executed, normally this is 0 (indicating no message.) Of course
you can use this for anything you want -- but the major purpose
is for letting the dialog box deal with a mouse hit inside of its
window borders, i.e. if a mouse hit is detected inside of a
dialog box, while the application is executing another routine,
that routine would execute db_run(db_data_ptr, MOUSE_EVENT). The
MOUSE_EVENT indicates to take the last mouse activity returned by
The WindowPro function kb_mouseclicks and interpret it into a new
message, like select a question, edit a response, etc.

To apply this to the real world, suppose you are writing "ZIPPY
WORD PROCESSOR". The entire screen is reserved for editing text,
but you have a dialog box on the screen to let the user change
formatting characterstics. While editing text you poll both the
keyboard and the mouse (using kb_mouseclicks.) If the keyboard
is hit you deal with it as you would in a traditional program.
But if a mouse event takes place you could deal with it like
this-- Via kb_mouseclicks you recognize that the user has clicked
the mouse. Using wn_whereon you determine that he has clicked in
the formatting dialog box. So, you call
db_run(format_dialog_box, MOUSE_EVENT). db_run picks it up from
this point.

It determines that the last mouse event was indeed inside the
format_dialog_box, on a question representing the value of the
right hand margin. db_run executes the line editor placing the
cursor where the user clicked his mouse. The user edits the
right margin value. Via the "post" question routines you
attached to this question it checks to make sure that the value
is greater than the left hand margin. The user then "clicks"
back inside of the text editor. db_run now updates the target
variables in your application hooked into the dialog box,
updating your global variable RIGHT_MARGIN with the new value,
and exits.

Now its your turn. Based on db_run's exit value you know that
the user has clicked outside of the formatting dialog box, you
check to see if your formatting variables have changed. They
have so you reformat the document. You then check to see if the
use clicked inside of the text editor (using wn_whereon) he has
so you position the cursor at the location of the last mouse
click, and go back to editing text.


Creating and Interpreting Messages

To understand how messages are created and interpreted.

Each data structure has a function to display it and execute it.
Each of these functions handles messages like this.

1. It takes the message passed as a parameter and puts it
at the head of the current circular queue.




- 7 -





DialogPro v 2.0 Users Guide
Reference Manual


2. It looks for a message at the tail of the queue.

A. If a message is found:

a. It first looks up the message in the macro
list. If the message is a macro it expands
the macro by putting the new messages at the
tail of the queue, and then returns to step
2,

b. Messages must have a value of less than 256.
If the message has a value of greater than
256 we assume that it is an extended keyboard
code. The extended kyeboard code is
intepreted into a "real" message". The
"real" message is placed at the tail of the
queue, and it then returns to step 2.

c. If we make it past steps 2.A.a and 2.A.b we
execute the message. The CONFIRM, ABORT,
SPECIAL messages terminate db_run and return
back to the calling function. If the message
is not one of the above it returns to step 2
to get another message to execute.

C. If no message is found, it polls the mouse and the
keyboard waiting for activity. If activity is
found, the activity is interpreted into a message
and put at the tail of the queue -- it then
returns to step 2.


You can modify the behavior of The DialogPro by manipulating the
message queues. Several functions are provided for putting
messages at the head and the tail, and for reading the message
queue.


The Questions

FREE_FORM

Free form questions are used to gather one line text responses.
The text can be up to a thousand characters long. The response
area can be any size. While editing, the response text scrolls
within the response area. The line editor has home, end, word
right/left, and character right/left, backspace and delete
functions. Clicking on any character places the cursor on the
character.


MULTI_CHOICE





- 8 -





DialogPro v 2.0 Users Guide
Reference Manual


Multiple choice questions can be configured to operate as pull
down menus or as more traditional multiple choice questions. The
principle difference is that the current response to a multiple
choice question is displayed in the response area. The pulldown
menu type doesn't display the current response.

The user cycles through the responses to a multiple choice
question with PRESS_BUTTON, or selects the next response
beginning with a specific character, or pulls down the list of
available choices with the DESCEND or EXPAND commands -- and then
selects his choice from the complete list. With the mouse, the
user cycles through the available responses by clicking on the
response area. He pulls down the list of available responses by
double-clicking, or holding, on the response area.


RADIO BUTTONS

Radio buttons serve the same purpose as multiple choice
questions, except that all of your available choices are
displayed in the dialog box rather than just your currently
selected choice.


CHECKBOXES

Checkboxes let you toggle an item on and off.


REDUCER

Reducer questions operate just like free_form except that after
confirming DialogPro compares the response to a list of available
responses. If there is only one response which matches the
current response -- nothing happens. If more than one available
response begin with the same letters as the given response, the
response is considered ambiguous and a list of possible matches
is displayed in a pulldown list. The user then selects his
response from the pulldown list.

The user can skip the reduction stage and go straight to the list
by pressing EXPAND.

The user can view the entire list by double-clicking or holding
on the response area with the mouse.


LIST

There are two types of lists, select list and checklist. The
checklist allows more than one item to be "checked-off." he
select list allows only one item at a time to be "checked-off."





- 9 -





DialogPro v 2.0 Users Guide
Reference Manual


A list response area is rectangular. If the list is bigger than
the rectangular area the user can scroll the list.

The user can modify the selections by placing the cursor inside
the list. The user can then check-off items using PRESS_BUTTON
or navigate to another question.

With the mouse, clicking on an item in the list will toggle it
between checked and un-checked. Holding or clicking on the
scroll bar hotpoints, or holding and dragging the scroll bar
thumbwheels scroll the list.


BUTTON

The user executes a button by pressing the key it is "bound" to.
Pressing the "bound" key will place the button's command key in
the message queue. This lets buttons behave as another way of
executing a CONFIRM, or ABORT, or any command -- or keystroke. A
kind of visual representation of commands.

You can also execute a key by pressing its mnemonic key. Its
mnemonic key will first make the button the selected question and
then put the command key in the message queue. The basic
difference is that the first method does not change the selected
question, or highlighting. This method changes the highlighted
item to the button.

You can also execute a button by navigating to it (or
highlighting it) and then executing PRESS_BUTTON.

With the mouse, clicking on a button is the same as pressing the
"bound" key. Holding on a button and then releasing it the same
as pressing the mnemonic key.

Buttons may or may not have a border. Buttons without borders
are useful for making words in a text behave like hot-points
(useful in hypertext type applications, help screens, etc.) or in
creating new hot-points that work like the scroll bars, for
example, creating a sliding scale in a dialog box would be done
with borderless buttons representing different parts of the scale
(an up button, a down button, the scale itself, etc. -- this lets
users literally reach out and grab a piece of your invention and
move it around the screen, pull levers, push buttons, and move
sliding scales.)

SCROLLING TEXT

Scrolling text questions is really a misnomer. Scrolling text
allows you to place a sub-window within the dialog box and then
associate a controlling routine with that sub-window. Some of
the common uses for this would be, for example, a box of
scrolling text, or a sub-dialog box. Sample control routines for




- 10 -





DialogPro v 2.0 Users Guide
Reference Manual


both of these types of SCROLLING TEXT questions are included.
But, you can create your own routines, infinitely extending the
abilities of The DialogPro.






















































- 11 -





DialogPro v 2.0 Users Guide
Reference Manual


IV. Shareware

Seabreeze Software distributes DialogPro under the shareware
marketing concept. Because DialogPro is shareware you can freely
copy and share the DialogPro shareware diskette with its programs
and manual. You can also obtain it from Seabreeze Software for
$15 (the cost of the diskette, postage, and handling.) In fact,
we hope you do help us by sharing unmodified copies of the
DialogPro shareware diskette with other programmers.

You may incorporate DialogPro into your programs and distribute
those programs absolutely royalty free (see registration section
for details.) You may not however sell, or give away, the
DialogPro source code -- even if you purchase the right to use it
(see registration section.)










































- 12 -





DialogPro v 2.0 Users Guide
Reference Manual


V. Registration

Shareware is software which can be freely copied and
distributed. It is copyrighted software which the author
encourages people to copy and share with others.

You can register with Seabreeze Software for three levels of
support:

. For $50 you receive

. A serialized diskette containing all the latest libraries
for all supported compilers and memory models.

. Single user telephone support (BBS, Compuserve, and
voice.) See next section for details.

. Notification of updates for one year.

. For $100 you receive

. the above, and
. one hundred pages of liberally commented source code (on
diskette,)

This support-level is usable for non-commercial
programs. Non-commercial programs are those created for
limited user (less than 50 users) installations (as
typically might be found in a small consulting situation
or a small corporate software development setting,) or
for unlimited shareware or freeware distribution.

. For $200 you receive

. the above, plus
. the right to use DialogPro in commercial applications.

. Call for details regarding site licensing, consulting
services, and customizations.


Seabreeze Software retains the following rights:

. If you purchase the source code you may not distribute it
except as part of an application program. In other words,
you can't resell the source in its current or modified form
in a way that competes with the original product.

. If you provide the DialogPro source code to a purchaser of
your applications software you must leave the remarks in the
source code indicating that the original copyright is held by
Seabreeze Software. If you rewrite portions of DialogPro you





- 13 -





DialogPro v 2.0 Users Guide
Reference Manual


must point out the modifications made by yourself and you are
legally obligated to leave the original copyright notice in
the source code.

. Seabreeze Software may modify its pricing and distribution
policies at any time without notification. This does not
imply that we will not honor our contractual obligations. But
that we reserve the right to not contract for the above
services at the above prices, i.e. we are not bound by 'old'
advertising.

The registration form is at the back of this manual.













































- 14 -





DialogPro v 2.0 Users Guide
Reference Manual


VI. Support Details

Support is provided under three methods.

. E-mail. Send mail to Seabreeze Software, Compuserve ID#
72330, 705

. Voice. You may call Seabreeze Software directly at
214-437-2729, Monday through Friday, 9 a.m. to 5 p.m.
Central Time.

Technical support is available to registered users only, you must
leave your license agreement number, your name, and instructions
for answering the question (like - "please answer via Compuserve
E-mail ID# XXXXX, XXX." or "Please call me at XXX-XXX-XXXX for
verbal consultation.") Give as many details as possible.
Answers will generally be received within 24 hours or less,
Monday through Friday.

Seabreeze Software will respond to general questions from
unregistered users, like "I have version X.XX, what is the latest
version?" or "What is the current price for support level X?" We
cannot respond to technical questions from unregistered users.


































- 15 -





DialogPro v 2.0 Users Guide
Reference Manual


VII. Diskette

The shareware diskettes should contain the following files:

READ.ME Any last minute corrections, additions, etc.
PKXARC.COM Unarchives Pro.arc
DBPRO1.ARC This manual and demo exe files
DBPRO2.ARC Required include, batch, and source files
DBPRO3.ARC Microsoft MS C/Quick-C libraries
DBPRO4.ARC Turbo-C libraries
DBPRO5.ARC Quick-C quicklib

dbpro1.arc, dbpro2.arc, dbpro3.arc, dbpro4.arc & dbpro5.arc
contain:

DBPRO.TXT Users guide and reference manual for The
DialogPro
MSDBPROM.LIB DialogPro MS C / Quick C medium model library
MSDBPROL.LIB DialogPro MS C / Quick C large model library
QCDBPRO.QLB DialogPro Quick C quicklib
TCDBPROM.LIB DialogPro Turbo C medium model library
TCDBPROL.LIB DialogPro Turbo C large model library
DBERRORS.H DialogPro include files
DBOPS.H "
DBPRO.H "
MAKEMENU.C Demo programs for creating pulldown menus
with the DialogPro
MAKEMENU.H "
MENUDEMO.C "
MSMENU_L.BAT Compiler/linker driver batch files for
compiling and linking the menu demo.
MSMENU_M.BAT "
QCMENU_L.BAT "
QCMENU_M.BAT "
TCMENU_L.BAT "
TCMENU_M.BAT "
MENU_L.PRJ Turbo-C project files for pulldown menu
example.
MENU_M.PRJ "
SIMPLEDB.C Easy example of a simple dialog box
SIMPLDBL.PRJ Turbo-C project files for above sample
program.
SIMPLDBM.PRJ "
QCDBPROM.BAT Generic Quick C medium model DialogPro
compile/link batch file
QCDBPROL.BAT Generic Quick C large model DialogPro
compile/link batch file
MSDBPROM.BAT Generic MS C medium model DialogPro
compile/link batch file
MSDBPROL.BAT Generic MS C large model DialogPro
compile/link batch file
TCDBPROM.BAT Generic Turbo C medium model DialogPro
compile/link batch file




- 16 -





DialogPro v 2.0 Users Guide
Reference Manual


TCDBPROL.BAT Generic Turbo C large model DialogPro
compile/link batch file

Note: BBS operators may repackage The DialogPro files to optimize
on-line time. If you received your files via a BBS please make
sure you have all of The DialogPro shareware files.



















































- 17 -





DialogPro v 2.0 Users Guide
Reference Manual


VIII. Installation

1. Backup your shareware diskette.

2. Type "pkxarc dbpro1" at the dos prompt and press ENTER, and
then "pkxarc dbpro2". Pkxarc will unarc dbpro1.arc &
dbpro2.arc into the current default directory. You can run
pkxarc.exe from another directory, and unarc dbpro1.arc
located on another drive or directory by preceding each with
a drive and directory specification, for example


C:\Pro>a:pkxarc a:dbpro1

will run pkxarc from the a: drive and unarc dbpro1.arc
located on the a: drive into the c: drive and the "Pro"
sub-directory.

Repeat for dbpro3.arc and dbpro4.arc.

3. Copy the library files for your compiler (extension of
".lib") to the diskette or sub-directory you usually use
with your C compiler. The lib files should be in the same
sub-directory as your C runtime libraries.

































- 18 -





DialogPro v 2.0 Users Guide
Reference Manual


IX. Compiling and linking the demo

Confirm proper installation by compiling one of the demo
programs. Compile makemenu.c by typing one of the following at
the dos prompt.

msmenu_l
msmenu_m
qcmenu_l
qcmenu_m
tcmenu_l
tcmenu_m

Or compile or simpledb.c by typing

msdbprol simpledb
msdbprom simpledb
qcdbprol simpledb
qcdbprom simpledb
tcdbprol simpledb
tcdbprom simpledb

If you were unable to compile and link check to make sure that:

TURBO-C :

Determine that you have all of the files listed on the previous
page. Turbo-C is installed as described in the Turbo-C manual,
you are compiling from the TURBOC directory, the source files
are in the default sub-directory, and the TCDBPRO?.LIB files are
installed in the LIB sub-directory.

QUICK-C :

Determine that the LIB, TMP, BIN, and INCLUDE environment
variables have been properly initialized, the MSDBPRO?.LIB files
are included in the subdirectory associated with LIB environment
variable, and the source files are in your default directory.

If the problem persists contact Seabreeze Software Customer
Support.
















- 19 -





DialogPro v 2.0 Users Guide
Reference Manual


X. Changes between version 1.0 and 2.0

Changes between 1.0 and 1.1

Documentation

We realize that The DialogPro represents somewhat of a departure
from the programming style you may be used to. To help the
transition we have provided three, new, heavily commented
examples.

Upgrades

All operations now pass through the queue before being executed.
Previously, if there was no operation in the queue the
keyboard/mouse interpreter would poll until it received an event
which translated into a command. The command was then
immediately executed. These commands are now passed into the
queue and then only executed as they are removed from the queue.
This makes debugging about 100% easier.

Added features

New question type. A new question type has been added,
scroll_txt. This question type can be used for creating custom
question types but includes two functions for using scroll_txt.
The included functions help you use scroll_txt as a scrolling
text box or as a sub dialog box.

Monitoring. The command queue can now be monitored. To monitor
the command queue simply turn on the monitor switch and assign
the monitor to a window handle. The command queue monitor will
then continuously scroll in the monitor window. You can slow
down queue execution with a delay factor or step through the
command queue by keystroke. This is a tremendously effective way
to debug dialog boxes.

New list type. Elements in a list can now be indicated to be
marked, unmarked, and in version 1.1 as titles. Titles cannot be
selected or returned as a selected item. Use them to divide
lists into segments -- e.g. segmented pull down menus.

New commands. The EXECUTE command allows you to place the
address of a function in the command queue. After EXECUTE is
received the next two parameters off of the queue are used to
construct a far address to a function. The dialog box then calls
the function using a pointer to the dialog box as a parameter.
If required, You can pass additional parameters to this function
through the command queue. This feature allows you to construct
macros which call other functions. Tremendously useful.



Changes between 1.1 and 2.0



- 20 -





DialogPro v 2.0 Users Guide
Reference Manual



DialogPro now supports radio buttons, check boxes, and
multi-column lists.

DialogPro now allows delimiters to be placed completely around a
response area (a box) rather than just to the left and right.

DialogPro's default settings are now more similar to SAA user
interface standards.

DialogPro has improved speed, particularly with list type
questions.

DialogPro now has global macros. You can now define macros which
are global or local. global macros are always processed before
local macros. This is very useful in creating application-wide
hotkeys.

You no longer specify an up,down,left,right for each question.
Instead you can only navigate to the next and previous questions
which is determined by the questions position within the question
array.

We have added an idle function pointer, which will repeatedly
call the function it points to as the keyboard and mouse are
polled.

Every structure which required a window handle has been added
additional strucutre members to describe the window. If the
window handle is not valid it is automatically created based on
these values. You can therefore describe most dialog boxes
entirely at compile time.

Added some new #defines to simplify creating DialogPro macros.

Dialog box colors and delimiters are now specified through a
pointer to a color and delimiter structure rather than explicitly
specified in each dialog box. This makes it much simpler to
implement design changes.



















- 21 -





DialogPro v 2.0 Users Guide
Reference Manual


XI. Future enhancements

Action Bars -- Again this is real similar to the makemenu.c
demonstration. However we may streamline it down and make it
more similar to the MS-WINDOW'S programmer's interface.

OS/2 -- very soon. We are currently testing the OS/2 version.


















































- 22 -





DialogPro v 2.0 Users Guide
Reference Manual


XII. Reference

A. Introduction

Generally speaking you only need to be familiar with the
functions db_run, lst_run, db_switchqueue, and the data
structures dialog_box and list_rec. All of the other functions
are documented solely to assist the application programmer in
writing pre and post routines to attach to questions. Using
these functions can help you do things like modify the dialog_box
structure based on an interim response. Typically this technique
is used to gray-out a questions in a dialog box based on another
response or to perform other similar processes.

The DialogPro is targeted for experienced applications
developers. The best way to learn how to use the DialogPro is by
studying, running, and modifying the sample programs menudemo and
simpledb.







































- 23 -





DialogPro v 2.0 Users Guide
Reference Manual


B. Functions

1. db_display

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_display(db_ptr)
______
i )
______

dialog_box *db_ptr;
_______
dialog_box *
_______


b. Description

Displays the dialog box pointed to by dp_ptr. If the window
________
associated with db_ptr is not on the screen it will be opened via
______
a call to wn_openw. If the window associated with the dialog box
wn_openw
(db_ptr->handle) is open but is not the last_wdw (on top of the
______
->handle last_wdw
______
stack of windows) and db_ptr->bg_operation is TRUE it will be
______
->bg_operation
______
brought to the top of the stack by a call to wn_openw.
wn_openw


c. Return Value

See section Standard Return Values.


2. db_displayq

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_displayq(db_ptr, question_id)
______ ___________
int db_displayq( , )
______ ___________

dialog_box *db_ptr;
_______
dialog_box *
_______
unsigned char question_id;
____________
unsigned char
____________


b. Description

Displays the question pointed to by
db_ptr->questions[question_id] in the window db_ptr->handle.
______ ___________ ______
->questions[ ] ->handle
______ ___________ ______


c. Return Value

See section Standard Return Values.








- 24 -





DialogPro v 2.0 Users Guide
Reference Manual


3. db_flushqueue

a. Summary

#include "dbpro.h"
#include "dbpro.h"

void db_flushqueue(void)
____
void db flushqueue
____


b. Description

Clears all messages in the queue, db_queue. Indiscriminate use
db queue
of db_flushqueue() is not advised. It may interfere with the
processing of macros. It is best to discard only those messages
which you are sure you do not want.


c. Return Value

None.


4. db_freestorage

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_freestorage(db_ptr, insurance)
______ _________
int db_freestorage( , )
______ _________

dialog_box *db_ptr;
_______
dialog_box *
_______
storage **insurance;
__________
storage **
__________


b. Description

If *insurance does not equal NULL the data structure pointed to
__________
NULL
__________
by *insurance is freed and *insurance is set to NULL.
__________ __________
NULL
__________ __________

If *insurance is equal to NULL, nothing happens.
__________
NULL
__________

(Normally **insurance is the same as &(db_ptr->insurance).
___________ ______
&( ->insurance)
___________ ______
db_ptr->insurance is used by db_run to point to the previous
______
->insurance db_run
______
answers to the dialog box.)


c. Return Value

See section Standard Return Values.








- 25 -





DialogPro v 2.0 Users Guide
Reference Manual


5. db_pop

a. Summary

#include "dbpro.h"
#include "dbpro.h"

unsigned db_pop(void)
____
unsigned db pop
____


b. Description

Reads the next message from the tail of the queue, db_queue.
db queue


c. Return Value

<> - 1 Function executed properly.

-1 The queue is empty.


6. db_priority

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_priority(new_event)
___ _____
int db priority
___ _____

unsigned new_event;
___ _____
unsigned
___ _____


b. Description

Puts new_message at the tail of the queue, db_queue.
___ _______
db queue
___ _______


c. Return Value

TRUE Function executed properly.
TRUE

FALSE The queue is full (a queue can only have 256 messages
FALSE
in it.)


7. db_push

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_push(new_event)
___ _____
int db push
___ _____

unsigned new_event;
___ _____
unsigned
___ _____



- 26 -





DialogPro v 2.0 Users Guide
Reference Manual


b. Description

Puts new_message at the head of the queue, db_queue.
___ _______
db queue
___ _______


c. Return Value

TRUE Function executed properly.
TRUE

FALSE The queue is full (a queue can only have 256 messages
FALSE
in it.)


8. db_restoreanswers

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_restoreanswers(db_ptr, insurance)
______ _________
int db_restoreanswers( , )
______ _________

dialog_box *db_ptr;
_______
dialog_box *
_______
storage **insurance;
__________
storage **
__________


b. Description

If *insurance is not equal to NULL the answers to the dialog box,
__________
NULL
__________
db_ptr, are changed to the answers recorded in the data structure
______
(which only contains the answers) of type storage pointed to by
storage
*insurance. The storage data structure is freed and *insurance
__________
storage
__________
is set to NULL.
NULL

If insurance is equal to NULL, nothing happens.
_________
NULL
_________

(Normally **insurance is the same as &(db_ptr->insurance).
___________ ______
&( ->insurance)
___________ ______
db_ptr->insurance is used by db_run to point to the previous
______
->insurance db_run
______
answers to the dialog box.)


c. Return Value

See section Standard Return Values.


9. db_run

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_run(db_ptr, message)
______ _______
int db_run( , message)
______ _______

dialog_box *db_ptr;
_______
dialog_box *
_______



- 27 -





DialogPro v 2.0 Users Guide
Reference Manual


unsigned message;
________
unsigned
________


b. Description

The function db_run executes the messages in the message queue
db_run
pointed to by db_queue against the dialog box data structure
db_queue
db_ptr. (It is very important that a message queue have been
______
initialized via a call to db_switchqueue before calling db_run.)
db switchqueue db run

Before executing the message queue it first places the standard
message STORAGE at the tail of the queue and then it places the
STORAGE
parameter message at the head of the queue. All messages are
_______
retrieved from the tail of the queue. Each retrieved message is
checked against the macro list db_ptr->macros. If the message is
______
->macros
______
a macro it is expanded by placing the items pointed to by the
macro at the tail of the queue in reverse order.

If there are no messages in the message queue db_run polls the
db_run
kyeboard and mouse (if one is recognized when wn_init is
called.) When activity is noted the keyboard/mouse activity is
translated into a message and placed at the tail of the queue.

If it is a mouse event the message MOUSE_EVENT is placed at the
MOUSE_EVENT
tail of the queue. The MOUSE_EVENT message takes the last mouse
MOUSE_EVENT
event, translates it into a message and places it at the tail of
the queue.

It it is a keyboard event, the keystroke is first compared
against the the shortcut key of each of the questions, starting
at the current question + 1 and ending at the current question.
The first question whose shortcut key matches the keystroke is
selected. If the question is a button and it matches
BUTTONQUEST(question_id)->key the button is selected, the
BUTTONQUEST(question_id)->key
keystroke value is replaced with the value
BUTTONQUEST(question_id)->cmd_key, and the global variable
BUTTONQUEST(question_id)->cmd_key
button_press is set the the value of
button_press
BUTTONQUEST(question_id)->exitval. If the question is a button
BUTTONQUEST(question_id)->exitval
and it matches BUTTONQUEST(question_id)->keybind the current
BUTTONQUEST(question_id)->keybind
question remains selected, and the keystroke value is replaced
with the value BUTTONQUEST(question_id)->cmd_key, and the global
BUTTONQUEST(question_id)->cmd_key
variable button_press is set the the value of
BUTTONQUEST(question_id)->exitval.
BUTTONQUEST(question_id)->exitval

The new keystroke value is then compared against the
keystroke-command table. If the keystroke is in the table the
keystroke is interpreted into a standard event. If it is not, it
is processed as a keystroke value. Alphanumeric Keystrokes can
be used to begin editing a free_form, a reducer, or select a
multiple choice response.

When one of several exit type messages is received db_run
terminates.




- 28 -





DialogPro v 2.0 Users Guide
Reference Manual


The actual message selection/interpretation code explains it a
little more succinctly:

do {

/* get event from queue */
if (!NO_EVENT) event = db_pop();

/* or from keyboard/mouse */
else event = get_dbevent(db_ptr);

} while

/* expand macros */
(db_executemacros(event, db_ptr->macros));


/* if event is a keystroke value ... */
if (event > 256) {

/* get ascii code */
ascii = event % 256;

/* check shortcut keys */
button_press = db_touchbutton(db_ptr, &event);

/* translate into a message */
event = db_getopcode(db_ptr, event);
}




c. Return Value

See section Standard Return Values.

Note that if this function returns with a value of CONFIRMED or
ABORTED that it has also placed a CONFIRM or ABORT message in the
queue. Many programmers find that using the queue for sending
and receiving arguments and return values is the cleanest way to
use the DialogPro. On the other hand, particularly if you are
integrating the DialogPro into an existing application you may
want to discard these messages. Use db_pop() to discard the the
unwanted message, or db_flushqueue() to discard all messages in
the queue.


10. db_selectq

a. Summary

#include "dbpro.h"
#include "dbpro.h"




- 29 -





DialogPro v 2.0 Users Guide
Reference Manual


int db_selectq(db_ptr, question_id)
______ ___________
int db_selectq( , )
______ ___________

dialog_box *db_ptr;
_______
dialog_box *
_______
unsigned char question_id;
____________
unsigned char
____________


b. Description

Makes db_ptr->id_select equal to question_id. Then displays the
question pointed to previously by
db_ptr->questions[db_ptr->id_select] (dehighlighting the
question) and then displays the question
db_ptr->questions[question_id] (highlighting it--as it is now the
______ ___________
->questions[ ]
______ ___________
selected question.)

Before dehighlighting the first question, the function pointed to
by (*) FIRST_QUESTION->whenoff(db_ptr) is executed, if
FIRST_QUESTION->whenoff(db_ptr) does not return TRUE db_selectq
terminates without modifying db_ptr->id_select.

After dehighlighting the second question, the function pointed to
by (*) SECOND_QUESTION->whenon(db_ptr) is executed, if
SECOND_QUESTION->whenon(db_ptr) does not return TRUE db_selectq
terminates without modifying db_ptr->id_select.


(*) FIRST_QUESTION and SECOND_QUESTION are generic pointers use
for illustrative purposes representing what would be the specific
pointer type for each question. Each question type has its own
pointer type.


c. Return Value

See section Standard Return Values.


11. db_storeanswers

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_storeanswers(db_ptr, insurance)
______ _________
int db_storeanswers( , )
______ _________

dialog_box *db_ptr;
_______
dialog_box *
_______
storage **insurance;
__________
storage **
__________










- 30 -





DialogPro v 2.0 Users Guide
Reference Manual


b. Description

If *insurance is equal to NULL the answers to the dialog box,
__________
NULL
__________
db_ptr, are stored in an interim data structure (which only
______
contains the answers) of type storage and *insurance returns the
__________
storage
__________
pointer to the data structure.

If insurance is not equal to NULL, nothing happens.
_________
NULL
_________

(Normally **insurance is the same as &(db_ptr->insurance).
___________ ______
&( ->insurance)
___________ ______
db_ptr->insurance is used by db_run to point to the previous
______
->insurance db_run
______
answers to the dialog box.)


c. Return Value

See section Standard Return Values.


12. db_switchqueue

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int db_switchqueue(head, tail, queue)
____ ____ _____
int db switchqueue
____ ____ _____

unsigned char *head, *tail;
____ ____
unsigned char
____ ____
unsigned *queue;
_____
unsigned
_____


b. Description

db_switchqueue associates variables representing the head, tail,
db switchqueue
and circular message queue used by db_run and lst_run. This
db run lst run
function must be called once before using db_run or lst_run. It
db run lst run
only has to be called once and then db_run and lst_run can be
db run lst run
used as many times necessary. You can however call this more
than once if you want to use separate message queues for
different dialog boxes.

queue must be a pointer to a 512 byte memory block (256
_____
integers.) head and tail should be pointers to existing unsigned
____ ____
chars. head and tail should be initialized to their proper
____ ____
values before calling db_switchqueue. If you are just
db switchqueue
initializing a brand new queue both would be 0.


c. Return Value

None.






- 31 -






DialogPro v 2.0 Users Guide
Reference Manual


13. lst_display

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int lst_display(list_ptr, mode)
________ ____
int lst_display
________ ____

list_rec *list_ptr;
________
list_rec *
________
unsigned char mode;
____
unsigned char
____


b. Description

Refreshes the display of the list, list_ptr.
________


If mode is equal to
____

0 The window, lst_ptr->handle, is brought to the top of
________ ______
lst_ptr
________ ______
the stack of windows via a call to wn_openw.
wn_openw

1 The window, lst_ptr->handle, is brought to the top of
______
lst ptr-
______
the stack of windows via a call to q_open. q_open is
q open q open
faster than wn_openw but no windowing functions which
wn openw
disrupt the order of display (wn_closew, wn_openw, or
wn closew wn openw
wn_activew) should be called without first removing the
wn activew
window by a call to q_close. This mode is used in pull
q close
down menus for example because it is designed in a way
that makes certain that the window is closed on exit.

2 Only the virtual screen is refreshed. The changes are
not updated on the physical screen.

These data structures members may be effected by lst_display
(Note: in the following listing TILE is defined as
TILE
window[lst_ptr->handle]->tiles[lst_ptr->tile_handle] and WDW is
___ ____ ___ ____
window handle tiles tile handle WDW
___ ____ ___ ____
defined as window[lst_ptr->handle]):
___ ____
window handle
___ ____

lst_ptr->optlen The length of the longest string in
___ ____
optlen
___ ____
the list of options.

lst_ptr->taglen The length of the longest on/off
___ ____
taglen
___ ____
tag (displayed to the left of each
option in the list.

lst_ptr->numopts The number of options in the list.
___ ____
numopts
___ ____

TILE->virtual_screen If (TILE->vs_rows *
TILE- virtual screen TILE- vs rows
TILE->vs_columns) >
TILE- vs columns
(lst_ptr->numopts *
___ ____
numopts
___ ____
(lst_ptr->taglen +
___ ____
taglen
___ ____
lst_ptr->optlen)) then
___ ____
optlen
___ ____
TILE->virtual_screen is deallocated
TILE- virtual screen



- 32 -





DialogPro v 2.0 Users Guide
Reference Manual


and a larger memory block is
allocated. TILE->virtual_screen
TILE- virtual screen
then points to the new memory
block.

TILE->vs_rows,
TILE- vs rows
TILE->vs_columns If TILE->vs_rows does not equal
TILE- vs columns TILE- vs rows
lst_ptr->numopts or
___ ____
numopts
___ ____
TILE->vs_columns does not equal
TILE- vs columns
(lst_ptr->optlen + lst_ptr->taglen)
___ ____ ___ ____
optlen taglen
___ ____ ___ ____
then TILE->vs_columns is set equal
TILE- vs columns
to lst_ptr->optlen +
___ ____
optlen
___ ____
lst_ptr->taglen and TILE->vs_rows
___ ____
taglen TILE- vs rows
___ ____
is calculated based on the size of
the memory block pointed to by
TILE->virtual_screen.
TILE- virtual screen

WDW->port_columns If lst_ptr->auto_horiz is TRUE and
___ ____
WDW- port columns auto horiz TRUE
___ ____
lst_ptr->optlen + lst_ptr->taglen
___ ____ ___ ____
optlen taglen
___ ____ ___ ____
does not equal WDW->port_columns,
WDW- port columns
WDW->port_columns is set equal to
WDW- port columns
lst_ptr->optlen + lst_ptr->taglen.
___ ____ ___ ____
optlen taglen
___ ____ ___ ____

WDW->port_rows If lst_ptr->auto_vert is TRUE and
___ ____
WDW- port rows auto vert TRUE
___ ____
lst_ptr->numopts does not equal
___ ____
numopts
___ ____
WDW->port_rows, WDW->port_rows is
WDW- port rows WDW- port rows
set equal to lst_ptr->numopts.
___ ____
numopts
___ ____


If the list is not changed this function operates quickly. If
the list is larger than the previous list lst_display must free
lst display
the original virtual screen and allocate memory for the new
virtual screen. This can make for a small hiccup when opening a
modified list. You can get around this hiccup by calling
lst_display with mode equal to 0 after modifying the list at a
point where processing speed is less critical. When lst_display
lst display
is called (probably via lst_run) for actual display the user will
lst run
not notice any delay.


c. Return Value

See section Standard Return Values.


14. lst_displayitem

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int lst_displayitem(list_ptr, offset)
________ ______
int lst_displayitem
________ ______

list_rec *list_ptr;
________
list_rec *
________



- 33 -





DialogPro v 2.0 Users Guide
Reference Manual


int offset;
______
int
______


b. Description

Refreshes the display of the offset item (the first item is 0) in
______
the list list_ptr.
________

If offset is greater than the number of items in the list
______
(list_ptr->numopts) then a blank line is output at that row in
_________
->numopts
_________
the virtual screen.

If offset is greater than the last row in the virtual screen
______
an OUT_OF_RANGE error is returned.
OUT_OF_RANGE


c. Return Value

See section Standard Return Values.


15. lst_freestorage

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int lst_freestorage(insurance)
_________
int lst_freestorage( )
_________

lst_storage **insurance;
__________
lst_storage **
__________


b. Description

If *insurance does not equal NULL the data structure pointed to
__________
NULL
__________
by *insurance is freed and *insurance is set to NULL.
__________ __________
NULL
__________ __________

If *insurance is equal to NULL, nothing happens.
__________
NULL
__________

(Normally **insurance is the same as &(lst_ptr->insurance).
___________ _______
&( ->insurance)
___________ _______
lst_ptr->insurance is used by lst_run to point to the previous
_______
->insurance lst_run
_______
answers to the list.)


c. Return Value

See section Standard Return Values.


16. lst_restoreanswers

a. Summary

#include "dbpro.h"
#include "dbpro.h"



- 34 -





DialogPro v 2.0 Users Guide
Reference Manual



int lst_restoreanswers(lst_ptr, insurance)
_______ _________
int lst_restoreanswers( , )
_______ _________

lst_rec *lst_ptr;
________
lst_rec *
________
lst_storage **insurance;
__________
lst_storage **
__________


b. Description

If *insurance is not equal to NULL the state of the lst, lst_ptr,
__________ _______
NULL
__________ _______
is changed to the answers recorded in the data structure of
type lst_storage pointed to by *insurance. The lst_storage data
__________
lst_storage lst_storage
__________
structure is freed and *insurance is set to NULL.
NULL

If insurance is equal to NULL, nothing happens.
_________
NULL
_________

(Normally **insurance is the same as &(lst_ptr->insurance).
___________ _______
&( ->insurance)
___________ _______
lst_ptr->insurance is used by lst_run to point to the previous
_______
->insurance lst_run
_______
answers to the list.)



c. Return Value

See section Standard Return Values.


17. lst_run

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int lst_run(lst_ptr, message)
_______ _______
int lst_run( , message)
_______ _______

list_rec *lst_ptr;
________
list_rec *
________
unsigned int message;
________
unsigned int
________


b. Description

The function lst_run executes the messages in the message queue
lst_run
pointed to by db_queue against the data structure lst_ptr. (It
_______
db_queue
_______
is very important that a message queue have been initialized via
a call to db_switchqueue before calling lst_run.)
db switchqueue lst run

Before executing the message queue it first places the standard
message STORAGE at the tail of the queue and then it places
STORAGE
message at the head of the queue. All messages are retrieved
from the tail of the queue. Each retrieved message is checked
first against the global macro list, global macros, and then
against the local macro list lst_ptr->macros. If the message is
_______
->macros
_______
a macro it is expanded by placing the items pointed to by the
macro at the tail of the queue in reverse order.



- 35 -





DialogPro v 2.0 Users Guide
Reference Manual



If there are no messages in the message queue lst_run polls the
lst_run
keyboard and mouse (if one is recognized when wn_init is
wn init
called.) When activity is noted the keyboard/mouse activity is
translated into a message and placed at the tail of the queue.

If it is a mouse event the message MOUSE_EVENT is placed at the
MOUSE_EVENT
tail of the queue. The MOUSE_EVENT message takes the last mouse
MOUSE_EVENT
event, translates it into a keystroke and places it at the tail
of the queue.

If the message has a value greater than 256 it is compared
against the keystroke-command table, lst_ptr->cmds. If the
keystroke is in the table it is interpreted into a standard
event.

If the message is less than 256 it is interpreted as a standard
message. Otherwise it is compared against the the shortcut key
of each of the options, starting at the current item + 1 and
ending at the current item. The first item whose shortcut key
matches the keystroke is selected. If lst_ptr->alpha_confirm is
TRUE and lst_ptr->list_type is CHECKLIST then the item is toggles
on/off. If lst_ptr->alpha_confirm is TRUE and lst_ptr->list_type
is SELECT_ONE then the item is set to TRUE and lst_run exits with
a value of CONFIRMED.

When one of several exit type messages is received lst_run
terminates.

The actual message selection/interpretation code explains it a
little more succinctly:

do {

/* get event from queue */
if (!NO_EVENT) event = db_pop();

/* or from keyboard/mouse */
else event = get_lstevent(lst_ptr);

} while

/* expand macros */
(db_executemacros(event, lst_ptr->macros));

/* if event > 256 see if attached to a standard message */
if (event > 256) {
event = lst_opcode(list_ptr, event);
ascii = event % 256;
}

EXECUTE MESSAGE where:

message < 256, standard message,



- 36 -





DialogPro v 2.0 Users Guide
Reference Manual


message > 256, short cut selection.




c. Return Value

See section Standard Return Values.


18. lst_select

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int lst_select(list_ptr, offset)
____ ___ ______
int lst select
____ ___ ______

list_rec *list_ptr;
____ ___
list rec
____ ___
int offset;
______
int
______


b. Description

Dehighlights the currently selected item and highlights the item
offset items above (-) or below (+) relative to the current item.
______

Accounts for rollover.

Does nothing if offset is equal to 0.
______


c. Return Value

See section Standard Return Values.


19. lst_storeanswers

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int lst_storeanswers(lst_ptr, insurance)
_______ _________
int lst_storeanswers( , )
_______ _________

list_rec *lst_ptr;
________
list_rec *
________
lst_storage **insurance;
__________
lst_storage **
__________


b. Description

If *insurance is equal to NULL the state of the list, db_ptr, is
__________ ______
NULL
__________ ______
stored in an interim data structure of type lst_storage and
lst_storage
*insurance returns the pointer to the data structure.
__________




- 37 -





DialogPro v 2.0 Users Guide
Reference Manual


If insurance is not equal to NULL, nothing happens.
_________
NULL
_________

(Normally **insurance is the same as &(lst_ptr->insurance).
___________ _______
&( ->insurance)
___________ _______
lst_ptr->insurance is used by lst_run to point to the previous
_______
->insurance lst_run
_______
answers to the list.)


c. Return Value

See section Standard Return Values.


20. lst_toggle

a. Summary

#include "dbpro.h"
#include "dbpro.h"

int lst_toggle(list_ptr, item)
____ ___ ____
int lst toggle
____ ___ ____

list_rec *list_ptr;
____ ___
list rec
____ ___
int item;
____
int
____


b. Description

If lst_ptr->lst_type is equal to CHECKLIST toggles the value of
___ ____
lst type CHECKLIST
___ ____
lst_ptr->selections[item] between TRUE and FALSE and refreshes
___ ____ ____
selections TRUE FALSE
___ ____ ____
the display of item by calling lst_displayitem.
lst displayitem

If lst_ptr->lst_type is equal to SELECT_ONE all other items in
___ ____
lst type SELECT ONE
___ ____
the list are set to FALSE, lst_ptr->selections[item] is set to
___ ____ ____
FALSE selections
___ ____ ____
TRUE, and the entire list is refreshed.
TRUE

The value of lst_ptr->available[item] must be TRUE.
___ ____ ____
available TRUE
___ ____ ____


c. Return Value

FALSE If lst_ptr->available[item] is FALSE the function
___ ____ ____
FALSE available FALSE
___ ____ ____
terminates early and returns FALSE.
FALSE

TRUE function executed properly.
TRUE














- 38 -





DialogPro v 2.0 Users Guide
Reference Manual


C. Standard Return Values

ABORTED User exited by abort

CONFIRMED User exited by confirm

ASCENDED User exited by ascending

DESCENDED User exited by descending

MOUSED User exited by clicking the mouse
outside of the image of the window
associated with the dialog box.

MENUED User exited by confirming a pull down
menu

OK No errors detected

INVALID_QUESTION_TYPE Dialog box's question list has a
question of a type not defined in
dbpro.h

BAD_PARAMS Coordinates or variables were outside of
a specified range

NULL_POINTER Passed a NULL pointer

OUT_OF_MEMORY Function could not allocate enough
memory to create required data
structures


























- 39 -





DialogPro v 2.0 Users Guide
Reference Manual


D. Data structures

1. button

char question_type must be set to BUTTON.
________ ____
char BUTTON
________ ____

unsigned char tile_handle The question is displayed in this
____ ______
unsigned char
____ ______
tile. tile_handle must be a valid
____ ______
tile handle.

int (*whenon)
______
int
______
(dialog_box *)
dialog box
int (*whenoff)
_______
int
_______
(dialog_box *)
dialog box
int (*action)(dialog_box *) Pointers to edit checking
______
int dialog box
______
routines. db_run executes each
db run
routine under these conditions. On
selecting the question whenon is
______
executed. On selecting a question
other than the current question or
on exiting db_run whenoff is
_______
db run
_______
executed. On pressing the
button action is executed. whenoff
______
must return TRUE or the attempt to
TRUE
navigate to another question will
fail. If any routine is set to
NULL it is not executed. db_run
NULL
always passes the current dialog
box pointer to each edit checking
function.

char *statement A string representing the statement
_________
char
_________
to appear inside the button.

int statementx, statementy Upper left coordinate of the
__________ __________
int
__________ __________
button.

int key Identical to keybind (below), but
___
int
___
the button also becomes the
selected question.

char *boxchars Box drawing characters to be used
________
char
________
in drawing the button border. Use
NULL to indicate no borders. See
NULL
vs_box in The WindowPro reference
vs box
manual for further explanation.

char shading Shading style to be used when
_______
char
_______
drawing the box surrounding the
button. See vs_box in The
vs box
WindowPro reference manual for
further explanation.





- 40 -





DialogPro v 2.0 Users Guide
Reference Manual


int cmdkey On pressing a button this value is
______
int
______
placed at the tail of the message
queue.

int keybind This value binds the keyboard code,
_______
int
_______
keybind, to the button. Generating
_______
this keyboard code will 1-flash the
button, 2-place cmdkey at the tail
______
of the message queue, and 3-execute
action. Note that the selected
______
question is not effected.

char continuous If TRUE, holding the mouse cursor
__________
char TRUE
__________
on the button repeatedly places
PRESS_BUTTON at the tail of the
PRESS BUTTON
message queue. If FALSE only a
FALSE
mouse release will place a single
PRESS_BUTTON at the tail of the
PRESS BUTTON
message queue.

int exitval If cmdkey results in exiting
_______ ______
int
_______ ______
db_run. db_run will exit with the
db run db run
value exitval.
_______


2. db_colors

db_colors represents the attributes to be used when updating a
dialog box. Typically you would set up one db_colors structure
for use with all dialog boxes to establish a personality for your
system. You may also want to have various color schemes for
different types of dialog boxes.


unsigned char title_bg,
__________
unsigned char
__________
title_fg The background and foreground color
______________________________
to use when updating a title.

unsigned char question_bg,
____________
unsigned char
____________
question_fg The background and foreground color
______________________________
to use when updating the statement
portions of questions.

unsigned char response_bg,
_____________
unsigned char
_____________
response_fg The background and foreground color
______________________________
to use when updating an unselected,
available response.

unsigned char un_bg, un_fg The background and foreground color
________________
unsigned char
________________
to use when updating an unselected,
unavailable response.






- 41 -





DialogPro v 2.0 Users Guide
Reference Manual


unsigned char sun_bg, sun_fg The background and foreground color
______________
unsigned char
______________
to use when updating a selected,
unavailable response.

unsigned char select_bg,
____________
unsigned char
____________
select_fg The background and foreground color
______________________________
to use when updating a selected,
available response.

unsigned char key_bg, key_fg The background and foreground color
________________
unsigned char
________________
to use when updating a statement or
list element. Each character
preceded by a ~ in a statement or
list element is output in this
color. If there are no ~s in the
string the first character is
output with this color. Used to
indicate the shortcut keys for a
question.

unsigned char edit_bg,
__________
unsigned char
__________
edit_fg The background and foreground color
_______
to use when using the line editor
in a free_form or reducer.


3. db_delimiters

db_delimiters represents the characters to be placed around the
response portion of questions within a dialog box. Typically you
would set up one db_delimiters structure for use with all dialog
boxes to establish a personality for your system. You may also
want to have various delimiter schemes for different types of
dialog boxes.



unsigned char *ff_boxchars The characters to place around the
___________
unsigned char
___________
response portion of a free_form
free_form
question. These character arrays
are defined the same as the window
border character arrays. Note that
any NULL characters are simply not
NULL
output. This means that you do not
have to triple space questions as
you would by putting a complete box
around each, but could just define
delimiters on either side (as in
DBPRO 1.1) or even none at all.

unsigned char *mc_boxchars Same as ff_boxchars, but for
___________ ___________
unsigned char
___________ ___________
multi_choice questions.





- 42 -





DialogPro v 2.0 Users Guide
Reference Manual


unsigned char *r_boxchars Same as ff_boxchars, but for
__________ ___________
unsigned char
__________ ___________
reducer questions.

char *check_on, *check_off The characters to be placed to the
________ _________
char
________ _________
left of a checkbox statement
indicating that the item is checked
or not checked, e.g. [ ] or [X].

char *radio_on, *radio_off Same as check_on, check_off but for
________ _________
char
________ _________
radio buttons.



4. dialog_box

dialog_box is the basic data type used by almost all of the high
______ ___
level functions. The dialog box data structure consists of the
following members.

int handle Every dialog box must be related to
______
int
______
an existing window. If handle is
______
not a valid window handle a window

handle is created using the window
information at the end of this
structure.

(*post_size)(void *) after db_run processes any sizing
____ ____
void db run
____ ____
messages it executes post_size
____ ____
passing db_ptr as argument.

int (*post_move)(void *) after db_run processes any moving
____ ____
int void db run
____ ____
messages it executes post_move
____ ____
passing db_ptr as argument.

char move_ok db_run will not process any moving
____ __
char db run
____ __
messages if move_ok is FALSE.
____ __
FALSE
____ __

char size_ok db_run will not process any sizing
____ __
char db run
____ __
messages if size_ok is FALSE.
____ __
FALSE
____ __

char **questions pointer to an array representing
_________
char
_________
the list of questions which
comprise the dialog box. The last
item in the array must be a NULL
pointer.

char *available pointer to an array corresponding
_________
char
_________
to the above array, where a value
of FALSE indicates that the
response to the corresponding
question cannot be modified.






- 43 -





DialogPro v 2.0 Users Guide
Reference Manual


char id_select The currently selected question as
__ ______
char
__ ______
an offset in the question array
(questions, above.)
_________

int *cmds An array of extended keyboard codes
____
int
____
corresponding to the standard
messages, where standard message 1
(PRESS_BUTTON) corresponds to
keyboard code in position 0,
message 2 (CONFIRM) corresponds to
the keyboard code in position 1,
etc. This array is used to
interpret keyboard codes into
messages. cmds is generally set to
____
the supplied default keyboard
commands default_db_cmds.
default_db_cmds

char bg_operation If FALSE, when db_run is executed
__ _________
char FALSE db run
__ _________
the dialog box window is brought to
the top of the stack via a call to
wn_openw. If FALSE and the window
wn openw FALSE
is on the screen it remains in its
position in the stack. If FALSE
FALSE
and the window is not on the screen
it is displayed via a call to
wn_openw. In a desktop type
wn_openw
application the desktop itself can
be setup as a type of dialog box (a
row of pull down menus along the
top, with perhaps some buttons
representing disk drives, etc.) In
this case we would not want the
dialog box brought to the top of
the stack since it would obscure
all of the windows on the screen.
This type of dialog box would
generally set bg_operation to TRUE.
__ _________
TRUE
__ _________

storage *insurance A pointer to a data structure
_________
storage
_________
representing the previous answers
to the dialog box questions.
Always set this to NULL.
NULL

int **macros A list of macros associated with
______
int
______
this dialog box. This array must
be NULL terminated. Each
NULL
individual macro must be
constructed in this manner:

[message to replace, number of
replacement message, nth
replacement message,...., first
replacement message]




- 44 -





DialogPro v 2.0 Users Guide
Reference Manual


Note that the first item represents
the message to be replaced, the
second item represents the number
of replacement items, and the
succeeding items represent the
messages to replace it with (note
that these are in reverse order.

db_colors *colors Determines what attributes to use
______
db_colors
______
when displaying a dialog box.

db_delimiters *delimiters Determines what delimiters to place
__________
db_delimiters
__________
around various question types.


5. free_form

char question_type must be set to FREE_FORM
________ ____
char FREE FORM
________ ____

unsigned char tile_handle The question is displayed in this
____ ______
unsigned char
____ ______
tile. tile_handle must be a valid
____ ______
tile handle.

int (*whenon)
______
int
______
(dialog_box *)
dialog box
int (*whenoff)
_______
int
_______
(dialog_box *)
dialog box
int (*action)(dialog_box *) Pointers to edit checking
______
int dialog box
______
routines. db_run executes each
db run
routine under these conditions. On
selecting the question whenon is
______
executed. On selecting a question
other than the current question or
on exiting db_run whenoff is
_______
db run
_______
executed. On exiting the line
editor action is executed. action
______ ______
must return TRUE or you will not be
TRUE
able to exit the line editor.
whenoff must return TRUE or the
_______
TRUE
_______
attempt to navigate to another
question will fail. If any routine
is set to NULL it is not executed.
NULL
db_run always passes the current
dialog box pointer to each edit
checking function.

char *statement A string representing the statement
_________
char
_________
portion of the question.

int statementx, statementy The left coordinate of the
__________ __________
int
__________ __________
statement.

int key Shortcut key.
___
int
___




- 45 -





DialogPro v 2.0 Users Guide
Reference Manual


char *response The current response to the
________
char
________
question. This must be a
dynamically allocated string. On
confirming a new response this
response will be freed.

char *default_response If response is NULL when the line
editor is invoked, or the response
is displayed, response will be set
equal to a dynamically allocated
copy of this string.

int responsex, responsey The coordinate where the response
_________ _________
int
_________ _________
will be displayed.

int responselen The maximum displayed length of the
___________
int
___________
response. The actual length of the
response can be up to 1000
characters.

char *storage The previous response to the
_______
char
_______
question. Should always be set
to NULL.
NULL

char **target The char * pointer pointed to by
______
char
______
target is updated with the value of
______
response on exiting the db_run.
________
db run
________

int cursor_position The position of the cursor on
______ ________
int
______ ________
confirming the current response to
the question.

int **macros See dialog_box for further
______
int dialog box
______
explanation.

char refresh If TRUE the statement and question
_______
char
_______
delimiters are output. Set this to
true on initialization. Each time
the statement and delimiters are
displayed this value is reset to
FALSE.


6. list

unsigned char tile_handle The question is displayed in this
____ ______
unsigned char
____ ______
tile. tile_handle must be a valid
____ ______
tile handle.

int (*whenon)
______
int
______
(dialog_box *)
dialog box
int (*whenoff)
_______
int
_______
(dialog_box *)
dialog box




- 46 -





DialogPro v 2.0 Users Guide
Reference Manual


int (*action)(dialog_box *) Pointers to edit checking
______
int dialog box
______
routines. db_run executes each
db run
routine under these conditions. On
selecting the question whenon is
______
executed. On selecting a question
other than the current question or
on exiting db_run whenoff is
_______
db run
_______
executed. On exiting the list
action is executed. Until action
______ ______
returns TRUE the user will be
TRUE
unable to exit the list. whenoff
_______
must return TRUE or the attempt to
TRUE
navigate to another question will
fail. If any routine is set to
NULL it is not executed. db_run
NULL
always passes the current dialog
box pointer to each edit checking
function.

char *statement A string representing the statement
_________
char
_________
portion of the question.

int statementx, statementy The left coordinate of the
__________ __________
int
__________ __________
statement.

int key Shortcut key.
___
int
___

unsigned int handle A window handle. The window should
______
unsigned int
______
have the number of rows and columns
and appropriate border type and
style as desired for the scrolling
list box. If this is not a valid
window handle. The window will be
created using the window parameters
below.

if handle (above) is not a valid window handle we use this info
______
to create a window ....

unsigned virtual_rows number of row & columns in the
____________
unsigned
____________
unsigned virtual_columns virtual screen.
_______________
unsigned
_______________

unsigned physical_x location of the upper left hand
__________
unsigned
__________
unsigned physical_y corner of the list within the
__________
unsigned
__________
dialog box window.

unsigned virtual_x upper left coordinate of the list's
_________
unsigned
_________
unsigned virtual_y virtual screen which maps to the
_________
unsigned
_________
upper left hand corner of the lists
frame.

unsigned port_rows number of rows & columns within the
_________
unsigned
_________
unsigned port_columns list's frame
____________
unsigned
____________




- 47 -





DialogPro v 2.0 Users Guide
Reference Manual


unsigned shading style of shading to use for the
_______
unsigned
_______
list's frame. See The WindowPro
manual for further explanation.

char *name1, *name2 a string to place in the top &
_____ _____
char
_____ _____
bottom part or the list's frame.

unsigned char *boxchars The characters to use when creating
________
unsigned char
________
the list's frame. See The
WindowPro manual for further
explanation

unsigned char scroll_bars The scroll bar style to use when
___________
unsigned char
___________
creating the list's frame. See The
WindowPro manual for further
explanation.

Note : If handle is a valid window handle than you do not need to
______
set the above structure members to meaningful values.

char list_type Set this to SELECT_ONE for a radio
____ ____
char SELECT ONE
____ ____
buttons style list. Set this to
CHECKLIST to toggle more than one
CHECKLIST
item on and off.

char **options An array of strings representing
_______
char
_______
the items in the list.

int offset An offset into the above array
______
int
______
representing the currently selected
item.

char *selections An array of chars corresponding the
__________
char
__________
above array. If selections[0] is
__________
TRUE indicates that the first item
TRUE
in the list is toggle on, If
selections[1] is TRUE indicates
__________
TRUE
__________
that the second item in the list is
toggled on. selections[2] == 2
_____________
indicates that the third item
represents a title within the list.

char *available pointer to an array corresponding
_________
char
_________
to the above array, where a value
of FALSE indicates that the state
FALSE
of the corresponding item cannot be
modified.

char *on, *off Strings which represent the on/off
__ ___
char
__ ___
states of each item in the list,
e.g. "ON" and "OFF", or "XX" and
"--", etc.

list_rec *list_ptr Used internally. Set this to NULL.
____ ___
list rec NULL
____ ___



- 48 -





DialogPro v 2.0 Users Guide
Reference Manual



char **target A pointer to an array of chars. On
______
char
______
exiting db_run *target is set equal
______
db run
______
to selections.
__________

int **macros See explanation at dialog_box.
______
int dialog box
______


7. list_rec

list_rec is the basic data type used by almost all of the high
________
level list-oriented functions. The list_rec data structure
________
consists of the following members.

int handle Every list must be related to an
______
int
______
existing window. handle must be a
______
valid window handle.

int tile_handle Every list must be related to an
___________
int
___________
existing tile. tile_handle must be
___________
a valid tile handle.

char list_type Set to CHECKLIST to allow more than
_________________________
char CHECKLIST
_________________________
one item to be toggled on/off. Set
to SELECT_ONE so that as one item
SELECT ONE
is toggled on all other items are
toggled off.

char move_ok lst_run will not process any moving
____ __
char lst run
____ __
messages if move_ok is FALSE.
____ __
FALSE
____ __

char size_ok lst_run will not process any sizing
____ __
char lst run
____ __
messages if size_ok is FALSE.
____ __
FALSE
____ __

char auto_vert If TRUE, on calling lst_run the
____ ____
char TRUE lst run
____ ____
window is automatically resized so
that it has the same number of rows
as there are items in the list.

char auto_horiz If TRUE, on calling lst_run the
____ _____
char TRUE lst run
____ _____
window is automatically resized so
that it is as wide as the widest
option.

char alpha_confirm If TRUE, list_type is SELECT_ONE,
_____ _______ ____ ____
char TRUE SELECT ONE
_____ _______ ____ ____
and executing lst_run, pressing
lst run
any alpha selects the next item
bound to the key, toggles it on,
and exits lst_run with a value of
lst run
CONFIRMED.
CONFIRMED







- 49 -





DialogPro v 2.0 Users Guide
Reference Manual


If TRUE, list_type is CHECKLIST,
TRUE CHECKLIST
and executing lst_run, pressing any
lst run
alpha key selects the next item in
the list bound to that key and
toggles the item on.

int *cmds An array of extended keyboard codes
____
int
____
corresponding to the standard
messages, where standard message 1
(PRESS_BUTTON) corresponds to
keyboard code in position 0,
message 2 (CONFIRM) corresponds to
the keyboard code in position 1,
etc. This array is used to
interpret keyboard codes into
messages. cmds is generally set to
____
the default keyboard commands
default_db_cmds.
default_db_cmds

char bg_operation If FALSE, when db_run is executed
__ _________
char FALSE db run
__ _________
the dialog box window is brought to
the top of the stack via a call to
wn_openw. If FALSE and the window
wn openw FALSE
is on the screen it remains in its
position in the stack. If FALSE
FALSE
and the window is not on the screen
it is displayed via a call to
wn_openw. In a desktop type
application the desktop itself can
be setup as a type of dialog box (a
row of pull down menus along the
top, with perhaps some buttons
representing disk drives, etc.) In
this case we would not want the
dialog box brought to the top of
the stack since it would obscure
all of the windows on the screen.
This type of dialog box would
generally set bg_operation to TRUE.
__ _________
TRUE
__ _________

lst_storage *insurance A pointer to a data structure
_________
lst_storage
_________
representing the previous answers
to the list. Always set this to
NULL.
NULL

int **macros A list of macros associated with
______
int
______
this dialog box. The list must be
NULL terminated (i.e. the last item
NULL
in the array must be NULL.) Each
NULL
individual macro must be
constructed in this manner:

[message to replace, nth
message,...., first message, NULL]
NULL



- 50 -






DialogPro v 2.0 Users Guide
Reference Manual



Note that the first item represents
the message to be replaced, the
succeeding items represent the
messages to replace it with (note
that these are in reverse order,)
and the last item must be a NULL.
NULL

char *on, *off Strings which represent the on/off
__ ___
char
__ ___
states of each item in the list,
e.g. "ON" and "OFF", or "XX" and
"--", etc.

char **options An array of strings representing
_______
char
_______
the items in the list. The last
element in the array must be NULL.
NULL

char *selections An array of chars corresponding the
__________
char
__________
above array. If selections[0] is
__________
TRUE indicates that the first item
TRUE
in the list is toggle on, If
selections[1] is TRUE indicates
__________
TRUE
__________
that the second item in the list is
toggled on, etc.

char *available pointer to an array corresponding
_________
char
_________
to the above array, where a value
of FALSE indicates that the state
FALSE
of the corresponding item cannot be
modified.

unsigned *keybind An array of ints corresponding to
_______
unsigned
_______
the above array where each element
in the array represents an extended
keyboard code or an ascii code.
These values bind the options to
keystrokes (see alpha_confirm,
_____ _______
above, for further explanation.)
If an ascii code is used selection
in case insensitive. If an
extended keyboard code is used it
must match exactly.

int selected An offset into the above array
________
int
________
representing the item in the list
which is currently selected.

int These values are used internally
int
and should not be modified. You
may however read these variables
although they are not always
guaranteed to be up to date.





- 51 -





DialogPro v 2.0 Users Guide
Reference Manual


optlen, The length of the longest option in
______
the list.

taglen, The length of the longest on/off
______
indicator.

numopts The number of items in the list.
_______

db_colors *colors A pointer to a color scheme
______
db_colors
______
structure. Determines which
attributes to use when displaying
different parts of the list.

unsigned maxcols determines the number of columns in
_______
unsigned
_______
the list. If this number is larger
than the number of items in the
list, creates a vertical list, like
a lotus menu.

unsigned If handle (above) is not a valid
______
unsigned
______
window handle these items are used
to create a window for the list.

physical_x, physical_y
___________________________
virtual_x, virtual_y,
__________________________
virtual_rows,
__________________
virtual_columns
____________________
port_rows, port_columns
____________________________
shading
____________

char *name1, *name2
_____ _____
char
_____ _____
char unsigned *boxchars;
________
char unsigned
________


8. multi_choice

char question_type must be set to MULTI_CHOICE.
________ ____
char MULTI CHOICE
________ ____

unsigned char tile_handle The question is displayed in this
____ ______
unsigned char
____ ______

tile. tile_handle must be a valid
____ ______
tile handle.

int (*whenon)
int
(dialog_box *)
dialog box
int (*whenoff)
int
(dialog_box *)
dialog box
int (*action)(dialog_box *) Pointers to edit checking
______
int dialog box
______
routines. db_run executes each
db run
routine under these conditions. On
selecting the question whenon is
executed. On selecting a question
other than the current question or
on exiting the db_run whenoff is
_______
db run
_______
executed. On confirming the



- 52 -





DialogPro v 2.0 Users Guide
Reference Manual


response to the current
question action is executed.
______
whenoff must return TRUE or the
TRUE
attempt to navigate to another
question will fail. If any routine
is set to NULL it is not executed.
NULL
db_run always passes the current
dialog box pointer to each edit
checking function.

char *statement A string representing the statement
_________
char
_________
portion of the question.

int statementx, statementy Displays the statement portion of
__________ __________
int
__________ __________
the question at these coordinates.

char *response_mask If not set to NULL, db_run
________ ____
char NULL db run
________ ____
suppresses the display of statement
and puts this string in place of
the response. Makes multiple
choice question behave like a pull
down menu.

char **response_list An array of strings representing
________ ____
char
________ ____
the available choices in the
multiple choice question. The last
element in the array must be set to
NULL.
NULL

char *available An array of chars corresponding to
_________
char
_________
the above array. If available[0] is
_________
FALSE the first item cannot be
FALSE
chosen as the response, If
available[1] is TRUE the second
_________
TRUE
_________
item in response_list can be chosen
________ ____
as the response. A 2 indicates that
the list element is a title.

int response_offset The current response to the
________ ______
int
________ ______
question as an offset into
response_list.
________ ____

int responsex, responsey The coordinates where the response
_________ _________
int
_________ _________
portion of the question is
displayed.

int responselen The displayed length of the
___________
int
___________
response. The actual response can
be longer.








- 53 -





DialogPro v 2.0 Users Guide
Reference Manual


int key The extended keyboard code for the
___
int
___
shortcut key (when executing
db_run, if the user presses the
db run
shortcut key he navigates directly
to associated question.)

unsigned int aux_handle A window handle. Required for the
___ ______
unsigned int
___ ______
pull down list. Note if this is
not a valid window handle it will
be automatically created.

unsigned char aux_tile A valid tile handle. Required for
___ ____
unsigned char
___ ____
the pull down list.

if aux_handle (above) is not a valid window handle this info to
__________
create a window ...

unsigned char *boxchars
________
unsigned char
________
char *major_head, *minor_head
__________ __________
char
__________ __________
char shading
_______
char
_______


list_rec *list_ptr Used internally. Set this to NULL.
____ ___
list rec NULL
____ ___

int *target A pointer to an int to set equal to
______
int
______
response_offset on exiting db_run.
_______________
db run
_______________

int **macros See dialog_box for an explanation.
______
int dialog box
______

char refresh When this value is true and the
_______
char
_______
question is displayed the statement
and delimiters are output to the
dialog box's virtual screen.
Otherwise, just the response is
sent. Typically you initialize
this to TRUE. Every time the
TRUE
question is displayed this is reset
to FALSE.
FALSE

unsigned maxcols Indicates how many columns to use
_______
unsigned
_______
when displaying the pull down list.


9. rcbutton

This structure is used to represent either a radio button or a
check box.

char question_type must be set to RCBUTTON.
________ ____
char RCBUTTON
________ ____

unsigned char tile_handle The question is displayed in this
____ ______
unsigned char
____ ______
tile. tile_handle must be a valid
____ ______
tile handle.




- 54 -





DialogPro v 2.0 Users Guide
Reference Manual


int (*whenon)
______
int
______
(dialog_box *)
dialog box
int (*whenoff)
_______
int
_______
(dialog_box *)
dialog box
int (*action)(dialog_box *) Pointers to edit checking
______
int dialog box
______
routines. db_run executes each
db run
routine under these conditions. On
selecting the question whenon is
______
executed. On selecting a question
other than the current question or
on exiting db_run whenoff is
_______
db run
_______
executed. On pressing the
rcbutton action is executed.
______
whenoff must return TRUE or the
TRUE
attempt to navigate to another
question will fail. If any routine
is set to NULL it is not executed.
NULL
db_run always passes the current
dialog box pointer to each edit
checking function.

char *statement A string representing the statement
_________
char
_________
to appear to the right of the
rcbutton's checkoff area.

int statementx, statementy left coordinate of the rcbutton.
__________ __________
int
__________ __________

int key Shortcut key.
___
int
___

unsigned char btype Set to CHECK if a checkbox, or
_____
unsigned char
_____
RADIO(N) where N is a number
between 0 and 254. Only one
rcbutton in the radio group number
N can be "on" at any moment.

char checked Set to TRUE if the rcbutton is
_________________________
char
_________________________
checked.

char *target The variable pointed to by target
________________________ ______
char
________________________ ______
will be updated with the value of
checked on exiting the dialog box.
_______


10. reducer

char question_type must be set to REDUCER.
________ ____
char REDUCER
________ ____

unsigned char tile_handle The question is displayed in this
____ ______
unsigned char
____ ______
tile. tile_handle must be a valid
____ ______
tile handle.

int (*whenon)
int
(dialog_box *)
dialog box
int (*whenoff)
int



- 55 -





DialogPro v 2.0 Users Guide
Reference Manual


(dialog_box *)
dialog box
int (*action)(dialog_box *) Pointers to edit checking
______
int dialog box
______
routines. db_run executes each
db run
routine under these conditions. On
selecting the question whenon is
executed. On selecting a question
other than the current question or
on exiting the db_run whenoff is
_______
db run
_______
executed. On confirming the
response to the current
question action is executed.
______
whenoff must return TRUE or the
TRUE
attempt to navigate to another
question will fail. If any routine
is set to NULL it is not executed.
NULL
db_run always passes the current
dialog box pointer to each edit
checking function.

char *statement A string representing the statement
_________
char
_________
portion of the question.

int statementx, statementy Displays the statement portion of
__________ __________
int
__________ __________
the question at these coordinates.

char **response_list An array of strings representing
________ ____
char
________ ____
the available choices in the
multiple choice question. The last
element in the array must be set to
NULL.
NULL

char *available An array of chars corresponding to
_________
char
_________
the above array. If available[0] is
_________
FALSE the first item cannot be
FALSE
chosen as the response, If
available[1] is TRUE the second
_________
TRUE
_________
item in response_list can be chosen
________ ____
as the response, etc.

char *response The current response to the
_________
char
_________
question. Must be a dynamically
allocated string as when a new
response is confirmed the previous
response is freed.

int responsex, responsey The coordinates where the response
_________ _________
int
_________ _________
portion of the question is
displayed.

int responselen The displayed length of the
___________
int
___________
response. The actual response can
be longer.





- 56 -





DialogPro v 2.0 Users Guide
Reference Manual


int key The extended keyboard code for the
___
int
___
shortcut key (when executing
db_run, if the user presses the
db run
shortcut key he navigates directly
to associated question.)

int cursor_position The position of the cursor when the
______ ________
int
______ ________
current response was confirmed.

char **target A pointer to a variable to set
_______
char
_______
equal to response on exiting
________
db_run.
db run

int **list_macros Macros used while in the pull down
___________
int
___________
list portion of a reducer
question. See dialog_box for an
dialog box
explanation.

int **edlin_macros Macros used while in the lide
____________
int
____________
editor portion of a reducer
question. See dialog_box for an
dialog box
explanation.

unsigned int aux_handle A window handle. Required for the
___ ______
unsigned int
___ ______
pull down list. Note if this is
not a valid window handle it will
be automatically created.

unsigned char aux_tile A valid tile handle. Required for
___ ____
unsigned char
___ ____
the pull down list.

if aux_handle (above) is not a valid window handle this info to
__________
create a window ...

unsigned char *boxchars
________
unsigned char
________
char *major_head, *minor_head
__________ __________
char
__________ __________
char shading
_______
char
_______


list_rec *list_ptr Used internally. Set this to NULL.
____ ___
list rec NULL
____ ___

char refresh When this value is true and the
_______
char
_______
question is displayed the statement
and delimiters are output to the
dialog box's virtual screen.
Otherwise, just the response is
sent. Typically you initialize
this to TRUE. Every time the
TRUE
question is displayed this is reset
to FALSE.
FALSE

unsigned maxcols Indicates how many columns to use
_______
unsigned
_______
when displaying the pull down list.




- 57 -





DialogPro v 2.0 Users Guide
Reference Manual


11. scroll_txt

This data structure is used to define the scrolling text type
questions. This question type is different from the other
question types because you must supply the address to the
'controlling' function. Two sample controlling functions are
provided.

char question_type Must be set to SCROLL_TXT.
_____________
char SCROLL_TXT
_____________

unsigned char tile_handle The question is displayed in this
____ ______
unsigned char
____ ______
tile. tile_handle must be a valid
____ ______
tile handle.

int (*whenon)
int
(dialog_box *)
dialog box
int (*whenoff)
int
(dialog_box *)
dialog box
int (*action)(dialog_box *) Pointers to edit checking
______
int dialog box
______
routines. db_run executes each
db run
routine under these conditions. On
selecting the question whenon is
executed. On selecting a question
other than the current question or
on exiting the db_run whenoff is
_______
db run
_______
executed. On confirming the
response to the current
question action is executed.
______
whenoff must return TRUE or the
TRUE
attempt to navigate to another
question will fail. If any routine
is set to NULL it is not executed.
NULL
db_run always passes the current
dialog box pointer to each edit
checking function.

int (far *control)
_______
int far
_______
(dialog_box *, int) On executing the question control
dialog_box int
is passed to this routine. In the
event of a MOUSE_EVENT occuring
MOUSE_EVENT
within the question's region the
second parameter will be set to
MOUSE_EVENT. Otherwise the
MOUSE_EVENT
parameter will be 0.

void *misc_ptr Because the use of SCROLL_TXT is
________
void SCROLL_TXT
________
open-ended it may be necessary to
associate additional data with the
question. You can point to a
structure containing this
additional data using this pointer.






- 58 -





DialogPro v 2.0 Users Guide
Reference Manual


int boxx, boxy The upper left corner of the
____ ____
int
____ ____
question will begin at this
coordinate within the dialog box
window.

unsigned int aux_handle The question requires a window for
__________
unsigned int
__________
some interim processing. Create a
window and assign the handle to
this data structure member. The
question region will be same size
as this window.

int **macros See dialog_box for further
______
int dialog box
______
explanation.



12. title

Use this to display titles in dialog boxes.

char question_type Must be set to TITLE.
_________________________
char TITLE
_________________________

unsigned char tile_handle Indicates which tile to display the
________________
unsigned char
________________
title in.

char *statement Indicates the title string.
_________
char
_________

int statementx, statementy Where to locate the title.
__________________________
int
__________________________

char center_justify If TRUE ignores statementx and
_________________________ __________
char TRUE
_________________________ __________
center justifies the title within
the virtual screen.
























- 59 -





DialogPro v 2.0 Users Guide
Reference Manual


E. Global variables

1. db_head, db_tail, db_queue

int *db_queue An array of ints representing the
__ _____
int
__ _____
circular message queue

unsigned char *db_head A pointer to a char containing the
__ ____
unsigned char
__ ____
offset into db_queue where the last
__ _____
message in the queue is located.

unsigned char *db_tail A pointer to a char containing the
__ ____
unsigned char
__ ____
offset into db_queue where the next
__ _____
message to be used is located.


2. default_db_cmds

A default keyboard-command table.


3. idle

void (* idle)(void *)
____
void void
____

the idle function is repeatedly called in the keyboard/mouse
polling loop. The function pointed to by idle is passed a
____
pointer to the active dialog_box or list_rec on each call. Use
dialog_box list_rec
this to place time limits on a response, update a time and date
field, or do other real time updating. Note that the timing of
the polling loop can vary based on whether keyboard typematic is
active, the mouse buttons are up or down, or whether or not a
mouse is installed.


4. monitor_switch, _fg, _bg, _speed, _wdw, _tile

These values determine how the debug monitor operates. The debug
monitor will display the queue events in a window. You can watch
these queue events to determine if a dialog box is behaving
properly.

extern unsigned int
extern unsigned int
monitor_wdw The handle of the window where the
___________
debug info will be displayed. The
extern unsigned char
extern unsigned char
monitor_tile The tile handle where the debug
______________
info will be displayed. This
tile's virtual screen needs to be
about 70 characters wide.

extern int monitor_speed 0 = no delay, > 0 = more delay, -1
_____________
extern int
_____________
= step through by keystroke.




- 60 -





DialogPro v 2.0 Users Guide
Reference Manual


extern int monitor_switch 0 if monitor is OFF, 1 if it is ON.
______________
extern int
______________

extern unsigned char
extern unsigned char
monitor_fg, monitor_bg The background and foreground color
__________ __________
that the monitor info will display
in.



5. mouse_sensitivity

The timeout value to be used when calling kb_mouseclicks. 15
kb mouseclicks
seems to work just about right. But you may want to fine tune it
for other systems or give the user access to this value--like the
MAC or Microsoft Windows.










































- 61 -





DialogPro v 2.0 Users Guide
Reference Manual


F. Messages

1. Dialog Box

Each message is translated as follows at the dialog box level by
_______________________
db_run (several of the messages transfer porcessing to question
level--to see how messages are interpreted at the question level
review the following section):

DO_NOTHING Does nothing.
DO_NOTHING

PRESS_BUTTON If the current question (indicated by
PRESS_BUTTON
db_ptr->id_select) is a button the value
______
->id_select
______
BUTTONQUEST(db_ptr->id_select)->cmd_key is
______
BUTTONQUEST( ->id_select)->cmd_key
______
placed at the tail of the queue and the
global variable button_press is set to
BUTTONQUEST(db_ptr->id_select)->exitval.
______
BUTTONQUEST( ->id_select)->exitval
______

If the current question is a multiple choice
question the current response + 1 (with wrap
around from the last response to the first)
becomes the new response.

On the other questions, nothing happens.

CONFIRM If the current question is a multiple choice
CONFIRM
and CURRMC->response__mask does not equal
CURRMC->response__mask
NULL the message DESCEND is placed at the
NULL DESCEND
tail of the queue.

Otherwise, if at the dialog box level, it
executes db_freestorage. Exits db_run with
db_freestorage db_run
the value CONFIRMED and places CONFIRM at the
CONFIRMED CONFIRM
tail of the queue if button_press is equal to
button_press
0, otherwise it exits with the value of
button_press.
button_press

ABORT Executes db_restoreanswers and exits db_run.
ABORT db_restoreanswers db_run
Exits with the value ABORTED and places ABORT
ABORTED ABORT
at the tail of the queue if button_press is
button_press
equal to 0, otherwise it exits with the value
button_press.
button_press

UP, DOWN, LEFT, RIGHT, HOME, END, BIG_RIGHT, BIG_LEFT, BACKSPACE
UP, DOWN, LEFT, RIGHT, HOME, END, BIG_RIGHT, BIG_LEFT, BACKSPACE

Passes the event onto the current question by
putting the respective event at the tail of
the queue and then placing a DESCEND at the
tail of the queue.

In the case of a BUTTON the event is
ignored. In the case of radio button selects
the next or previous radio button in the
radio button group.



- 62 -





DialogPro v 2.0 Users Guide
Reference Manual



BIG_UP Does nothing.
BIG_UP
BIG_DOWN "
BIG_DOWN

BIG_HOME Selects the first question in the dialog box.
BIG_HOME
BIG_END Selects the last question in the dialog box.
BIG_END

ASCEND Executes db_freestorage. Exits db_run with
ASCEND db_freestorage db_run
the value ASCENDED if button_press is equal
ASCENDED button_press
to 0, otherwise it exits with the value of
button_press.
button_press

DESCEND If the current question is a multiple choice,
DESCEND
"pulls down" the list of selection in a
vertical list, with the current response
highlighted.

If the current question is a free form or
reducer, enters the line editor.

If the current question is a list, the cursor
moves inside of the scrolling list and the
item which was highlighted when the user last
executed the list is highlighted.

If the current question is a button, does
nothing.

EXPAND If the current question is a multiple choice
EXPAND
question it "pulls down" the available
responses to the question in a vertical list.

If the current question is a reducer is
"pulls down" ALL of the available responses
to the question in a vertical list.

DELETE does nothing.
DELETE

MOUSE_CONFIRM Executes db_freestorage. Exits db_run with
MOUSE_CONFIRM db_freestorage db_run
the value MOUSED and places MOUSE_EVENT at
MOUSED MOUSE_EVENT
the tail of the queue.

MOUSE_EVENT Interprets the last mouse event (prev_x,
MOUSE_EVENT prev_x
prev_y, and prev_click) into keystroke. The
prev_y prev_click
keystroke is then placed at the tail of the
queue.

MOUSE_DESCEND If the current question is a reducer or a
MOUSE_DESCEND
multiple choice question db_run calls the
db_run
line editor and places the cursor at the
location clicked on in the text.






- 63 -





DialogPro v 2.0 Users Guide
Reference Manual


If the current question is a list,
MOUSE_EVENT is placed at the tail of the
MOUSE_EVENT
queue and the list is executed.

STORE Executes db_storeanswers.
STORE db_storeanswers.

RESTORE Executes db_restoreanswers.
RESTORE db_restoreanswers

FREE_STORAGE Executes db_freestorage.
FREE_STORAGE db_freestorage

POSITION Selects the question based on the value of
POSITION
the next integer in the event queue.

POSITION_TOGGLE Does nothing.
POSITION_TOGGLE

POSITION_CONFIRM Does nothing.
POSITION_CONFIRM

If db_ptr->size_ok is TRUE then:
______
->size_ok
______

SIZE_LT Pulls right border of window (db_ptr->handle)
______
SIZE_LT ->handle
______
in one character.

SIZE_RT Pulls right border of window (db_ptr->handle)
______
SIZE_RT ->handle
______
out one character.

SIZE_UP Pulls bottom border of tile (db_ptr->handle,
______
SIZE_UP ->handle
______
QUESTION->tile_handle) up one character.
QUESTION->tile_handle

SIZE_DN Pulls bottom border of tile down one
SIZE_DN
character.

BIG_SIZE_LT Same as above but by 8 characters.
BIG_SIZE_LT

BIG_SIZE_RT "
BIG_SIZE_RT

BIG_SIZE_UP "
BIG_SIZE_UP

BIG_SIZE_DN "
BIG_SIZE_DN

SCROLL_LT Scrolls virtual screen (db_ptr->handle,
______
SCROLL_LT ->handle
______
QUESTION->tile_handle) left one column.
QUESTION->tile_handle

SCROLL_RT " right ".
SCROLL_RT

SCROLL_UP " up one row.
SCROLL_UP

SCROLL_DN " down ".
SCROLL_DN

BIG_SCROLL_LT Same as above but by 8.
BIG_SCROLL_LT

BIG_SCROLL_RT "
BIG_SCROLL_RT

BIG_SCROLL_UP "
BIG_SCROLL_UP




- 64 -





DialogPro v 2.0 Users Guide
Reference Manual


BIG_SCROLL_DN "
BIG_SCROLL_DN

MOVE_LT Moves the window (db_ptr->handle) left one
______
MOVE_LT ->handle
______
character.

MOVE_RT " right.
MOVE_RT

MOVE_UP " up.
MOVE_UP

MOVE_DN " down.
MOVE_DN

BIG_MOVE_LT Same as above but by 8.
BIG_MOVE_LT

BIG_MOVE_RT "
BIG_MOVE_RT

BIG_MOVE_UP "
BIG_MOVE_UP

BIG_MOVE_DN "
BIG_MOVE_DN

EXECUTE Executes a function by generating a function
EXECUTE
pointer based on the next two instructions in
the event queue. The function is passed
db_ptr as a parameter. The function is
db_ptr
continually execute until it returns an
integer value of TRUE.
TRUE

alphanumeric If on a free_form or reducer, erases the
current response, makes the character pressed
the first character in the new response and
enters the line editor.

If on a multiple choice, selects the next
item beginning with that character.

NEXT, PREVIOUS Selects the next/previous question.
NEXT PREVIOUS


2. Line Editor

The line editor is invoked when editing a free_form or a reducer.
Each message is translated as follows at the line editor level
________________________
(several of the messages transfer porcessing to the dialog box
level--to see how messages are interpreted at the dialog box
level review the previous section):

CONFIRM Exits the line editor and makes
CONFIRM
CURRFF->response (or CURRR->response, for a
______ _____
->response ->response
______ _____
reducer) equal to the current edited
response. Also, places a CONFIRM at the tail
CONFIRM
of the queue. If the question is a reducer
and the current response matches more than
one of the specified items, the possible
matches are displayed in a "pulldown" list.




- 65 -





DialogPro v 2.0 Users Guide
Reference Manual


Executes CURRFF->action(db_ptr) (or
______
->action(db_ptr)
______
CURRR->action(db_ptr).)
_____
->action(db_ptr)
_____

ABORT Exits the line editor. The current edited
ABORT
response is replaced by the previous response
(CURRFF->response or CURRR->response.) Also
______ _____
->response ->response
______ _____
places an ABORT at the tail of the queue.
ABORT

Executes CURRFF->action(db_ptr) (or
______
->action(db_ptr)
______
CURRR->action(db_ptr).)
_____
->action(db_ptr)
_____

LEFT Selects the character to the left.
LEFT

RIGHT " right.
RIGHT

HOME Selects the first character.
HOME

END Selects the last character.
END

BIG_LEFT Selects the first character in the word to
BIG_LEFT
the left.

BIG_RIGHT Selects the first character in the word to
BIG_RIGHT
the right.

ASCEND Same as CONFIRM.
ASCEND CONFIRM

DESCEND "
DESCEND

BACKSPACE Deletes the character to the left of the
BACKSPACE
cursor.

DELETE Deletes the character under the cursor.
DELETE

MOUSE_CONFIRM Same as CONFIRM, but also puts a MOUSE_EVENT
MOUSE_CONFIRM CONFIRM MOUSE_EVENT
at the tail of the queue.

MOUSE_EVENT Converts the last mouse event into a message
MOUSE_EVENT
of either POSITION or MOUSE_CONFIRM.
POSITION MOUSE_CONFIRM

STORE if CURRFF->insurance is NULL makes it equal
______
STORE ->insurance NULL
______
to CURRFF->response.
______
->response
______

RESTORE If CURRFF->insurance does not equal NULL
______
RESTORE ->insurance NULL
______
makes CURRFF->response equal to
______
->response
______
CURRFF->insurance and sets CURRFF->insurance
______ ______
->insurance ->insurance
______ ______
to NULL.
NULL

FREE_STORAGE Set CURRFF->insurance to NULL.
______
FREE_STORAGE ->insurance NULL
______

POSITION Selects the character based on the value of
POSITION
the next integer in the event queue.





- 66 -





DialogPro v 2.0 Users Guide
Reference Manual


3. list question

Each message is translated as follows at the list level (several
_________________
of the messages transfer porcessing to the dialog box level--to
see how messages are interpreted at the dialog box level review

the previous section):

CONFIRM Executes CURRLIST->action(db_ptr), places a
_________
CONFIRM >action(db_ptr)
_________
CONFIRM at the tail of the queue, and exits
CONFIRM
back to db_run.

PRESS_BUTTON check the current item on/off.
PRESS_BUTTON

ABORT Executes lst_freestorage, executes
ABORT
CURRLIST->action(db_ptr), places an ABORT at
_________
>action(db_ptr)
_________
the tail of the queue, and exits back to
db_run.

UP Highlights item above current item.
UP

DOWN Highlights item below current item.
DOWN

LEFT If in a multicolumn list selects the item to
LEFT
the left of the current item.

RIGHT If in a multicolumn list selects the item to
RIGHT
the right of the current item.

HOME Highlights the first item.
HOME

END Highlights the last item.
END

BIG_UP Highlights the item a window's length above.
BIG_UP

BIG_DOWN Highlights the item a window's length below.
BIG_DOWN

ASCEND Exits the list, confirms the current
ASCEND
responses, and executes
CURRLIST->action(CURRLIST->list_ptr).
_________ _________
>action( >list_ptr)
_________ _________

DESCEND "
DESCEND

MOUSE_CONFIRM Same as ASCEND, but also puts a MOUSE_EVENT
MOUSE_CONFIRM ASCEND MOUSE_EVENT
at the tail of the queue.

MOUSE_EVENT Converts the last mouse event into a message
MOUSE_EVENT
of either POSITION, POSITION_TOGGLE or
POSITION POSITION_TOGGLE
MOUSE_CONFIRM.
MOUSE_CONFIRM

STORE Stores the current selected item in another
STORE
data structure.

RESTORE Restores the list to its state when STORE was
RESTORE STORE

called.



- 67 -





DialogPro v 2.0 Users Guide
Reference Manual



FREE_STORAGE Free data structures created on STORE.
FREE_STORAGE STORE

POSITION Highlights an item based on the value of the
POSITION
next instruction in the event queue.

POSITION_TOGGLE Highlights item clicked on (based on the
POSITION_TOGGLE
value of the next instruction in the event
queue,) and toggles the item on/off.

POSITION_CONFIRM "
POSITION_CONFIRM




4. Pull down list

Pull down lists can originate from a multiple choice or a reducer
question. Regardless of how they came about they operate the
same. Each message is translated as follows at the pull down
________________
list level (several of the messages transfer porcessing to the
__________
dialog box level--to see how messages are interpreted at the
dialog box level review the previous section):

CONFIRM Selects the current item as the answer, exits
CONFIRM
the pull down list and places a RIGHT at the
RIGHT
tail of the queue.

Executes CURRMC->action(db_ptr) (or
______
->action(db_ptr)
______
CURRR->action(db_ptr).)
_____
->action(db_ptr)
_____

ABORT Does not change the selected item, and exits
ABORT
the pull down list.

Executes CURRMC->action(db_ptr) (or
______
->action(db_ptr)
______
CURRR->action(db_ptr).)
_____
->action(db_ptr)
_____

UP Highlights item above current item.
UP

DOWN Highlights item below current item.
DOWN

LEFT If a multicolumn list selects the item to the
LEFT
left of the current item.

RIGHT If a multicolumn list selects the item to the
RIGHT
right of the current item.

HOME Highlights the first item.
HOME

END Highlights the last item.
END

BIG_UP Highlights the item a window's length above.
BIG_UP

BIG_DOWN Highlights the item a window's length below.
BIG_DOWN



- 68 -





DialogPro v 2.0 Users Guide
Reference Manual



ASCEND Selects the current item as the answer, and
ASCEND
exits the pull down list.

Executes CURRMC->action(db_ptr) (or
______
->action(db_ptr)
______
CURRR->action(db_ptr).)
_____
->action(db_ptr)
_____

DESCEND "
DESCEND

MOUSE_CONFIRM Same as ASCEND, but also puts a MOUSE_EVENT
MOUSE_CONFIRM ASCEND MOUSE_EVENT
at the tail of the queue.

MOUSE_EVENT Converts the last mouse event into a message
MOUSE_EVENT
of either POSITION, POSITION_TOGGLE or
POSITION POSITION_TOGGLE
MOUSE_CONFIRM.
MOUSE_CONFIRM

STORE Stores the current selected item in another
STORE
data structure.

RESTORE Restores the list to its state when STORE was
RESTORE STORE
called.

FREE_STORAGE Free data structures created on STORE.
FREE_STORAGE STORE

POSITION Highlights an item based on the position of
POSITION
the last mouse event.

POSITION_TOGGLE Highlights item clicked on, selects the item,
POSITION_TOGGLE
and exits.

POSITION_CONFIRM "
POSITION_CONFIRM


























- 69 -









----------------- The DialogPro registration form ---------------

Mailing Address

Name :___________________________________________________
Company Name :___________________________________________________
Position :___________________________________________________
Street :___________________________________________________
___________________________________________________
City :_________________ State :__ Zip Code :__________
Country :___________________________________________________
Compuserve # :___________________________________________________


Computer System

Manufacturer :___________________________________________________
Model :___________________________________________________
RAM :___________________________________________________

Disk Media 5 1/4" 360K __ 5 1/4" 1.2mb __
3 1/2" 720K __ 3 1/2" 1.4mb __
Hard Disk
Capacity :___________________________________________________
Video Adapter:___________________________________________________
Monitor :___________________________________________________


How did you hear about DialogPro? ______________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________

Desired Support Level (check one)

__ $15, The DialogPro shareware diskette
__ $50, registered DialogPro shareware library user
__ $100, registered DialogPro source code user (non-commercial)
__ $200, registered DialogPro source code user (commercial)

Include a check for the amount corresponding to the desired level
of service. Make the check payable to, Seabreeze Software.





















 December 11, 2017  Add comments

Leave a Reply