![]() |
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:
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_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. |
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. |