Open Object Rexx™: Windows OODialog Reference
Prev		Next

Chapter 10. Standard Dialogs, External Functions, and Public Routines

Table of Contents
Standard Dialog Classes
External Functions
Public Routines

The ooDialog framework provides a number of easy to use standard dialogs, external functions, and public routines that allow programmers to include simple graphical elements in their ooRexx applications. A few of the functions, like MSSleep expose functionality that can be useful in any type of ooRexx application. The external functions and public routines can be called with a single line of code and the standard dialogs can usually be executed with only two lines of code. This does not require the programmer to do much set up and makes them simple to work with.

The standard dialogs, external functions, and public routines are listed the following table:

Table 10-1. Standard Dialogs, Functions, and Routines

Standard dialog...	...on page
CheckList	CheckList class
InputBox	InputBox class
IntegerBox	IntegerBox class
ListChoice	ListChoice class
MultiInputBox	MultiInputBox class
MultiListChoice	MultiListChoice class
PasswordBox	PasswordBox class
SingleSelection	SingleSelection class
TimedMessage	TimedMessage class

External function...	...on page
ErrorMessage	ErrorMessage function
GetFileNameWindow	GetFileNameWindow function
GetScreenSize	GetScreenSize function
GetSysMetrics	GetSysMetrics function
InfoMessage	InfoMessage function
PlaySoundFile	PlaySoundFile function
PlaySoundFileInLoop	PlaySoundFileInLoop function
SleepMS	SleepMS function
StopSoundFile	StopSoundFile function
WinTimer	WinTimer function
YesNoMessage	YesNoMessage function

Public routine...	...on page
AskDialog	AskDialog routine
CheckList	CheckList routine
ErrorDialog	ErrorDialog routine
FileNameDialog	FileNameDialog routine
FindWindow	FindWindow routine
InfoDialog	InfoDialog routine
InputBox	InputBox routine
IntegerBox	IntegerBox routine
ListChoice	ListChoice routine
MSSleep	MSSleep routine
MultiInputBox	MultiInputBox routine
MultiListChoice	MultiListChoice routine
PasswordBox	PasswordBox routine
Play	Play routine
ScreenSize	ScreenSize routine
SingleSelection	SingleSelection routine
SystemMetrics	SystemMetrics routine
TimedMessage	TimedMessage routine

Standard Dialog Classes

The standard dialog classes are:

TimedMessage
InputBox
PasswordBox
IntegerBox
MultiInputBox
ListChoice
MultiListChoice
CheckList
SingleSelection

Requires:

Use the oodPlain.cls file for the standard dialog classes.

::requires "oodPlain.cls"

Preparation:

Standard dialogs are prepared by using the new method of the class, which in turn invokes the Init method. The parameters for the new method are described for the Init method of each class.

Execution:

The dialog is then run by using the Execute method. For most of the standard dialogs Execute returns the user's input if the OK button is clicked and the null string if the Cancel button is clicked to terminate the dialog. If there is more than one return value, Execute returns the value 1 and stores the results in an attribute. Exceptions to the general rule are noted in the documentation for the individual dialog.

Functions:

Each standard dialog is also available as a callable function. These functions are described in the Public Routines section of this chapter.

TimedMessage Class

The TimeMessage class shows a message window for a defined duration.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the PlainUserDialog class
Execute:: There is no return from execute for this dialog.

The methods listed below are defined by this class.

Init

>>-aTimedMessage~Init(--msg--,--title--,--sleeping--+--------------+--)----><
                                                    +-,-earlyReply-+

The Init method prepares the dialog.

Arguments:

The arguments are:

message

A string that is displayed inside the window as a message. The length of the message determines the horizontal size of all standard dialogs.

title

A string that is displayed as the window title in the title bar of the dialog

sleeping

A number that determines how long (in milliseconds) the window is shown. If this number is 0 or greater, the message window is shown for that time and automatically dismisses itself. The programmer need take no further action.

If the number is less than 0 then the message window is shown indefinitely. The Execute method returns immediately. In this case, the programmer needs to dismiss the window manually. This is done by invoking the stopIt method. See Example 2 below.

earlyReply

