Public Routines

The routines listed in this section can be used in any Rexx program. They are designed to be even easier to use than the standard dialogs or the external functions. They do not require that an ooDialog dialog be initialized prior to their use, or that any ooDialog dialog be used in the program at all. The programmer does not have to register any functions to use these routines.

Requires:

Use a requires directive for the ooDialog.cls file in an Rexx program to use any of these routines.

 
::requires ooDialog.cls 

Play Routine

This routine is used to play audio sounds.

>>-Play(--+----------+--+---------+--)------------------------><
          +-fileName-+  +-,--YES--+
                        +-,--LOOP-+


The Play routine can be used to play an audio file using the Windows multimedia capabilities. See also the PlaySoundFile external function.

The named file is searched for in the current directory and in the directories of the SOUNDPATH environment variable.

Arguments:

The arguments are:

fileName

The file name of an audio (.WAV) file. The file is searched for in the current directory and in the directories listed in the SOUNDPATH environment variable. If this argument is omitted, the currently playing sound file is stopped.

option

You can set the last argument to:

YES

This plays the audio file asynchronously.

LOOP

Plays the audio file asynchronously and repeats it in a loop. You can stop the loop by calling Play again omitting all arguments.

Example:

The following example plays a welcoming message:

rc = play("Welcome.wav")

InfoDialog Routine

Pops up a message box containing the specified text and an OK button.

>>-InfoDialog(--info_text--)----------------------------------><


Argument:

The only argument is:

info_text

Text to be displayed in the message box.

ErrorDialog Routine

Pops up a message box containing the specified text, an OK button, and an error symbol.

>>-ErrorDialog(--error_text--)--------------------------------><

Argument:

The only argument is:

error_text

Text to be displayed in the message box.

AskDialog Routine

Pops up a message box containing the specified text, a Yes button, and a No Button.

>>-AskDialog(--question--+-------------------+--)-------------><
                         +--, defaultbutton--+

Arguments:

The only argument is:

question

Text to be displayed in the message box.

defaultbutton

Specifies which button, the Yes or the No button, has the default focus when the message box pops up. This argument can be Yes or No and is optional. If the argument is omitted, the Yes button will be given the focus. Only the first letter of the option is needed and case is not significant.

Return Values:

0

The No button has been selected.

1

The Yes button has been selected.

FileNameDialog Routine

Causes a file selection dialog box to appear.

>>-FileNameDialog(--+---------+--+--------------------------------+-->
                    +-selfile-+  +-,--+--------+--+-------------+-+
                                      +-parent-+  +-,--filemask-+

>--+----------------------------------------------------------------->
   +-,--+------------+--+----------+--+-----------------+------------>
        +-loadorsave-+  +-,--title-+  +-,--defExtension-+


>--+-----------------------------------+--)-------------------------><
>--+----------------+--+------------+--+
   +-,--multiSelect-+  +-,--sepChar-+


Arguments:

The arguments are:

selfile

Preselected file name and / or initial directory information.

This argument places a preselected file name in the "File name" field of the file selection dialog. In addition this argument can also be used to specify the initial directory (folder) the dialog opens in.

When this argument contains no path information, then the File name field will contain the argument and the initial directory is determined by the operating system. Which directory the operating system picks varies slightly between Windows 98, Windows NT, Windows XP, etc. But, in general, it will be a directory previously used in one of the Windows common dialogs, or a directory in the users My Documents. (The exact behavior is documented by Microsoft.)

If the argument contains file name and path information, the initial directory will be determined by the path information and the File name field will contain the file information. When the selfile argument contains only path information and no file name information, i.e. the argument ends with a back slash ("\"), then the initial directory will be that path and the File name field will be left blank.

In cases where the argument contains incorrect path information the initial directory is determined as if no path information had been supplied and the entire value of the argument is placed in the File name field.

Note: Windows treats normal wild card characters as valid for file names. Therefore, values such as C:\*.* or C:\Windows\*.exe are acceptable for this argument.

parent

Handle to the parent window.

filemask

Pairs of null-terminated filter strings.

The first string in each pair is a display string that describes the filter (for example, "Text Files"), and the second string specifies the filter pattern (for example, "*.TXT"). To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, "*.TXT;*.DOC;*.BAK"). A pattern string can be a combination of valid file name characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string.

If omitted, "Text Files (*.TXT)"'0'x"*.TXT"'0'x"All Files (*.*)"'0'x"*.*" is used as the filter.

loadorsave

