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


short DlgMessage (char *title, char *message, short left_button, short right_button);

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_NONENo button at all
BT_OKButton "Enter=OK"
BT_SAVEButton "Enter=SAVE"
BT_YESButton "Enter=YES"
BT_CANCELButton "Esc=CANCEL"
BT_NOButton "ESC=NO"
BT_GOTOButton "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 (xy), 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 (xy), 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 (xy), 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 (xy), 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): 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: 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.

short NoCallBack (short x, long y);

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.

short Dialog (void *DialogPtr, short x, short y, char* RequestBuffer, short *PopupBuffer);

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


enum Bool

Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};

enum Buttons

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};

const NULL

NULL is a null-pointer value, defined as (void *) 0.

type HANDLE

HANDLE is a type which represents handles associated to allocated memory blocks. It is defined as

typedef unsigned short HANDLE;

const H_NULL

H_NULL is a null-handle defined as a constant with value 0.

const CENTER

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.

Return to the main index