The optional early reply argument defaults to false. If used and if true, the execute method of the dialog returns immediately. This allows the code at the point where execute was invoked to continue. The message windows continues to display for its specified duration and then dismisses itself automatically.

Example 1:

The following example shows a window with the title of Infomation for a duration of 3 seconds:

dlg = .TimedMessage~New("Application will be started, please wait", -
                        "Information", 3000)
dlg~Execute
drop dlg

Example 2:

The following example shows an introductory window that displays while an application is doing its time consuming start up routine. Since this start up process can vary in time depending on the individual system, the window is set to display indefinitely. When the start up process is finished, the programmer dismisses the window and destroys the dialog manually.

dlg = .TimedMessage~New("The WidgetCreator Application - loading ...", -
                        "The Widget Factory", -1)
dlg~Execute
ret = doStartup()
dlg~stopIt
drop dlg
if ret <> 0 then do
  ...
end

Example 3:

The following example is a variation on Example 2. In this case the Widget Factory executives decided that they want their WidgeCreator splash screen to always display for 2 seconds to the customer and then close. The early reply argument is used so that the start up routine executes immediately. After 2 seconds the splash screen dismisses and the dialog is destroyed automatically.

Note: It is not necessary to explicitly drop the dlg variable. That is shown in the other examples to emphasis the point that the dialog has been destroyed.

 
dlg = .TimedMessage~New("The WidgetCreator Application - loading ...", -
                        "The Widget Factory", 2000)
dlg~Execute
if doStartup() <> 0 then do
  ...
end

DefineDialog

>>-aTimedMessage~DefineDialog----------------------------------><

The DefineDialog method is called by the Create method of the parent class, PlainUserDialog, which in turn is called at the very beginning of Execute. You do not have to call it. However, you may want to override it in your subclass to add more dialog controls to the window. If you override it, you have to forward the message to the parent class by using the keyword super.

Example:

The following example shows how to subclass the TimedMessage class and how to add a background bitmap to the dialog window:

::class MyTimedMessage subclass TimedMessage inherit DialogExtensions

::method DefineDialog
   self~BackgroundBitmap("mybackg.bmp", "USEPAL")
   self~DefineDialog:super()

Execute

>>-aTimedMessage~Execute---------------------------------------><

The Execute method creates and shows the message window. If the specified duration (see Init method) is not negative, this method destroys the dialog automatically when the duration is up. If the duration is less than 0, then the programmer must destroy the dialog manually by invoking the stopIt method. See this example for a code snippet showing the procedure.

InputBox Class

The InputBox class provides a simple dialog with a title, a message, one entry line, an OK, and a Cancel push button.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the PlainUserDialog class
Execute:: Returns the user's input

The methods listed below are defined by this class.

Init

>>-aInputBox~Init(--message--,--title--,--prevalue--,--len--)----><

The Init method prepares the input dialog.

Arguments:

The arguments are:

message: A text string that is displayed in the dialog
title: A string that is displayed as the dialog's title in the title bar
prevalue: A string to initialize the entry line. If you do not want to put any text in the entry line, just pass an empty string.
len: The width of the entry line in dialog units

Example:

The following example shows an InputBox dialog with the title of Input and an entry line:

dlg = .InputBox~New("Please enter your email address", -
                    "Input", "user@host.domain", 150)
value = dlg~Execute
say "You entered:" value
drop dlg

DefineDialog

>>-aInputBox~DefineDialog--------------------------------------><

AddLine

>>-aInputBox~AddLine(--x--,--y--,--l--)------------------------><

The AddLine method is used internally to add one entry line to the dialog.

Execute

>>-aInputBox~Execute-------------------------------------------><

The Execute method creates and shows the dialog. After termination, the value of the entry line is returned if the user clicks the OK button; a null string is returned if the user clicks on Cancel.

PasswordBox Class

The PasswordBox class is an InputBox dialog with an entry line that echoes the keys with asterisks (*) instead of characters.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the InputBox Class
Execute:: Returns the user's password

The methods are the same as for the InputBox Class, with the exception of AddLine.

AddLine

>>-aPasswordBox~AddLine(--x--,--y--,--l--)---------------------><

The AddLine overrides the same method of the parent class, InputBox, by using a password entry line instead of a simple entry line.