Specifies which dialog should be displayed, the File Open Dialog (the default) or the File Save Dialog. If the File Save Dialog is not explicitly requested the default File Open Dialog is always presented. Only the first letter of the argument is needed and case is not significant. For historic reasons this argument can also be 1 (File Open Dialog) or 0 (File Save Dialog.)

Load or 1

Display the File Open Dialog (default).

Save or 0

Display the File Save Dialog.

title

The window title. The default is "Open a File" or "Save File As", depending on what is specified for loadorsave.

defExtension

The default extension that is added if no extension was specified. The default is TXT.

multiSelect

Specifies if the File Open Dialog allows selection of multiple files. Normally, the open dialog allows the user to select one file only. This can be changed by specifying "MULTI" for this option. Only the first letter is needed and case is not significant.

MULTI

Multiple file selection is allowed. This option is ignored for File Save Dialogs. If the user selects multiple files, the result is then path file1 file2 file3 ...

sepChar

Specifies the separation character for the returned path and file names. This is needed for file names with blank characters. If this argument is omitted, the separation character is a blank. If the argument is specified, the returned path and file name uses this separation character. For example, if you specify "#" as the separation character, the return string might look as follows:

C:\WINNT#file with blank.ext#fileWithNoBlank.TXT

Return value:

Returns the selected file name or 0 if the user cancels the dialog. Open File dialogs with multiple selection return path file1 file2 file3 ... when the user selects multiple files.

Notes:

If the user changes directory with the File Open or File Save dialog, then the current directory of the Rexx program will be changed. This is the behavior of the underlying Windows dialog, which is designed to work that way. The ooDialog programmer should be aware of this behavior and insert code to change the directory back if that is needed. For example:

curdir = directory()
file = FileNameDialog("*.pdf", , "Adobe PDF Files"'0'x"*.pdf"'0'x)
call directory curdir

FindWindow Routine

Searches the Windows application list for a specific window and returns its handle.

>>-FindWindow(--Caption--)------------------------------------><

Argument:

The only argument is:

Caption

Caption of the window that is to be searched.

Return value:

Handle of the window or 0 if the window was not found.

ScreenSize Routine

Obtains the screen size in dialog units and in pixels

>>-ScreenSize()-----------------------------------------------><

Argument:

This function takes no arguments.

Return value:

An array containing the screen size. The size in dialog units of the width is at index 1 and the height in dialog units is at index 2. The size in pixels of the width is at index 3 and the height in pixels is at index 4.

Example

Get the screen size and display it to the user.

size = screenSize()
say
say 'The monitor is' size[1] 'dialog units wide and' size[2] 'dialog units high.'
say 'The monitor is' size[3] 'pixels wide and' size[4] 'pixels high.'

SystemMetrics Routine (deprecated)

Note: This routine is deprecated. It is replaced by the functionally equivalent getSystemMetrics() method of the .DlgUtil class. Do not use this routine in new code. Try to migrate existing code to to the .DlgUtil~getSystemMetrics() method. This routine may not exist in future versions of ooDialog.

MSSleep Routine

Sleeps for the specified number of milliseconds.

>>-MSSleep(--duration--)--------------------------------------><

Argument:

The only argument is:

duration

The time in milliseconds to sleep.

Return value:

This function always returns 0.

TimedMessage Routine

The TimedMessage routine provides a shortcut to invoke a TimedMessage dialog as a function:

ret = TimedMessage("We are starting...","Please wait",3000)

The parameters are the same as described in the Init method of the TimedMessage class.

The function returns 0, always, when the duration is non-negative. When the duration is less than 0, the function returns a reference to the TimedMessage dialog object. This is needed in order for the programmer to manually dismiss the dialog. Below are the same 3 examples listed for the TimedMessage dialog, modified to work with the public routine:

Example 1:

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

 
ret = timedMessage("Application will be started, please wait", -
                   "Information", 3000)

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. Note how a reference to the TimedMessage dialog is returned. The programmer only needs to use this to dismiss / destroy the dialog

dlg = timedMessage("The WidgetCreator Application - loading ...", -
                   "The Widget Factory", -1)
ret = doStartup()
dlg~stopIt
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.

 
ret = timedMessage("The WidgetCreator Application - loading ...", -
                   "The Widget Factory", 2000)

if doStartup() <> 0 then do
  ...
end

InputBox Routine

A shortcut function to invoke an InputBox dialog as a function:

say "Your name:" InputBox("Please enter your name","Personal Data")

The parameters are described in the Init method of theInputBox class.

PasswordBox Routine

A shortcut to invoke a PasswordBox dialog as a function:

pwd = PasswordBox("Please enter your password","Security")

The parameters are described in the Init method of the InputBoxclass.

IntegerBox Routine

