Preparing and Running the Dialog

This section presents the methods used to prepare and initialize a dialog, show it, run it, and stop it.

Init

>>-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.

Protected:

This method is protected. You cannot create an instance of BaseDialog. You can only create instances of its subclasses.

Arguments:

The arguments are:

Library

The file name of a .DLL file. Pass an empty string if you do not use binary resources.

id

The resource ID, (numeric or symbolic,) of the dialog within the resource file.

DlgData.

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.

hFile

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.

Example:

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

InitAutoDetection

>>-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.

Protected:

This method is protected. You can override this method within your subclass to change the standard behavior.

Example:

The following example overrides the method to switch off auto detection:

::class MyDialog subclass UserDialog
::method InitAutoDetection
   self~NoAutoDetection

NoAutoDetection

>>-aBaseDialog~NoAutoDetection---------------------------------><


The NoAutoDetection method switches off auto detection.

AutoDetection

>>-aBaseDialog~AutoDetection----------------------------------->>


The AutoDetection method switches on auto detection.

InitDialog

>>-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.

Protected:

The method is designed to be overwritten in subclasses; it cannot be called from outside the class.

Example:

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")

Run

>>-aBaseDialog~Run---------------------------------------------><


The Run method dispatches messages from the Windows dialog until the user terminates the dialog by one of the following actions:

Protected:

Run is a protected method. You cannot call this method directly; it is called by Execute.

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.

Arguments:

The arguments are:

show

See Show.

icon

The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.

Return value:

0

The dialog was not executed.

1

You terminated the method using the OK button.

2

You terminated the method using the Cancel button.

Example:

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)

ExecuteAsync

>>-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.

Arguments:

The arguments are:

sleeptime

The time slice, in milliseconds, until the next message is processed.

show

See Show.

icon

The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.

Return value:

0

The dialog was started.

1

An error occurred. Do not call the EndAsyncExecution method in this case.

Example:

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

EndAsyncExecution

>>-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.

Return value:

0

The dialog was not executed.

1

The dialog was terminated using the OK button.

2

The dialog was terminated using the Cancel button.

Example:

See the example in ExecuteAsync.

Popup

                          +-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.

Arguments:

The arguments are:

show

See Show.

sleeptime

The time, in milliseconds, until the next message is processed.

icon

The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.

Return value:

This method does not return a value.

Example:

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
end

This 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.

PopupAsChild

                                            +-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.

Arguments:

The arguments are:

parent

An object of the PlainBaseDialog class or one of its descendants that is the parent of the newly started dialog.

show

See Show.

sleeptime

The time, in milliseconds, until the next message is processed.

icon

The resource ID of the dialog's icon. If an icon ID is not supplied, the default ooDialog icon will be used.

Return value:

This method does not return a value.

Example:

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 */
end

This 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.

IsDialogActive

>>-aBaseDialog~IsDialogActive----------------------------------><


The IsDialogActive method returns 1 if the Windows dialog still exists.

Example:

The following example tests whether the dialog is active:

if MyDialog~IsDialogActive then ...

StopIt

>>-aBaseDialog~StopIt------------------------------------------><


The StopIt method removes the Windows dialog from the memory. It is called by Execute, after the user terminates the dialog.

Protected:

This method is protected and for internal use only.

HandleMessages

>>-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.

AsyncMessageHandling

>>-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).

Protected:

This method is protected and for internal use only.

Arguments:

The only argument is:

sleeptime

The time slice, in milliseconds, until the next message is processed.

PeekDialogMessage

>>-aBaseDialog~PeekDialogMessage-------------------------------><


The PeekDialogMessage method returns the first pending message of the dialog's message queue without removing it from the message queue.

Return value:

The first pending message or an empty string.

ClearMessages

>>-aBaseDialog~ClearMessages-----------------------------------><


The ClearMessages method clears all pending dialog messages.

SendMessageToItem

>>-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.

Arguments:

The arguments are:

id

The ID of the dialog item.

msg

The Windows message (you need a Windows SDK to look up these numbers).

wp

The first message parameter (wParam).

lp

The second message parameter (lParam).

Example:

The following example sets the marker to radio button 9001:

MyDialog~SendMessageToItem(9001, "0x000000F1", 1, 0)