IntegerBox Class

The IntegerBox class is an InputBox dialog whose entry line allows only numerical data.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the InputBox Class class
Execute:: Returns the user's numeric input

The methods are the same as for the InputBox Class class, with the exception of Validate.

Validate

>>-aIntegerBox~validate----------------------------------------><

The only method this subclass overrides is Validate, which is one of the automatically called methods of PlainUserDialog. It is invoked by the OK method, which in turn is called in response to a push button event. This method checks whether or not the entry line contains a valid numerical value. If the value is invalid, a message window is displayed.

MultiInputBox Class

The MultiInputBox class is a dialog that provides a title, a message, and one or more entry lines. After execution of this dialog you can access the values of the entry lines.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the "PlainUserDialog" class
Execute:: Returns 1 (if OK was clicked). The values entered by the user are stored in attributes matching the labels of the entry lines.

The methods are the same as for the InputBox Class class, with the exception of Init.

Init

>>-aMultiInputBox~Init(--message--,--title--,--labels.--,--datas.-->

>--+--------+--)--------------------------------------------------><
   +-,--len-+

The Init method is called automatically whenever a new instance of this class is created. It prepares the dialog.

Arguments:

The arguments are:

message: A text string that is displayed on top of the entry lines. Use it to give the user advice on what to do.
title: A text string that is displayed in the title bar.
labels.: A stem variable containing strings that are used as labels on the left side of the entry lines. Labels.1 becomes the label for the first entry line, labels.2 for the second, and so forth.
datas.: A stem variable (do not forget the trailing period) containing strings that are used to initialize the entry lines. The entries must start with 101 and continue in increments of 1.
len: The length of the entry lines. All entry lines get the same length.

Example:

The following example creates a four-line input box. The data entered is stored in the object attributes that are displayed after dialog execution.

lab.1 = "First name"  ;     lab.2 = "Last name "
lab.3 = "Street and City" ; lab.4 = "Profession:"

addr.101 = "John" ; addr.102 = "Smith" ; addr.103 = ""
addr.104 = "Software Engineer"

dlg = .MultiInputBox~new("Please enter your address", ,
"Your Address", lab., addr.)
if dlg~execute = 1 then do
  say "The address is:"
  say dlg~firstname dlg~lastname
  say dlg~StreetandCity
  say dlg~Profession
end

ListChoice Class

The ListChoice class provides a dialog with a list box, an OK, and a Cancel button. The selected item is returned if the OK push button is used to terminate the dialog.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the "PlainUserDialog" class
Execute:: Returns the user's choice or a null string

The method listed below is defined by this class.

Init

>>-aListChoice~Init(--message--,--title--,--input.-------------->

>--+---------------------------------------------------+-------><
   +-,--+------+--+-------------------------------+--)-+
        +-lenx-+  +-,--+------+--+--------------+-+
                       +-leny-+  +-,--preselect-+

The Init method is used to initialize a newly created instance of this class.

Arguments:

The arguments are:

message: A text string that is displayed on top of the list box. Use it to give the user advice on what to do.
title: A text string for the dialog's title
input.: A stem variable (do not forget the trailing period) containing string values that are inserted into the list box
lenx, leny: The size of the list box in dialog units
preselect: Entry that is selected when list pops up

Example:

The following example creates a list choice dialog box where the user can select exactly one dessert:

lst.1 = "Cookies"; lst.2 = "Pie"; lst.3 = "Ice cream"; lst.4 = "Fruit"

dlg = .ListChoice~new("Select the dessert please","YourChoice",lst., , ,"Pie")
say "Your ListChoice data:" dlg~execute

MultiListChoice Class

The MultiListChoice class is an extension of the ListChoice class. It makes it possible for the user to select more than one line at a time. The Execute method returns the selected items' indexes separated by blank spaces. The first item has index 1.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the ListChoice Class
Execute:: Returns the index numbers of the entries selected
Preselect:: Indexes of entries, separated by a blank, that are to be preselected. The first entry has index 1 and the rest are increments of one.

The methods are the same as for the ListChoice Class class, except that Execute returns the index numbers of the selected entries.

Example:: The following example creates a multiple list choice box where the user can select multiple entries:

