| Open Object Rexx™: Windows OODialog Reference | ||
|---|---|---|
| Prev | Chapter 10. Standard Dialogs, External Functions, and Public Routines | Next |
The routines listed in this section can be used in any ooRexx 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.
Use a requires directive for the ooDialog.cls file in an ooRexx program to use any of these routines.
::requires ooDialog.cls
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.
The arguments are:
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.
You can set the last argument to:
This plays the audio file asynchronously.
Plays the audio file asynchronously and repeats it in a loop. You can stop the loop by calling Play again omitting all arguments.
The following example plays a welcoming message:
rc = play("Welcome.wav")Pops up a message box containing the specified text and an OK button.
>>-InfoDialog(--info_text--)----------------------------------><
The only argument is:
Text to be displayed in the message box.
Pops up a message box containing the specified text, an OK button, and an error symbol.
>>-ErrorDialog(--error_text--)--------------------------------><
The only argument is:
Text to be displayed in the message box.
Pops up a message box containing the specified text, a Yes button, and a No Button.
>>-AskDialog(--question--+-------------------+--)-------------><
+--, defaultbutton--+
The only argument is:
Text to be displayed in the message box.
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.
The No button has been selected.
The Yes button has been selected.
Causes a file selection dialog box to appear.
>>-FileNameDialog(--+---------+--+--------------------------------+-->
+-selfile-+ +-,--+--------+--+-------------+-+
+-parent-+ +-,--filemask-+
>--+----------------------------------------------------------------->
+-,--+------------+--+----------+--+-----------------+------------>
+-loadorsave-+ +-,--title-+ +-,--defExtension-+
>--+-----------------------------------+--)-------------------------><
>--+----------------+--+------------+--+
+-,--multiSelect-+ +-,--sepChar-+
The arguments are:
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.
Handle to the parent window.
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.
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.)
Display the File Open Dialog (default).
Display the File Save Dialog.
The window title. The default is "Open a File" or "Save File As", depending on what is specified for loadorsave.
The default extension that is added if no extension was specified. The default is TXT.
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.
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 ...
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
Returns the selected file name or an empty string when canceled. Open File dialogs with multiple selection return path file1 file2 file3 ... when the user selects multiple files.
Searches the Windows application list for a specific window and returns its handle.
>>-FindWindow(--Caption--)------------------------------------><
The only argument is:
Caption of the window that is to be searched.
Handle of the window or 0 if the window was not found.
Obtains the screen size in dialog units and in pixels
>>-ScreenSize()-----------------------------------------------><
This function takes no arguments.
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.
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.'
Queries and returns one of the system metric values The system metric values contain information that help the programmer write programs that work correctly independent of the current system. They have information on system configuration, such as the number of monitors connected, and metrics such as the size in pixels of a dialog border or the width in pixels of a scrollbar.
Good documentation on the system metrics is found in the MSDN Library under the GetSystemMetrics function. This documentation contains both the numeric value of the different indexes and information on what is returned for each index. The documentation is easy to found using a Google search of "GetSystemMetrics MSDN Library"
>>-SystemMetrics(--index--)-----------------------------------><
The only argument is:
The numeric index of the metric to query.
The return value is dependent on the index queried. Consult the MSDN library for information on the returned values.
Note: The OS will return 0 if an invalid index is used. Hoever, the return value for some indexes is also 0. The programmer will need to determine from the context if 0 is an error return or not. In addition, ooDialog will return -1 for some invalid argument values. For instance, if the string "dog" was passed in for the index argument, -1 would be returned.
Determine the number of mouse buttons and whether the mouse has a scroll wheel.
/* detectMouse.rex Simple program to detect the user's mouse. */
SM_CMOUSEBUTTONS = 43
SM_MOUSEWHEELPRESENT = 19
countMouseButtons = SystemMetrics(SM_CMOUSEBUTTONS)
haveMouseWheel = SystemMetrics(SM_MOUSEWHEELPRESENT)
if countMouseButtons == 0 then do
say 'The system does not have a mouse attached'
end
else do
say 'The mouse has' countMouseButtons 'buttons'
if haveMouseWheel == 0 then say 'There is no mouse scroll wheel.'
else say 'The mouse has a scroll wheel.'
end
return 0
::requires 'oodPlain.cls'
Sleeps for the specified number of milliseconds.
>>-MSSleep(--duration--)--------------------------------------><
The only argument is:
The time in milliseconds to sleep.
This function always returns 0.
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:
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)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
...
endThe 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
...
endA 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.
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.
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.
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
endThe 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.
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" dayThe 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.
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
endThe 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.
A shortcut function to invoke the CheckList dialog:
>>--CheckList(--message--,--title--,--labels--,-+-----------+---->
+-,--checks-+
>>--+------------------------+--)-------------------------------><
+-,--+-----+--+--------+-+
+-len-+ +-,--max-+
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.
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.
A text string for the dialog's title
An array containing the labels, in order, for each of the check boxes. The dialog will contain a check box for each label.
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.
Determines the length (in dialog units) of the check boxes and labels. If omitted, the size is calculated to fit the largest label.
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.
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.
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"
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")
m = SingleSelection("Check it","Born in",months,12, ,6)
say "Born in month" m "=" months[m]The parameters are described in the Init method of the SingleSelectionclass. However, instead of an input stem an array is passed into the function.