Appearance and Behavior Methods

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.

getTextSizeDlg

>>--getTextSizeDlg(--text--+-------------+--+-------------+--+---------+--)----><
                           +-,-fontname--+  +-,-fontSize--+  +-,-hwnd--+

Calculates the size, (width and height,) needed to display the given text in the specified font. The size is expressed in dialog units. To calculate the size in pixels use the getTextSizeScreen() method.

In general, dialog units are only of value in laying out the dialog controls before the underlying dialog is created. Once the underlying dialog is created, it makes more sense to work with pixels. Historically, the ooDialog documentation did not make that distinction clear. In addition, dialog units are tied directly to the font used by a dialog. Therefore, it does not make much sense for this method to be an instance method of a dialog control.

The normal use of this method would be to invoke it on a dialog object to help layout the dialog's controls prior to the creation of the underlying dialog. In this use case, the hwnd argument is meaningless. There is no handle to either the dialog window or any of its controls, prior to the underlying dialog creation. There is little point in using a window handle from some other dialog. However, to maintain compatibility with previous versions of ooDialog, the hwnd argument remains, and the method is still an instance method of a dialog control.

This method replaces the deprecated getTextSize() method. The compatibility restraint is a result of this. The compatibility restraint makes it harder than necessary to document exactly how this method works, because the behavior is different in places if the method is inovked on a dialog object or on a dialog control object.

The ooDialog programmer is strongly encouraged to only inovke this method through a dialog object. Future versions of ooDialog may remove this method from the instance methods of the DialogControl class.

Arguments:

The arguments are:

text

The string whose size is desired. If none of the optional arguments are specified then the dialog font is used to calculate the size.

However, there are some exceptions to this if the method is invoked after the underlying dialog is created.

  1. If this method is invoked through a dialog control object, then the size is calculated using the dialog control font. This usage is deprecated and the ooDialog programmer is strongly encouraged to not use this method in this manner.

  2. If the fourth, optional, hwnd argument is used, then the font of that window is used to calculate the size. Again, the ooDialog programmer is strongly encouraged to not use this method in this manner.

fontName

Optional. The name of the font to use to calculate the size needed for the string. Use This argument when the string will be displayed in a font different than the dialog font.

fontSize

Optional. The size of the font named by the fontName argument. If this argument is omitted then the defualt font size is used. (Currently the default size is 8.)

hwnd

Optional. A valid window handle. The font of this window is used to calculate the text size. This argument is always ignored when the fontName argument is specified. As per the notes above the ooDialog programmer is encouraged not to use this argument.

Return value:

The size needed for the string is returned in a Size object. The size is specified in dialog units.

Example:

This example calculates the size needed to display a message. It then uses that size to create an object that holds the co-ordinates needed to place the text in a dialog. This is used in defineDialog() to add the message text to the dialog.

      
      size = self~getTextSizeDlg(message)
      messageRect = .directory~new
      messageRect~x = 10
      messageRect~y = 10
      messageRect~cx = size~width
      messageRect~cy = size~height
      ...

    ::method defineDialog
      expose message messageRect okRect

      r = messageRect
      self~addText(r~x, r~y, r~cx, r~cy, message)

      
      

BackgroundColor

>>-aBaseDialog~BackgroundColor(--color--)---------------------><


The BackgroundColor method sets the background color of a dialog.

Arguments:

The only argument is:

color

A color-palette index specifying the background color. For information on the color numbers, refer to Definition of Terms.

Return value:

This method does not return a value.

Show

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

Argument:

The argument can be one of the following keywords, case is not significant:

NORMAL

Makes the dialog visible with its default window size. This is the default keyword if the argument is omitted.

DEFAULT

DEFAULT is an alias for NORMAL. The two keywords are functionally identical.

SHOWTOP

Shows and makes the dialog the topmost dialog.

HIDE

Makes the dialog invisible.

MIN

Minimizes the dialog.

MAX

Maximizes the dialog.

INACTIVE

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.

Example:

The following statement hides the dialog:

MyDialog~Show("HIDE")

ToTheTop

>>-aBaseDialog~ToTheTop----------------------------------------><