lst.1 = "Monday" ;   lst.2 = "Tuesday" ; lst.3 = "Wednesday"
lst.4 = "Thursday" ; lst.5 = "Friday" ;  lst.6 = "Saturday"
lst.7 = "Sunday"

dlg = .MultiListChoice~new("Select the days you are working this week", ,
                           "YourMultipleChoice",lst., , ,"2 5")
s = dlg~execute
if s <> "" then do while s \= ""
                  parse var s res s
                  say lst.res
               end

CheckList Class

The CheckList class is a dialog with a group of one or more check boxes.

Requires:: oodPlain.cls is required to use this class.
Subclass:: This class is a subclass of the "PlainUserDialog" class.
Execute:: Returns 1 (if OK was clicked). The check boxes selected by the user are marked in a stem variable with the value 1.

The method listed below is defined by this class.

Init

>>-aCheckList~Init(--message--,--title--,--labels.--,--datas.-->

>>--+------------------------+--)-----------------------------><
    +-,--+-----+--+--------+-+
         +-len-+  +-,--max-+

Arguments:

The arguments are:

message

A text string that is displayed on top of the check box group. Use it to give the user advice on what to do.

title

A text string for the dialog's title

labels.

A stem variable (do not forget the trailing period) containing all the labels for the check boxes

datas.

This argument is a stem variable (do not forget the trailing period) that you can use to preselect the check boxes. The first check box relates to stem item 101, the second to 102, and so forth. A value of 1 indicates selected, and a value of 0 indicates deselected.

For example, Datas.103=1 indicates that there is a check mark on the third box.

len

Determines the length of the check boxes and labels. If omitted, the size is calculated to fit the largest label.

max

The maximum number of check boxes in one column. If there are more check boxes than max - that is, labels. has more items than the value of max - this method continues with a new column.

Example:

The following example creates and shows a dialog with seven check boxes:

lst.1 = "Monday";   lst.2 = "Tuesday"; lst.3 = "Wednesday"
lst.4 = "Thursday"; lst.5 = "Friday";  lst.6 = "Saturday"
lst.7 = "Sunday"

do i = 101 to 107
   chk.i = 0
end

dlg = .CheckList~new("Please select a day!","Day of week",lst., chk.)
if dlg~execute = 1 then do
   say "You selected the following day(s): "
   do i = 101 to 107
      a = i-100
      if chk.i = 1 then say lst.a
   end
end

SingleSelection Class

The SingleSelection class shows a dialog that has a group of radio buttons. The user can select only one item of the group.

Requires:: oodPlain.cls is required to use this class
Subclass:: This class is a subclass of the "PlainUserDialog" class
Execute:: Returns the number of the radio button selected

The method listed below is defined by this class.

Init

>>-aSingleSelection~Init(--message--,--title--,--labels.--,--data-->

>--+------------------------+--)-------------------------------><
   +-,--+-----+--+--------+-+
        +-len-+  +-,--max-+

Arguments:

The arguments are:

message: A text string that is displayed on top of the radio button group. Use it to give the user advice on what to do.
title: A text string for the title bar
labels.: This argument is a stem variable containing all labels for the radio buttons
data: You can use this argument to preselect one radio button. A value of 1 selects the first radio button, a value of 2 selects the second, and so on.
len: Determines the length of the check boxes and labels. If omitted, the size is calculated to fit the largest label.
max: The maximum number of radio buttons in one column. If there are more radio buttons than max - that is, labels. has more items than the value of max - this method continues with a new column.

Example:

The following example creates and executes a dialog that contains a two-column radio button group. The fifth radio button (the button with the label May) is preselected.

mon.1 = "January" ; mon.2 = "February" ; mon.3 = "March"
mon.4 = "April"   ; mon.5 = "May"      ; mon.6 = "June"
mon.7 = "July"    ; mon.8 = "August"   ; mon.9 = "September"
mon.10= "October" ; mon.11= "November" ; mon.12= "December"

dlg = .SingleSelection~new("Please select a month!", ,
                           "Single Selection", mon., 5, , 6)
s = dlg~execute
say  "You Selected the month: " mon.s

Prev	Home	Next
Appearance Modification Methods		External Functions