The methods listed in this section are related to the appearance or the behavior of the dialog or its controls. The section contains methods related to size, position, visibility, and title.
Some of the methods come in two flavors, normal (for example, ShowWindow and fast (for example, ShowWindowFast). The fast extension indicates that the method does not redraw the control or window immediately. After modifying several items, invoke the Update method (see page Update) to redraw the dialog.
>>-aBaseDialog~BackgroundColor(--color--)---------------------><
The BackgroundColor method sets the background color of a dialog.
The only argument is:
A color-palette index specifying the background color. For information on the color numbers, refer to Definition of Terms.
This method does not return a value.
+-NORMAL---+
>>-aBaseDialog~Show(--"--+----------+--"--)--------------------><
+-DEFAULT--+
+-SHOWTOP--+
+-HIDE-----+
+-MIN------+
+-MAX------+
+-INACTIVE-+
The Show method shows the dialog. It is called by Execute or ExecuteAsync methods to initially display the dialog. Once the dialog has been initially shown, the programmer can use the Show to change the appearance of the dialog. For instance the dialog can be hidden, maximized, minimized, etc..
The argument can be one of the following keywords, case is not significant:
Makes the dialog visible with its default window size. This is the default keyword if the argument is omitted.
DEFAULT is an alias for NORMAL. The two keywords are functionally identical.
Shows and makes the dialog the topmost dialog.
Makes the dialog invisible.
Minimizes the dialog.
Maximizes the dialog.
Shows the dialog without changing the active window. When the Normal keyword is used, the dialog is shown and becomes the active window. Using the INACTIVE keyword allows the dialog to be shown and let another window remain active.
The following statement hides the dialog:
MyDialog~Show("HIDE")>>-aBaseDialog~ToTheTop----------------------------------------><
The ToTheTop method makes the dialog the topmost dialog.
The following example uses the ToTheTop method to make the user aware of an alarm event:
aDialog = .MyDialog~new
msg = .Message~new(aDialog, "Remind")
a = .Alarm~new("17:30:00", msg)
::class MyDialog subclass UserDialog
.
.
.
::method Remind
self~SetStaticText(102, "Don't forget to go home!")
self~ToTheTop
Note: The Message and Alarm classes are built-in classes of Object Rexx. See the Open Object Rexx: Reference for further information.
>>-aBaseDialog~EnsureVisible-----------------------------------><
The EnsureVisible method causes the dialog to reposition itself so that the entire dialog is on the visible screen. If the entire dialog is already on the visible screen then no action is taken.
This is useful in a number of situations. It allows the programmer to move or resize the dialog and not have to worry that the dialog is off the screen. After finishing the move or resizing, the programmer can invoke the EnsureVisible method and know that the dialog is entirely on the screen.
The method takes no arguments.
This method always returns 0.
The following example reads in the previous size and position of the dialog and then opens the dialog in the position that the user had closed it. If the INI file is corrupted, or had been accidently edited, or a number of other things, it is possible that sizing and positioning the dialog using the values from the INI file will place the dialog of the screen. Invoking EnsureVisible will cause the dialog to reposition itself so that it is completely on the screen, but only if needed. If the dialog is already completely on the screen, then no action is taken.
if \.useDefault then
do
-- Read oorexxtry.ini position & size the dialog based on its values
handle = self~getSelf()
k1 = SysIni('oorexxtry.ini','oorexxtry','k1')
k2 = SysIni('oorexxtry.ini','oorexxtry','k2')
k3 = SysIni('oorexxtry.ini','oorexxtry','k3')
k4 = SysIni('oorexxtry.ini','oorexxtry','k4')
if k1 = 'ERROR:' | k2 = 'ERROR:' | k3 = 'ERROR:' | k4 = 'ERROR:' then
nop -- First execution will not find the ini file
else
do
self~setWindowRect(handle,k1,k2,k3-k1,k4-k2)
self~ensureVisible
end
end
>>-aBaseDialog~Minimize----------------------------------------><
The Minimize method minimizes the dialog to the taskbar. This is the identical to the user clicking the minimize button on the dialog window. This method will minimize the dialog even if it does not have the MINIMIZEBOX style when it is created.
This is a convenience method. It is functionally equivalent to using the Show method with the MIN keyword.
The method takes no arguments.
Minimizing was successful.
Minimizing failed.
This example creates a secondary dialog to display the contents of a file. The secondary dialog is show full screen (maximized.) At the same time the parent dialog is minimized to the taskbar. The complete program listing is available (see the File Viewer example.)
::method onView
expose viewDlg editCntrl
fileName = editCntrl~getText
viewDlg = .Viewer~new( , "fileView.h", self, fileName)
if viewDlg~initCode = 0 then do
self~disableItem(IDC_PB_VIEW)
viewDlg~create(30, 30, 170, 180, "Viewer", "MAXIMIZEBOX MINIMIZEBOX")
viewDlg~popUpAsChild(self, "HIDE", , IDI_DLG_APPICON)
-- The underlying Windows dialog has to be created before it can be maximized.
j = SysSleep(.1)
viewDlg~maximize
self~minimize
end
>>-aBaseDialog~Maximize----------------------------------------><
The Maximize method maximizes the dialog on the screen. This is the identical to the user clicking the maximize button on the dialog window. This method will maximize the dialog even if it does not have the MAXIMIZEBOX style when it is created.
This is a convenience method. It is functionally equivalent to using the Show method with the MAX keyword.
The method takes no arguments.
Maximizing was successful.
Maximizing failed.
The following code snippet minimizes the dialog to the taskbar. It is used in the FileViewer example. The complete program listing is available (see the File Viewer example.)
::method onView
expose viewDlg editCntrl
...
if viewDlg~initCode = 0 then do
...
viewDlg~maximize
self~minimize
end
>>-aBaseDialog~Restore-----------------------------------------><
The Restore method restores a minimized or maximized dialog to its original position. This is the identical to the user taking action to restore the dialog window. The programmer can use this method to restore a dialog window that he previously minimized or maximized.
This is a convenience method. It is functionally equivalent to using the Show method with the RESTORE keyword.
The method takes no arguments.
Restoring was successful.
Restoring failed.
The following example checks if the parent dialog is minimized and, if it is, the Restore method is used to show the dialog in the size and position it was prior to being minimized. The complete program listing for this code snippet is available (see the File Viewer example.)
::method cancel expose parent parent~enableItem(IDC_PB_VIEW) if parent~isMinimized then parent~restore return self~cancel:super
>>-aBaseDialog~IsMinimized-------------------------------------><
The IsMinimized method is used to check if a dialog is currently minimized.
The method takes no arguments.
The dialog is minimized.
The dialog is not minimized.
The following example checks if the parent dialog is minimized and, if it is, the Restore method is used to show the dialog in the size and position it was prior to being minimized. The complete program listing that this code snippet comes from is available (see the File Viewer example.)
::method cancel expose parent parent~enableItem(IDC_PB_VIEW) if parent~isMinimized then parent~restore return self~cancel:super
>>-aBaseDialog~IsMaximized-------------------------------------><
The IsMaximized method is used to check if a dialog is currently maximized.
The method takes no arguments.
The dialog is maximized.
The dialog is not maximized.
The following code snippet would check if the dialog is maximized and, if it is, restore it to the position and size it was prior to being maximized.
if self~isMaximized then self~restore
>>-aBaseDialog~FocusItem(--id--)------------------------------><
The FocusItem method sets the input focus to a particular dialog item.
The only argument is:
The ID of the dialog item to set the focus to
This method always returns 1.
>>-aBaseDialog~TabToNext--------------------------------------><
The TabToNext method sets the input focus to the next dialog control with a tab stop. This performs the same action as if the user pressed the tab key in the dialog. Like many of the other methods, TabToNext is a method of both a BaseDialog and a DialogControl.
The method failed.
The focus was changed, but the control with the previous focus could not be determined.
The handle to the control with the previous focus.
>>-aBaseDialog~TabToPrevious----------------------------------><
This method is the reverse of TabToNext and sets the input focus to the previous dialog control with a tab stop. This performs the same action as if the user pressed the shift-tab key in the dialog. TabToPrevious is a method of both a BaseDialog and a DialogControl.
The method failed.
The focus was changed, but the control with the previous focus could not be determined.
The handle to the control with the previous focus.
>>-aBaseDialog~SetGroup(--id--,--+-----------+--)---------------><
+-wantStyle-+
Add or remove the group style for the specified control. The group style controls how the user can navigate through the dialog using the keyboard. For most dialogs this does not change while the dialog is executing. However, in some dialogs the programmer may want to change the navigation depending on the options the user selects.
The arguments are:
The resource ID of the dialog control that will gain or lose the group style.
A boolean (.true or .false) to indicate whether the dialog control should have or not have the group style. True (the default) indicates the control should have the group style and false indicates the control should not have the style.
Negative values indicate the function failed, non-negative values indicate success.
The value is the negated Operating System Error code. The absolute value of the return can be used to look up the error reason in the Windows documentation.
The second argument to the method is not a boolean.
There is an (internal) problem with the dialog or the dialog handle.
The resource ID of the control is not correct.
The window style of the dialog control prior to adding or removing the group style.
>>-aBaseDialog~SetTabStop(--id--,--+-----------+--)-------------><
+-wantStyle-+
Add or remove the tab stop style for the specified control. When a control has the tabstop style, the user can set the focus to the control by using the tab key. When a control does not have this style, the tab key will skip over the control. Adding or removing this style during the execution of a dialog allows the programmer to alter how the user navigates through the dialog controls.
The arguments are:
The resource ID of the dialog control that will gain or lose the tabstop style.
A boolean (.true or .false) to indicate whether the dialog control should have or not have the tabstop style. True (the default) indicates the control should have the tabstop style and false indicates the control should not have the style.
Negative values indicate the function failed, non-negative values indicate success.
The value is the negated Operating System Error code. The absolute value of the return can be used to look up the error reason in the Windows documentation.
The second argument to the method is not a boolean.
There is an (internal) problem with the dialog or the dialog handle.
The resource ID of the control is not correct.
The window style of the dialog control prior to adding or removing the tabstop style.
>>-aBaseDialog~EnableItem(--id--)-----------------------------><
The EnableItem method enables the given dialog item.
The only argument is:
The ID of the item
>>-aBaseDialog~DisableItem(--id--)----------------------------><
The DisableItem method disables the given dialog item. A disabled dialog item is usually indicated by a gray instead of a black title or text; it cannot be changed by the user.
The only argument is:
The ID of the item
>>-aBaseDialog~HideItem(--id--)-------------------------------><
The HideItem method makes the given item disappear from the screen and thus unavailable to the user. In fact, the item is still in the dialog and you can transfer its data.
The only argument is:
The ID of the item
>>-aBaseDialog~HideItemFast(--id--)---------------------------><
The HideItemFast method hides an item without redrawing its area. It is similar to the HideItem method, but it is faster because the item's area is not redrawn. The HideItemFast method is used when more than one item state is modified. After the operations, you can manually redraw the dialog window, using the Update method.
The only argument is:
The ID of the item
>>-aBaseDialog~ShowItem(--id--)-------------------------------><
The ShowItem method makes the given dialog item reappear on the screen.
The only argument is:
The ID of the item
>>-aBaseDialog~ShowItemFast(--id--)---------------------------><
The ShowItemFast method shows an item without redrawing its area. It is the counterpart to the HideItemFast method.
>>-aBaseDialog~HideWindow(--hwnd--)---------------------------><
The HideWindow method hides a whole dialog window or a dialog item.
The only argument is:
The following example gets the window handle of the top dialog (which is not necessarily the executing dialog, see the Get method) and hides the whole dialog:
hwnd = MyDialog~Get MyDialog~HideWindow(hwnd)
>>-aBaseDialog~HideWindowFast(--hwnd--)-----------------------><
The HideWindowFast method is similar to the HideWindow method, but it is faster because the window's or item's area is not redrawn. The HideWindowFast method is used when more than one state is modified. After the operations, you can manually redraw the dialog window, using the Update method.
The only argument is:
A handle to the window or dialog item
>>-aBaseDialog~ShowWindow(--hwnd--)---------------------------><
The ShowWindow method shows the window or item again.
The only argument is:
The handle of a window or an item
>>-aBaseDialog~ShowWindowFast(--hwnd--)-----------------------><
The ShowWindowFast method is the counterpart to the HideWindowFast method.
>>-aBaseDialog~SetWindowRect(--hwnd--,--x--,--y--,--width--,--height-->
>--+-----------------------------+--)--------------------------------><
| +----------------+ |
| V | |
+-,--"----+-NOMOVE-----+-+--"-+
+-NOSIZE-----+
+-HIDEWINDOW-+
+-SHOWWINDOW-+
+-NOREDRAW---+
The SetWindowRect method sets new coordinates for a specific window.
The arguments are:
The handle to the dialog that is to be repositioned.
The new position of the upper left corner, in screen pixels.
The new width of the window, in screen pixels.
The new height of the window, in screen pixels.
This argument can be one or more of the following keywords, separated by blanks:
The upper left position of the window has not changed.
The size of the window has not changed.
The window is to be made invisible.
The window is to be made visible.
The window is to be repositioned without redrawing it.
Repositioning was successful.
Repositioning failed.
>>-aBaseDialog~RedrawWindow(--hwnd--)-------------------------><
The RedrawWindow method redraws a specific dialog.
The only argument is:
The handle to the dialog that is to be redrawn.
Redrawing was successful.
Redrawing failed.
>>-aBaseDialog~ResizeItem(--id--,--width--,--height--+-------------------------+--)-><
+-,--"--+-HIDEWINDOW-+--"-+
+-SHOWWINDOW-+
+-NOREDRAW---+
The ResizeItem method changes the size of a dialog item.
The arguments are:
The ID of the dialog item you want to resize
The new size in dialog units
This argument can be one of the following keywords:
Hides the item
Shows the item
Resizes the item without updating the display. Use the Update method to manually update the display.
The following example resizes a dialog item:
MyDialog~ResizeItem(123, 40, 30, "SHOWWINDOW")
>>-aBaseDialog~MoveItem(--id--,--xPos--,--yPos--+-------------------------+--)-><
+-,--"--+-HIDEWINDOW-+--"-+
+-SHOWWINDOW-+
+-NOREDRAW---+
The MoveItem method moves a dialog item to another position within the dialog window.
The arguments are:
The ID of the dialog item you want to move
The new position in dialog units relative to the dialog window
This argument can be one of the following keywords:
Hides the dialog
Shows the dialog
Moves the dialog item without updating the display. Use the Update method to manually update the display.
>>-aBaseDialog~Center(--"--+-HIDEWINDOW-+--"--)---------------><
+-SHOWWINDOW-+
+-NOREDRAW---+
The Center method moves the dialog to the screen center.
The only argument can be one of:
Hides the dialog
Shows the dialog
Center the dialog without updating the display. Use the Update method to manually update the display.
>>-aBaseDialog~SetWindowTitle(--hwnd--,--aString--)-----------><
The SetWindowTitle method changes the title of a window.
The arguments are:
The handle of the window whose title you want to change
The new title text
The FileViewer program is a complete working program that uses many of the methods of the base dialog. Portions of this program are presented as examples in the documentation for these methods. The complete program is shown here as a reference to how the code snippets all fit together.
The documentation for the individual methods used in the program has additional commentary that will help in understanding how the program works.
Init: This program uses a header file, fileView.h to define symbolic IDs for the dialog controls. The name of the file is one of the arguments used to create a new instance of a dialog object. (As in all ooRexx classes, the arguments used in new are passed on to the init method of the class.)
Execute: Two dialogs are created in the example. The first dialog allows the user to enter the name of a file to view. Then the file itself is displayed in a second dialog. Each dialog uses a different application icon. The Execute method documentation has more detail on the application icon.
InitDialog This method is called after the underlying Windows dialog has been created, but before it is shown on the screen. In the viewer dialog the Init method is overridden and the text of the read-only multi-line edit control is set to the contents of the file. In both dialogs, this method is used to get and save a reference to the edit control of the dialog.
DisableItem: When the user clicks the "View File" button, the button is disabled until the user is finished viewing the file. When a button is disabled it can not be clicked by the user.
EnableItem: When the user closes the secondary viewer dialog, the "View File" button is enabled so the user can choose to view another file.
PopupAsChild: The viewer dialog is executed using this method so that both dialogs run independently, both dialogs stay enabled. The HIDE keyword is used for the show argument. This creates the dialog as invisible and prevents unnecessary screen flicker.
Maximize: Note that there is a 100 millisecond sleep right before the Maximize method is invoked. This allows Windows to finish creating the dialog. The InitDialog method will have already finished executing and the contents of the file are loaded into the multi-line edit control. Then, Maximize resizes the dialog to take up the whole screen and shows it. The dialog appears on the user's screen, with the file displayed, in one screen drawing. This reduces the flicker on the screen.
Minimize: When the viewer dialog is maximized, the main dialog is minimized to the task bar.
InitAutoDetection: Because the contents of the file are loaded into the multi-line edit control during InitDialog, auto detection must be turned off. Otherwise, after InitDialog finishes executing, auto detection would set the empty string as the text for the control. The program overrides this method to turn auto detection off.
NoAutoDetection: Used in turning auto detection off.
ConnectResize: When the viewer dialog is resized, the onSize method is invoked. The size of the multi-line edit control is then changed so it completely takes up the client area of the dialog. (The client area of a window is where all the child windows are drawn. In this case the edit control is the only child window.) Since the dialog is not resizeable by the user (it does not have a sizing border) the only time the size can change is when the dialog is maximized, minimized, or restored.
HideItem: The edit control in the viewer dialog is created invisible. Again, this helps reduce flicker.
GetItem: The window handle of the edit control is obtained by this method ...
GetClientRect: ... then the size of the client area of the viewer dialog is obtained using this method. Then ..
SetWindowRect: ... the size of the edit control window is set using to the size of the dialog's client area.
ShowItem: The ShowItem method is used to make the edit control visible when the dialog is initially shown.
IsMinimized: When the viewer dialog is closed, this method checks to see if the main dialog is still minimized. Since the dialogs run independently the user may have already restored this dialog.
Restore: If the main dialog is still minimized, then this method restores it to its normal position.
/* fileView.h Simple symbolic ID definitions */
#define IDD_DIALOG1 100
#define IDC_ST_TYPE 105
#define IDC_ENTRYLINE 106
#define IDC_MULTILINE 107
#define IDC_PB_VIEW 111
/* FileViewer.rex Simple Dialog to view files full screen */
dlg = .FileView~new( , "fileView.h")
if dlg~initCode = 0 then do
dlg~createCenter(170, 90, "The File Viewer Dialog", "VISIBLE MAXIMIZEBOX MINIMIZEBOX")
dlg~Execute("SHOWTOP", IDI_DLG_OOREXX)
dlg~Deinstall
end
-- End of entry point.
::requires "OODWin32.cls"
::class FileView subclass UserDialog inherit AdvancedControls
::method defineDialog
self~addText(10, 25, 150, 10, " Enter the name of a file to view:", "", IDC_ST_TYPE)
self~addEntryLine(IDC_ENTRYLINE, , 10, 35, 150, 10, "AUTOSCROLLH")
-- When the view button is pushed, another dialog will show the file.
self~addButton(IDC_PB_VIEW, 10, 55, 35, 15, "View File", onView, "DEFAULT GROUP")
self~addButton(IDOK, 130, 55, 35, 15, "Quit")
::method initDialog
expose editCntrl
editCntrl = self~getEditControl(IDC_ENTRYLINE)
::method onView
expose viewDlg editCntrl
fileName = editCntrl~getText
viewDlg = .Viewer~new( , "fileView.h", self, fileName)
if viewDlg~initCode = 0 then do
self~disableItem(IDC_PB_VIEW)
viewDlg~create(30, 30, 170, 180, "Viewer", "MAXIMIZEBOX MINIMIZEBOX")
viewDlg~popUpAsChild(self, "HIDE", , IDI_DLG_APPICON)
-- The underlying Windows dialog has to be created before it can be maximized.
j = SleepMS(100)
viewDlg~maximize
self~minimize
end
::class 'Viewer' subclass UserDialog inherit AdvancedControls
::method init
expose parent filename
use arg data, header, parent, fileName
forward class (super)
::method initAutoDetection
self~noAutoDetection
::method defineDialog
expose wasMinimized
wasMinimized = .false
style = "VSCROLL HSCROLL MULTILINE READONLY"
self~addEntryLine(IDC_MULTILINE, "cEntry", 0, 0, 170, 180, style)
self~connectResize("onSize")
::method initDialog
expose editControl fileName isHidden
self~hideItem(IDC_MULTILINE)
isHidden = .true
editControl = self~getEditControl(IDC_MULTILINE)
fObj = .stream~new(fileName)
text = fObj~charin(1, fObj~chars)
fObj~close
if text == "" then text = " No file "
editControl~setText(text)
::method onSize
expose wasMinimized
use arg sizeEvent sizeInfo
if sizeEvent = 1 then wasMinimized = .true
if sizeEvent = 0 | sizeEvent = 2 then do
if \ wasMinimized then self~resizeEditControl
wasMinimized = .false
end
::method resizeEditControl
expose editControl isHidden
hWnd = self~getItem(IDC_MULTILINE)
parse value self~getClientRect with wx wy wcx wcy
self~setWindowRect(hWnd, 0, 0, wcx, wcy)
if isHidden then do
self~showItem(IDC_MULTIINE)
isHidden = .false
end
::method cancel
expose parent
parent~enableItem(IDC_PB_VIEW)
if parent~isMinimized then parent~restore
return self~cancel:super