The ToTheTop method makes the dialog the topmost dialog.

Example:

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.

EnsureVisible

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

Arguments:

The method takes no arguments.

Return value:

This method always returns 0.

Example:

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

Minimize

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

Arguments:

The method takes no arguments.

Return value:

0

Minimizing was successful.

1

Minimizing failed.

Example:

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

Maximize

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

Arguments:

The method takes no arguments.

Return value:

0

Maximizing was successful.

1

Maximizing failed.

Example:

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

Restore

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

Arguments:

The method takes no arguments.

Return value:

0

Restoring was successful.

1

Restoring failed.

Example:

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

IsMinimized

>>-aBaseDialog~IsMinimized-------------------------------------><


The IsMinimized method is used to check if a dialog is currently minimized.

Arguments:

The method takes no arguments.

Return value:

.true

The dialog is minimized.

.false

The dialog is not minimized.

Example:

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

IsMaximized

>>-aBaseDialog~IsMaximized-------------------------------------><


The IsMaximized method is used to check if a dialog is currently maximized.

Arguments:

The method takes no arguments.

Return value:

.true

The dialog is maximized.

.false

The dialog is not maximized.

Example:

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

FocusItem

>>-aBaseDialog~FocusItem(--id--)------------------------------><


The FocusItem method sets the input focus to a particular dialog item.

Arguments:

The only argument is:

id

The ID of the dialog item to set the focus to

Return value:

This method always returns 1.

TabToNext

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

Return value:

-1

The method failed.

0

The focus was changed, but the control with the previous focus could not be determined.

Other

The handle to the control with the previous focus.

TabToPrevious

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

Return value:

-1

The method failed.

0

The focus was changed, but the control with the previous focus could not be determined.

Other

The handle to the control with the previous focus.

SetGroup

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

Arguments:

The arguments are:

id

The resource ID of the dialog control that will gain or lose the group style.

wantStyle

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.

Return value:

Negative values indicate the function failed, non-negative values indicate success.

-4 or less

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.

-3

The second argument to the method is not a boolean.

-2

There is an (internal) problem with the dialog or the dialog handle.

-1

The resource ID of the control is not correct.

0 or greater

The window style of the dialog control prior to adding or removing the group style.

SetTabStop

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

Arguments:

The arguments are:

id

The resource ID of the dialog control that will gain or lose the tabstop style.

wantStyle

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.

Return value:

Negative values indicate the function failed, non-negative values indicate success.

-4 or less

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.

-3

The second argument to the method is not a boolean.

-2

There is an (internal) problem with the dialog or the dialog handle.

-1

The resource ID of the control is not correct.

0 or greater

The window style of the dialog control prior to adding or removing the tabstop style.

EnableItem

>>-aBaseDialog~EnableItem(--id--)-----------------------------><


The EnableItem method enables the given dialog item.

Arguments:

The only argument is:

id

The ID of the item

DisableItem

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

Arguments:

The only argument is:

id

The ID of the item

HideItem

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

Arguments:

The only argument is:

id

The ID of the item

HideItemFast

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

Arguments:

The only argument is:

id

The ID of the item

ShowItem

>>-aBaseDialog~ShowItem(--id--)-------------------------------><


The ShowItem method makes the given dialog item reappear on the screen.

Arguments:

The only argument is:

id

The ID of the item

ShowItemFast

>>-aBaseDialog~ShowItemFast(--id--)---------------------------><


The ShowItemFast method shows an item without redrawing its area. It is the counterpart to the HideItemFast method.

HideWindow

>>-aBaseDialog~HideWindow(--hwnd--)---------------------------><


The HideWindow method hides a whole dialog window or a dialog item.

Arguments:

The only argument is:

hwnd

A handle to the window or dialog item. Use the GetSelf or GetItem method to get a handle.

Example:

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)

HideWindowFast

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

Arguments:

The only argument is:

hwnd

A handle to the window or dialog item

ShowWindow

>>-aBaseDialog~ShowWindow(--hwnd--)---------------------------><


The ShowWindow method shows the window or item again.

Arguments:

The only argument is:

hwnd

The handle of a window or an item

ShowWindowFast