A shortcut to invoke an IntegerBox dialog as a function:

say "Your age:" IntegerBox("Please enter your age","Personal Data")

The parameters are described in the Init method of the InputBoxclass.

MultiInputBox Routine

Provides a shortcut function to invoke a MultiInputBox dialog:

res = MultiInputBox("Enter your address","Personal Data", ,
                    .array~of("&First name","Last &name","&City"), ,
                    .array~of("John","Smith","San Jose"), 100)
if res \= .Nil then do entry over res
                       say "Address-line[]= " entry
                    end

The parameters are described in the Init method of the MultiInputBoxclass. However, instead of using stems, arrays are used for input.

The user's input to the dialog is also returned in an array. Note this other difference from the MultiInputBox dialog: if the user cancels the dialog .nil is returned rather than the empty string.

ListChoice Routine

The ListChoice function provides a shortcut to invoke a ListChoice dialog:

day = ListChoice("Select a day","My favorite day", ,
                 .array~of("Monday","Tuesday","Wednesday","Thursday", ,
                          "Friday","Saturday","Sunday") , , ,"Thursday")
say "Your favorite day is" day

The parameters are described in the Init method of the ListChoiceclass. However, instead of an input stem an array is passed into the function.

If the user cancels the dialog .nil is returned rather than the empty string.

MultiListChoice Routine

Provides a shortcut to invoke a MultiListChoice dialog as a function:

days = MultiListChoice("Select days","My TV Days", ,
                       .array~of("Monday","Tuesday","Wednesday", ,
                              "Thursday","Friday","Saturday","Sunday"), , ,"2 5")
if days <> .Nil then do day over days
                       say "TV day =" day
                    end

The parameters are described in the Init method of the MultiListChoiceclass. However, instead of stems, arrays are passed into the function.

If the user cancels the dialog .nil is returned rather than the empty string.

CheckList Routine

A shortcut function to invoke the CheckList dialog:

>>--CheckList(--message--,--title--,--labels--,-+-----------+---->
                                                +-,--checks-+

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


Arguments:

The arguments are similar to what is described in the Init method of the CheckListclass. However, instead of stems, arrays are passed into and returned from the function.

message

A text string that is displayed on top of the check box group. It could be used, for example, to give the user a hint as to what to do.

title

A text string for the dialog's title

labels

An array containing the labels, in order, for each of the check boxes. The dialog will contain a check box for each label.

checks

This argument is an array that allows you to pre-check any of the check boxes. For each index in this array whose item is .true, (or 1,) the check box at the corresponding index in the labels array will be checked. For any index that is not .true , the corresponding check box will not be checked. This means that the programmer only needs to put a .true at the indexes where he wants the check boxes checked. All the other indexes can be left empty.

len

Determines the length (in dialog units) 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, if labels has more items than the value of max, the check boxes will be put into columns. Each column will contain no more than the number of check boxes specified by max.

Return value:

If the user cancels the dialog, then .nil is returned. If the user clicks the okay button, then an array is returned. The array will be the same size as the input labels array. Each index of the returned array will contain .true if the corresponding check box was checked by the user or will contain .false if the check box was not checked.

Example

The following example show how to use the CheckList public routine:


  weekdays = .array~of("Monday","Tuesday","Wednesday","Thursday", -
                       "Friday","Saturday","Sunday")

  -- Monday and Tuesday will be checked, all the rest will not be checked.
  checks = .array~of(.true, .true, .false)
  checks[5] = 0
  checks[7] = 'a'

  -- The labels will be 60 dialog units wide and there will be at most 4 check
  -- boxes in a column.  (Only 7 check boxes, so 2 columns, the first with 4
  -- check boxes, the second with 3.)

  days = CheckList("Check the days", "Working Days", weekdays, checks, 60, 4)

  if days <> .Nil then do i = 1 to days~items
    if days[i] then say "Working day =" weekdays[i]
  end

::requires "oodPlain.cls"

SingleSelection Routine

The SingleSelection function provides a shortcut means to invoke a SingleSelection dialog


months = .array~of("Jan","Feb","Mar","Apr","May","Jun",  -
                   "Jul","Aug","Sep","Oct","Nov","Dec")
title = "Month You Were Born"
groupBoxLabel = "Check your birth month"
selectedRadioButton = 3

m = SingleSelection(groupBoxLabel, title, months, selectedRadioButton, , 6)
if m == "" then
    say "The user canceled the dialog."
else
    say "Born in month" m "=" months[m]

::requires "oodPlain.cls"

The parameters are described in the Init method of the SingleSelectionclass. However, instead of an input stem an array is passed into the function.