This section presents the methods used to prepare and initialize a dialog, show it, run it, and stop it.
>>-aBaseDialog~Init(--+---------+--,--id--+-------------+--+----------+--)--><
+-Library-+ +-,--DlgData.-+ +-,--hFile-+
The constructor of the class installs the necessary C functions for the Object Rexx API manager and prepares the dialog management for a new dialog.
This method is protected. You cannot create an instance of BaseDialog. You can only create instances of its subclasses.
The arguments are:
The file name of a .DLL file. Pass an empty string if you do not use binary resources.
The resource ID, (numeric or symbolic,) of the dialog within the resource file.
A stem variable (remember the period!) that contains initialization data for the dialog. For example, if you assign the string "Hello world" to DlgData.103, where 103 is the ID of an entry field, it is initialized with this string. If the dialog is terminated with OK, the data of the dialog is copied into this stem variable.
A file, (often called a header file,) defining symbolic IDs for resources. The symbolic IDs defined within the file will be added to the ConstDir directory.
The following example shows how a header file, symbolic IDs, and the data stem can be used in instantiating a new object that is a subclass of the ResDialog. Assume resources.h is a file in the same directory as the program file and contains the following:
/* resources.h */ #define IDD_BUILD_DLG 100 #define IDC_EDITFIELD_INCLUDE 110 #define IDC_COMBOBOX_PROJECT 120 #define IDC_RADIO_DEBUG 130 #define IDC_RADIO_RELEASE 131 #define IDC_CHECKBOX_CLEAN 140 #define IDI_DLG_ICON 514
The dialog (a fictitious build dialog) will have an entry line, a combo box, two radio buttons, and a check box. The DlgData. stem will be used to initialize the values of the controls using the symbolic IDs defined in the header file.
/* BuildDlg.rex */
DlgData.IDC_EDITFIELD_INCLUDE = "C:\sdk\include"
DlgData.IDC_COMBOBOX_PROJECT = "Calculator"
DlgData.RADIO_DEBUG = 0
DlgData.RADIO_RELEASE = 1
DlgData.CHECKBOX_CLEAN = 0
dlg = .BuildDialog~new( "dlg.dll", IDD_BUILD_DLG, DlgData, "resources.h" )
if dlg~initCode <> 0 then do
say "Error starting dialog. initCode:" dlg~initCode
return dlg~initCode
end
dlg~execute( "NORMAL", IDI_DLG_ICON )
...
At this point the dialog is shown, the entry line will contain "C:\sdk\include", the combo box will have the Calculator project selected, the release radio button will be checked, (the debug radio button will not be checked,) and the clean check box will not be checked.
The user interacts with the dialog and selects ok to close it. Now the state of the dialog when it was closed can be determined by checking the DlgData. stem values.
...
dlg~deinstall
if DlgData.CHECKBOX_CLEAN == 1 then doClean()
includePath = DlgData.IDC_EDITFIELD_INCLUDE
if DlgData.RADIO_RELEASE == 1 then
success = doReleaseBuild(includePath)
else
success = doDebugBuild(includePath)
return success
>>-aBaseDialog~InitAutoDetection-------------------------------><
The InitAutoDetection method is called by the Init method to change the default setting for the automatic data field detection.
Automatic data field detection means that for every dialog data item a corresponding Object Rexx attribute is created automatically. If you disable automatic detection, you have to use the Connect... methods to assign a dialog item to an Object Rexx attribute.
This method is protected. You can override this method within your subclass to change the standard behavior.
The following example overrides the method to switch off auto detection:
::class MyDialog subclass UserDialog ::method InitAutoDetection self~NoAutoDetection
>>-aBaseDialog~NoAutoDetection---------------------------------><
The NoAutoDetection method switches off auto detection.
>>-aBaseDialog~AutoDetection----------------------------------->>
The AutoDetection method switches on auto detection.
>>-aBaseDialog~InitDialog--------------------------------------><
The InitDialog method is called after the Windows dialog has been created. It is useful for setting data fields and initializing combo and list boxes. Do not use Set... methods because the SetData method is executed automatically afterwards and sets the values of all dialog items from the attributes.
The method is designed to be overwritten in subclasses; it cannot be called from outside the class.
The following example shows how to use InitDialog to initialize dialog items; in this case a list box:
::class MyDialog subclass Userdialog ::method InitDialog self~InitDialog:super AddListEntry(501, "this is the first line") AddListEntry(501, "and this one the second")
>>-aBaseDialog~Run---------------------------------------------><
The Run method dispatches messages from the Windows dialog until the user terminates the dialog by one of the following actions:
Press the OK button (the push button with ID 1)
Press the Cancel button (the push button with ID 2)
Press the Enter key (if OK or Cancel is the default button)
Press the Esc key
Run is a protected method. You cannot call this method directly; it is called by Execute.
+-DEFAULT--+
>>-aBaseDialog~Execute(--"--+----------+--"--+---------+--)----><
+-NORMAL---+ +-,--icon-+
+-SHOWTOP--+
+-HIDE-----+
+-MIN------+
+-MAX------+
+-INACTIVE-+
The Execute method creates the dialog, shows it (see Show), starts automatic methods, and destroys the dialog. The data is passed to the Windows dialog before execution and received from it after the dialog is terminated.
Note: If another dialog has already been started in the same process, it is disabled by Execute.
The arguments are:
See Show.
The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.
The dialog was not executed.
You terminated the method using the OK button.
You terminated the method using the Cancel button.
The following example instantiates a new dialog object (remember that it is not possible to instantiate an object of the BaseDialog class), creates a dialog template, and runs the dialog as the topmost window. The dialog icon is one of the pre-defined icons supplied by ooDialog:
MyDialog = .UserDialog~new(...)
MyDialog~Create(...)
MyDialog~Execute("SHOWTOP", IDI_DLG_OOREXX)>>-aBaseDialog~ExecuteAsync--+--------------+------------------->
+-(--sleeptime-+
>--+-----------------------------------------------+-----------><
+-+----------------------------------------+--)-+
+-,--+--------------------+--+---------+-+
| +-DEFAULT--+ | +-,--icon-+
+-"--+-NORMAL---+--"-+
+-SHOWTOP--+
+-HIDE-----+
+-MIN------+
+-MAX------+
+-INACTIVE-+
The ExecuteAsync method does the same as Execute, except that it dispatches messages asynchronously. Therefore the ExecuteAsync method returns immediately after the dialog has been started.
The arguments are:
The time slice, in milliseconds, until the next message is processed.
See Show.
The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.
The dialog was started.
An error occurred. Do not call the EndAsyncExecution method in this case.
The following example starts a dialog and runs the statements between ExecuteAsync and EndAsyncExecution asynchronously to the dialog:
ret = MyDialog~ExecuteAsync(1000, "SHOWTOP") if ret = 0 then do ... /* Object Rexx statements to run while the dialog is executing */ ... MyDialog~EndAsyncExecution end else do call errorDialog "Could not start dialog" end
>>-aBaseDialog~EndAsyncExecution-------------------------------><
The EndAsyncExecution method is used to complete the asynchronous execution of a dialog. It does not terminate the dialog but waits until the user terminates it.
The dialog was not executed.
The dialog was terminated using the OK button.
The dialog was terminated using the Cancel button.
See the example in ExecuteAsync.
+-DEFAULT--+
>>-aBaseDialog~Popup(--"--+----------+--"--+-------------------------------+--)-><
+-NORMAL---+ +-,--+-----------+--+---------+-+
+-SHOWTOP--+ +-sleeptime-+ +-,--icon-+
+-HIDE-----+
+-MIN------+
+-MAX------+
+-INACTIVE-+
The Popup method starts a dialog, dispatches messages asynchronously, and returns immediately after the dialog is started.
A dialog started with Popup is independent of any other dialog. This means that a dialog already started in the same process is not disabled by Popup. You can therefore use Popup to produce nonmodal dialogs.
The arguments are:
See Show.
The time, in milliseconds, until the next message is processed.
The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.
This method does not return a value.
The following example starts a dialog and runs the statements after Popup asynchronously to the dialog. This means that the dialog reacts to an event like pressing a button and calls the connected method while the DO loop is being processed:
MyDialog~Popup("SHOWTOP", 250)
do i = 1 to 1000
say "Iteration" i
call msSleep 100
endThis example could also be part of a method handling an event of a dialog, for example dialog A. The newly started dialog MyDialog is independent of dialog A. If dialog A is closed, MyDialog remains unaffected and active.
+-DEFAULT--+
>>-aBaseDialog~PopupAsChild(--parent--,--"--+----------+--"----->
+-NORMAL---+
+-SHOWTOP--+
+-HIDE-----+
+-MIN------+
+-MAX------+
+-INACTIVE-+
>--+-------------------------------+--)------------------------><
+-,--+-----------+--+---------+-+
+-sleeptime-+ +-,--icon-+
The PopupAsChild method starts a dialog as a child dialog of another dialog, dispatches messages asynchronously, and returns immediately after the dialog is started.
A dialog started with PopupAsChild and its parent dialog can be active at the same time. This means that the parent dialog is not disabled by the child dialog. You can therefore use PopupAsChild to produce nonmodal dialogs. However, the child dialog is automatically terminated when the parent dialog is closed.
The arguments are:
An object of the PlainBaseDialog class or one of its descendants that is the parent of the newly started dialog.
See Show.
The time, in milliseconds, until the next message is processed.
The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.
This method does not return a value.
The following example starts a dialog and runs the statements after PopupAsChild asynchronously to the dialog. This means that the dialog reacts to an event like pressing a button and calls the connected method while the DO loop is being processed. The new dialog is started as a child of MyParent and is therefore closed when the MyParent dialog is closed:
MyParent = .UserDialog~new
...
MyParent~Popup("SHOWTOP")
...
MyDialog~PopupAsChild(MyParent, "SHOWTOP", 250)
do i = 1 to 1000
say "Iteration" i
call msSleep 100
if i = 800 then MyParent~Finished = 1 /* close both dialogs when i = 800 */
endThis example could also be part of a method handling an event of a dialog, for example dialog A. The newly started dialog MyDialog is independent of dialog A. If dialog A is closed, MyDialog remains unaffected and active.
>>-aBaseDialog~IsDialogActive----------------------------------><
The IsDialogActive method returns 1 if the Windows dialog still exists.
The following example tests whether the dialog is active:
if MyDialog~IsDialogActive then ...
>>-aBaseDialog~StopIt------------------------------------------><
The StopIt method removes the Windows dialog from the memory. It is called by Execute, after the user terminates the dialog.
This method is protected and for internal use only.
>>-aBaseDialog~HandleMessages----------------------------------><
The HandleMessages method handles dialog messages synchronously. It is called by Execute. HandleMessages is a dispatcher that receives Windows events and posts the message that is set to handle the event.
>>-aBaseDialog~AsyncMessageHandling(--sleeptime--)-------------><
The AsyncMessageHandling method starts the asynchronous handling of dialog messages. It is invoked automatically by ExecuteAsync with the Start method of the Object class. A message in this context is the name of an object method that is processed whenever the corresponding event occurs. You can set the messages that should be sent by using Connect... methods (see page Connect Methods).
This method is protected and for internal use only.
The only argument is:
The time slice, in milliseconds, until the next message is processed.
>>-aBaseDialog~PeekDialogMessage-------------------------------><
The PeekDialogMessage method returns the first pending message of the dialog's message queue without removing it from the message queue.
The first pending message or an empty string.
>>-aBaseDialog~ClearMessages-----------------------------------><
The ClearMessages method clears all pending dialog messages.
>>-aBaseDialog~SendMessageToItem(--id--,--msg--,--wp--,--lp--)-><
The SendMessageToItem method sends a Windows message to a dialog item. It is used to influence the behavior of dialog items.
The arguments are:
The ID of the dialog item.
The Windows message (you need a Windows SDK to look up these numbers).
The first message parameter (wParam).
The second message parameter (lParam).
The following example sets the marker to radio button 9001:
MyDialog~SendMessageToItem(9001, "0x000000F1", 1, 0)