>>-aBaseDialog~ShowWindowFast(--hwnd--)-----------------------><


The ShowWindowFast method is the counterpart to the HideWindowFast method.

SetWindowRect

>>-aBaseDialog~SetWindowRect(--hwnd--,--x--,--y--,--width--,--height-->

>--+-----------------------------+--)--------------------------------><
   |       +----------------+    |
   |       V                |    |
   +-,--"----+-NOMOVE-----+-+--"-+
             +-NOSIZE-----+
             +-HIDEWINDOW-+
             +-SHOWWINDOW-+
             +-NOREDRAW---+


The SetWindowRect method sets new coordinates for a specific window.

Arguments:

The arguments are:

hwnd

The handle to the dialog that is to be repositioned.

x, y

The new position of the upper left corner, in screen pixels.

width

The new width of the window, in screen pixels.

height

The new height of the window, in screen pixels.

showOptions

This argument can be one or more of the following keywords, separated by blanks:

NOMOVE

The upper left position of the window has not changed.

NOSIZE

The size of the window has not changed.

HIDEWINDOW

The window is to be made invisible.

SHOWWINDOW

The window is to be made visible.

NOREDRAW

The window is to be repositioned without redrawing it.

Return value:

0

Repositioning was successful.

1

Repositioning failed.

RedrawWindow

>>-aBaseDialog~RedrawWindow(--hwnd--)-------------------------><


The RedrawWindow method redraws a specific dialog.

Arguments:

The only argument is:

hwnd

The handle to the dialog that is to be redrawn.

Return value:

0

Redrawing was successful.

1

Redrawing failed.

ResizeItem

>>-aBaseDialog~ResizeItem(--id--,--width--,--height--+-------------------------+--)-><
                                                     +-,--"--+-HIDEWINDOW-+--"-+
                                                             +-SHOWWINDOW-+
                                                             +-NOREDRAW---+


The ResizeItem method changes the size of a dialog item.

Arguments:

The arguments are:

id

The ID of the dialog item you want to resize

width, height

The new size in dialog units

showOptions

This argument can be one of the following keywords:

HIDEWINDOW

Hides the item

SHOWWINDOW

Shows the item

NOREDRAW

Resizes the item without updating the display. Use the Update method to manually update the display.

Example:

The following example resizes a dialog item:

MyDialog~ResizeItem(123, 40, 30, "SHOWWINDOW")

MoveItem

>>-aBaseDialog~MoveItem(--id--,--xPos--,--yPos--+-------------------------+--)-><
                                                +-,--"--+-HIDEWINDOW-+--"-+
                                                        +-SHOWWINDOW-+
                                                        +-NOREDRAW---+


The MoveItem method moves a dialog item to another position within the dialog window.

Arguments:

The arguments are:

id

The ID of the dialog item you want to move

xPos, yPos

The new position in dialog units relative to the dialog window

showOptions

This argument can be one of the following keywords:

HIDEWINDOW

Hides the dialog

SHOWWINDOW

Shows the dialog

NOREDRAW

Moves the dialog item without updating the display. Use the Update method to manually update the display.

Center

>>-aBaseDialog~Center(--"--+-HIDEWINDOW-+--"--)---------------><
                           +-SHOWWINDOW-+
                           +-NOREDRAW---+


The Center method moves the dialog to the screen center.

Arguments:

The only argument can be one of:

HIDEWINDOW

Hides the dialog

SHOWWINDOW

Shows the dialog

NOREDRAW

Center the dialog without updating the display. Use the Update method to manually update the display.

assignWindow (deprecated)

Note: This method is deprecated and will not be supported in future vesions of ooDialog. The method will always return 0, the connection failed. To work with a dialog or dialog control object, construct the proper ooDialog object. To control a window not owned by your program use the find() method of the WindowsManger. The WindowsManager class is part of the WinSystm.cls package.

SetWindowTitle

>>-aBaseDialog~SetWindowTitle(--hwnd--,--aString--)-----------><


The SetWindowTitle method changes the title of a window.

Arguments:

The arguments are:

hwnd

The handle of the window whose title you want to change

aString

The new title text

FileViewer Example Program

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.


/* 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 = msSleep(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