The <dialogs.h> header file
This header file contains the following functions:
Dialog DialogAdd DialogAddButtons DialogAddPulldown
DialogAddRequest DialogAddText DialogDo DialogNew
DialogNewSimple DlgMessage NoCallBack
and the following constants and predefined types:
Bool Buttons CENTER H_NULL
HANDLE NULL
Functions
Displays a message dialog box.
DlgMessage displays a message dialog box, where title is the title string
(pass NULL for no title), and
message is the content of the message. Both title and message
must fit into one screen line, else very unpredictable behaviour is possible (for example, a
message may appear into the status line instead of dialog box; however, on AMS 2.xx, a long
message will simply be wrapped in the dialog box). Parameters left_button
and right_button determine the type of the left and right buttons which will appear
at the bottom of the dialog box. The set of possible buttons is very limited, and possible
types are defined in enum Buttons (any other values will cause a crash).
The meanings of these constants are:
BT_NONE | No button at all |
BT_OK | Button "Enter=OK" |
BT_SAVE | Button "Enter=SAVE" |
BT_YES | Button "Enter=YES" |
BT_CANCEL | Button "Esc=CANCEL" |
BT_NO | Button "ESC=NO" |
BT_GOTO | Button "Enter=GOTO" |
DlgMessage returns KEY_ENTER or KEY_ESC,
depending of whether the user exits the dialog by pressing ENTER or ESC key. This routine may
cause the heap compression.
HANDLE DialogNewSimple (short width, short height);
Creates a new dialog box.
DialogNewSimple allocates a memory for a dialog box with dimensions width x height,
initializes allocated block with necessary structures and returns a handle to it (or H_NULL in a case of
error). This routine may cause the heap compression.
DialogNewSimple in fact calls DialogNew with
NoCallBack as third parameter.
NOTE: You can later free the memory by calling HeapFree.
HANDLE DialogAddText (HANDLE Handle, short x, short y, const char *text);
Adds a text into a dialog box.
DialogAddText adds the text text to the dialog structure associated with handle
Handle at the position (x, y), where coordinates are
relative to the top-left corner of the dialog box. Returns H_NULL
in a case of error, else returns Handle. The text must fit into one line of
the dialog box. This routine (as well as all other 'DialogAdd...' routines) may cause
the heap compression.
HANDLE DialogAddTitle (HANDLE Handle, const char *title, short left_button, short right_button);
Adds a title bar and up to two buttons into a dialog box.
DialogAddButtons adds a title bar with text title and up to two buttons to the dialog structure associated
with handle Handle. Parameters left_button and right_button determine the type of the
left and right buttons which eventually will appear at the bottom of the dialog box
(by giving BT_NONE as the parameter you can skip adding a button). The set of possible buttons
is very limited. See DlgMessage for info about possible types. It seems that it is not
possible to add buttons without adding a title bar.
DialogAddTitle returns H_NULL in a case of error, else returns Handle.
HANDLE DialogAddRequest (HANDLE Handle, short x, short y, const char *prompt, unsigned short offset,
short MaxLen, short width);
Adds a request box into a dialog box.
DialogAddRequest adds the request box (i.e. an input line box) to the dialog structure
associated with handle Handle at the position (x, y),
where coordinates are relative to the top-left corner of the dialog box.
A prompt prompt will appear in front of the request box. All request boxes in
one dialog box will be aligned in according to a request box which has the longest
prompt, except when the prompt string finishes with '`' character (code 96). In such case,
the request box will start immidiately after the prompt string ('`' is a special
character, which will not be displayed). If the prompt is not finished with '`', it will
be eventually padded with '.' characters up to the length of the longest prompt, except when
the prompt finishes with ':'. In such case, the prompt will be padded with space character
(':' will also be displayed).
Maximal number of characters which may be entered is determined by parameter MaxLen,
and width determines the actual width of the request box. It will be such that
the widest string made of width characters may fit into the box. So, the real
width of box in pixels will be width * 6, because the widest character
'M' is 6 pixels wide. If you try to enter a string with more than width characters,
the content of the request box will scroll. If width is wider than the actual
avaliable width of the dialog box, the request box will be truncated at the edge of the
dialog box.
Parameter offset determines what will be the initial content of the request box,
and where the entered characters will be stored. See DialogDo for
info how and where entered characters are actually stored.
DialogAddRequest returns H_NULL
in a case of error, else returns Handle.
HANDLE DialogAddPulldown (HANDLE Handle, short x, short y, const char *prompt,
HANDLE MenuHandle, unsigned short index);
Adds a pulldown menu into a dialog box.
DialogAddPulldown adds a pulldown menu to the dialog structure associated with handle
Handle at the position (x, y), where coordinates are
relative to the top-left corner of the dialog box. prompt is the prompt which
will appear in front of the pulldown menu, and MenuHandle is a handle of the
associated menu which need to be created using PopupNew
function (the same functions are used for creating pulldown and popup menus). See
menus.h for more info about creating menus.
DialogAddPulldown returns H_NULL
in a case of error, else returns Handle. The text must fit into one line of
the dialog box.
Parameter index determines where the result value of executing the pulldown
menu will be stored, and what will be the initial selected option too. See
DialogDo for info how and where result values are actually stored.
short DialogDo (HANDLE Handle, short x, short y, char* RequestBuffer, short *PulldownBuffer);
Activates and shows a dialog box.
DialogDo activates and shows on the screen the dialog associated with handle Handle.
The top-left corner of the dialog will be at the position (x, y),
where coordinates are absolute screen coordinates. x, y or both may
also have a special value CENTER which means "center the dialog on
the screen in x, y or both directions". DialogDo returns KEY_ENTER
or KEY_ESC, depending of whether the user
exits the dialog by pressing ENTER or ESC key
(note that structures pointed to by RequestBuffer and PulldownBuffer will be
modified regardless of whether the user exits the dialog by pressing ENTER or ESC). It also
may return a negative number in a case of error (e.g. no enough memory to display the dialog
box). After the execution is finished, the original
content of the screen will be restored. This routine may cause the heap compression.
Parameter RequestBuffer is the pointer to the buffer where character entered
into request boxes will be stored. This buffer may store more than one string; the characters
entered into a request box will be stored starting from address
RequestBuffer + offset, where offset is the parameter
given with DialogAddRequest command which created
this request box. Each stored
string will be zero terminated. This buffer may be pre-filled with the initial content which
will appear in request boxes. Namely, initial content of any request box will be
a sequence of characters starting from address RequestBuffer + offset
up to the first zero ('\0') character (where offset is the parameter given when
the request box is created). If the dialog does not contain any request boxes,
RequestBuffer may be NULL.
Parameter PulldownBuffer is the pointer to the buffer where return values
of execution of pulldown menus will be stored. This buffer is, in fact. an array of
integers; the return value of executing a pulldown menu will be stored in
PulldownBuffer[index], where index is the parameter
given with DialogAddPulldown command which created
this pulldown menu. This array may be pre-filled with the ordinal numbers of initial
option in pulldown menus. Namely, initial selected option content of any pulldown menu
will be an option with ordinal number PulldownBuffer[index]
(where index is the parameter given when the pulldown menu is created).
If the dialog does not contain any pulldown menus,
PulldownBuffer may be NULL.
Here is a concrete example, which creates a dialog which asks the user for his name,
then displays a message box with greetings message in which user's name is included,
except if the user pressed ESC key:
char *buffer = "Hello \0 "; // fill with 20 spaces
HANDLE handle = DialogNewSimple (140, 55);
DialogAddTitle (handle, "EXAMPLE", BT_OK, BT_CANCEL);
DialogAddText (handle, 3, 20, "Enter name (max. 20 chars)");
DialogAddRequest (handle, 3, 30, "Your name`", 6, 20, 14);
if (DialogDo (handle, CENTER, CENTER, buffer, NULL) == KEY_ENTER)
DlgMessage ("GREETINGS", buffer, BT_OK, BT_NONE);
HANDLE DialogAdd (HANDLE Handle, short unknown, short x, short y, short ItemType, ...);
Adds an item into a dialog box.
DialogAdd is an universal item-adding function. It is a very complicated function
which accepts from 7 to 12 parameters depending of the type of the item which will
be added (the type is determined by parameter ItemType). In fact, functions like
DialogAddText, DialogAddTitle,
DialogAddRequest and DialogAddPulldown
are implemented as macros which calls DialogAdd function with appropriate parameters
(for easier using), so you can mainly avoid this function at all
(you can list dialogs.h file to see how exactly these macros are implemented). However, this
function has so many parameters that I didn't discover all variants, so existence of
this function would allow possibilities not covered with functions like
DialogAddText. At the moment, I still don't know how to
create a dialog with function keys (like "MODE" and "VAR-LINK" dialogs), nor a dialog
with scrolling items (like "UNITS" dialogs). DialogAdd returns H_NULL
if ItemType is wrong.
This function is open for anybody which
knows more about dialogs than I know. What I also know is that legal ItemType
values are: 2, 3, 7, 8, 10, 12 and 14. 2 is for adding request boxes, 7 for adding texts,
8 for adding titles, and 14 for adding pulldown menus. 10 and 12 are also related with
request boxes and pulldown menus, but required extra parameters are somewhat different.
It seems that 11 was planed for adding function keys, but not implemented, so it is very
questionable whether function key menus can be added to dialogs using DialogAdd.
DialogAdd with ItemType equals to 3 is the general dialog setup command, but
it needs 12 parameters and I still don't success to discover them exactly. This command
(with ItemType set to 3) is a key for creating dialogs with scrolling items.
Any info is welcomed.
HANDLE DialogNew (short width, short height, short (*UserFunc)(short, long));
Creates a new dialog box which can interact with the user program.
DialogNew acts like DialogNewSimple, but accepts
a pointer to the user function UserFunc as third parameter. This function
is called (as far as I know):
- whenever an item in the dialog box is created or recreated;
- when an item gets a focus;
- after the user pressed ENTER in a request box;
- after execution of any pulldown menu.
Such user function allows interaction between execution of dialog boxes and the user
program, and allows creating dialog boxes which dinamically change its properties
during execution. I still don't know all possibilities of such interaction, but
what I know is quite enough for creating very complex dialog boxes.
Whenever the user function is called, two parameters (one short and one long, I will
call them x and y for simplicity) are passed to it. What I know about them at the
moment is:
- When an item in the dialog box is created, recreated or gets a focus, x = -2 and
y will be equal to the ordinal number of the item in the list of dialog items
(first added item after DialogNew has
ordinal number 0, the next one has number 1, etc.). If the user function returns 0,
the item in the dialog box will be dimmed (displayed as
gray) and inactive (nonselectable), else it will be normal.
- After the user pressed ENTER in a request box, x will be nonnegative and
equal to the ordinal number of the item (i.e. this request box) in the list
of dialog items. y will contain the absolute address of the place where the
content of the request box is stored. I don't know what return value of the
user function means in this case. In according what TIOS does during executing of
built-in dialogs, you should return 1 for normal return in this case. Returning -3
and -4 will force redrawing the dialog box; in addition to this, return value
-3 will force ignoring the key just pressed by the user.
- After execution of the pulldown menu, x will also be nonnegative and equal to
the ordinal number of the item in the list of dialog items. y will contain the
result of executing the menu. The user function should return 1 if you want to
continue execution of the dialog normally. If the user function returns -8,
execution of the dialog will be terminated immediately. Return values -3 and
-4 have the same meaning as with request boxes.
-
There is also one event known to me in which x = -6. In normal situations
this event will not happen, but I will describe what I know about it, maybe later
more info will be available. This event happens when a special request box which may be
added to the dialog using DialogAdd with ItemType set
to 10 is created or gets a focus. The user function in such case must return a handle
which points to a memory area from where such request box will get its initial value,
and where the content of the request box would be stored. I think that "normal"
request boxes are quite enough for all purposes, so I will not explain this special
feature in more details.
After pressing ENTER in a request box or after execution of a pulldown menu, all
items in the dialog will be recreated (and user function will be called for each
item accordingly). This allows creating dialogs in which execution of various
options in pulldown menus makes some other items in the dialog dimmed or active again.
Dummy function.
NoCallBack is a dummy function which does nothing, and always returns 1 as result.
The purpose of this function is in the fact that it may be given as a third parameter
to the function DialogNew, when there is no need for an
interaction with the user program during the execution of the dialog (i.e. no
"calling back"). DialogNewSimple does exactly this:
it calls DialogNew with NoCallBack as a third parameter.
NOTE: This routine was in TIOS jump table up to AMS 1.xx. In AMS 2.xx it is not more
in jump table! Here, NoCallBack is implemented on such whay that it can be used on
any version of AMS.
Shows and activates a dialog box giving a pointer to a dialog structure.
Dialog works exactly like DialogDo, except instead of the
handle, a pointer to the dialog structure is given as the parameter.
DialogDo internally calls HeapDeref,
then passes returned pointer to Dialog function. This function is manly used
internally in TIOS. Its advance in comparing to DialogDo is
in the fact that the complete dialog structure may be given as a static pre-filled
array of butes, and you can give the pointer to such structure to Dialog function.
It will save a lot of memory, because you need not to call DialogNew,
a lot of functions like DialogAddText etc. But note that
the dialog structure is an extremely complicated variable-shape structure, so if you
don't know EXACTLY what you are doing, avoid this function!
Constants and predefined types
Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};
Buttons is enumerated type for describing possible button types. It is defined as
enum Buttons {BT_NONE, BT_OK, BT_SAVE, BT_YES, BT_CANCEL, BT_NO, BT_GOTO};
NULL is a null-pointer value, defined as (void *) 0.
HANDLE is a type which represents handles associated to allocated memory
blocks. It is defined as
typedef unsigned short HANDLE;
H_NULL is a null-handle defined as a constant with value 0.
When used in DialogDo command as the parameter, CENTER means
"center the dialog on the screen in x, y or both directions", depending of as which parameter
CENTER is used. CENTER has in fact value -1.