DialogNew Function (ROM Call 0x34)

dialogs.h

HANDLE DialogNew (short Width, short Height, Dialog_Callback_t Callback);

Creates a new dialog box which can interact with the user program.

DialogNew acts like DialogNewSimple, but accepts a pointer to a user callback function Callback as a third parameter (i.e. you must pass the pointer of a function you wrote in your source code which contains the parameter types defined by Dialog_Callback_t). This function is called more than once during the dialog's execution.

Such a user function allows for interaction between the dialog box and the user program, and permits the creation of dialog boxes which dynamically change their contents during execution. This is a kind of event-driven programming: When an event occurs in the dialog, the Callback function will be called with a specific Message parameter Message that should be processed so as to know what data the parameter Value contains. Events are only sent on a few occasions, which include:

This function has to return a value, whose meaning also depends on the input Message parameter. However, in simple dialog boxes without any dynamic elements, you may always pass TRUE, which is the same as DB_CONTINUE, i.e. the standard return value. Note that if you do not want to take care of the Callback function at all (i.e. if you do not want to write such a function) you can use the already written NoCallBack function, which does nothing but return TRUE whatever the entering message is (but in that case, the best thing is to use DialogNewSimple, which in fact is a macro using both DialogNew and NoCallBack).

Note that if you choose not to create a CallBack function, some of the items (such as D_MENU) and the DF_OWNER_DRAW flag will not be very useful for you as they need to be handled in the callback function.

The following table shows what the Message value can be, when events occur and what you should return from Callback. The constants are defined in the enum DialogMessages:

A nonnegative value This occurs when the user pressed ENTER to activate an item, or to return from an activated item.
This nonnegative value is in fact the identification number of an item in a dialog. This identification number is created automatically when you use one of the creation functions DialogAdd, DialogAddText, DialogAddPulldown, and all other functions starting with "DialogAdd". A value of 0 represents the first item you created in the dialog box, 1 is the second one, 2 the third one, and so on.
The meaning of the Value parameter depends on the type of the item. See below for a list of possible meanings.
The return value should be a message from the enum DialogMessages:
DB_CONTINUE Process the key pressed by the user, but do not redraw the dialog box.
DB_REDRAW Redraw the dialog box and ignore the key pressed by the user.
DB_REDRAW_AND_CONTINUE Redraw the dialog box, then process the key pressed by the user.
DB_EXIT You can return this value if you want the dialog box to stop its execution immediately.
DB_QACTIVE Query the status of an item (enabled/disabled).
This occurs whenever an item in the dialog box is created, gets the focus, or whenever the dialog box needs to update the state of the item. In this case, the value passed through Value is the identification number of an item in the dialog (0 for the first one, 1 for the second one, and so on). You should return TRUE if the item is enabled and should not be grayed out, or FALSE if the item is disabled and must be grayed out). Note that static items such as D_TITLE and D_TEXT are not even drawn if they are disabled.
DB_GET_TITLE Query the title of a dynamic header.
This event occurs when a special title bar which may be added to the dialog using DialogAdd with ItemType set to D_DYNHEADER is created. The Value parameter will be zero, and the callback function must return the text for the title of the dialog box.
Note: as statically created dynamic titles are not known very well for the moment, in most cases you do not have to care about this value.
DB_GET_EDIT_HANDLE Query the text buffer of a dynamic edit field.
This event occurs when a special request box which may be added to the dialog using DialogAdd with ItemType set to D_HEDIT (or using DialogAddDynamicRequest) is created or gets the focus. The value contained in Value is the identification number of this edit box item in the dialog. The callback function must return a handle which points to a buffer from where this request box will get its initial value, and where the contents of the request box will be stored. You may need the HeapAlloc function to get a new handle and HeapDeref to access the associated buffer (see the example below).
Note: See DialogAddDynamicRequest for more details about this special feature.

The following table shows what the Value parameter is if Message is a nonnegative value, depending on the item type:

Pulldown If the item identified by Message is a pulldown menu (i.e. if this item has been created using DialogAddPulldown or DialogAddPulldownEx, or DialogAdd with ItemType set to D_POPUP, D_HPOPUP or D_DYNPOPUP), the value contained in Value is the identification number of the item selected in the pulldown menu (not one of a dialog item). The event occurs only when the user selects an item and presses ENTER.
Request If the item identified by Message is a request item (i.e. if this item has been created using DialogAddRequest or DialogAddRequestEx, or DialogAdd with ItemType set to D_HEDIT or D_EDIT_FIELD), the value contained in Value is a pointer pointing to the data the user just entered.
Menu If the item identified by Message is a menu (i.e. if this item has been added using DialogAddMenu or DialogAdd with ItemType set to D_MENU), the value contained in Value is in fact the composition of two values: the 16 most significant bits (the high word) of Value contain the execution handle of the menu (the dialog box code calls MenuBegin initially to get a handle for the menu) and the 16 least significant bits (the low word) contain the key pressed by the user to activate the menu (for your convenience, common key values are defined in the CommonKeys enum). The macros LO_WORD and HI_WORD have been created to get both values easily. The callback function may activate the menu or change anything in it if needed. See MenuKey for more details on activating a menu.
Note: The return value of a menu differs from that of any other element: Returning a positive value will select (focus on) the dialog item whose identification number is equal to the value you returned. (This feature is mainly used in the TIOS 'MODE' dialog where pressing F1, F2 or F3 changes the page displayed, which is achieved by changing the focus.) With AMS 2.xx the return value can also be one of DB_REDRAW, DB_REDRAW_AND_CONTINUE or DB_EXIT, but not DB_CONTINUE, since that value is positive.
Owner Draw Text If the item identified by Message is an owner draw text/image (i.e. if this item has been created using DialogAdd with ItemType set to D_TEXT and Flags containing DF_OWNER_DRAW), the value contained in Value is a pointer to an OWNER_DRAW_STRUCT structure. The Item field in this structure is a direct pointer to the DIALOG_ITEM structure for the item to be drawn (this is not normally used). The pW field is a pointer to the WINDOW structure for the dialog box. Using this pointer, the callback function can draw anything anywhere to the dialog box (clipped to the window of the dialog box). For example, you can draw simple text using the WinStrXY function, or draw a standard button using DrawStaticButton, or a bitmap using WinBitmapPut, etc. In general, you will be able to use any of the functions from wingraph.h.

All other item types cannot be activated; Callback will not be called with their identification number as the Message parameter.

After pressing ENTER in a request box or after execution of a pulldown menu, the DB_QACTIVE message will be sent to all items in the dialog. This permits the user to create dialogs in which the selection of various options in pulldown menus enables or disables some other items.

Note: It might be useful for you to know that dereferencing the handle returned by DialogNew with HeapDeref or with HLock returns a pointer to the dialog's DIALOG structure.


Uses: HeapAlloc, memset
Used by: DialogNewSimple, DlgMessage, VarNew, VarOpen, VarSaveAs, cmd_dialog, cmd_request, EV_defaultHandler, HomeExecute


See also: DialogDo, Dialog, DialogAdd, DIALOG