Chapter 6. DialogControl Class

Table of Contents
Appearance and Behavior Methods
Miscellaneous Dialog Control Methods
Connect Event Methods
Draw Methods
Conversion Methods
Scroll Methods
Mouse and Cursor Methods
Bitmap Methods
Device Context Methods
Text Methods
Graphic Methods
Graphic Drawing Methods

The DialogControl class provides methods that are common to all dialog controls. It is a generic class that serves as a superclass to all dialog control specific classes. In the graphical user interface (GUI) for the Windows operating system both dialogs and dialog controls are windows. Therefore, many of the methods of the DialogControl class are the same as the methods of the ooDialog dialog classes. These are the methods that are common to all windows, whether they are dialog windows or dialog control windows.

In the Windows GUI all windows are created with a set of window styles. Dialog control windows are created using styles that are common to all windows, (for example the visible style,) and styles specific to the dialog control itself, (for example the multi-line style of the EditControl class.) In general the styles of a control fall into three categories: Styles that can only be set when the control is created and then can not be changed afterwards. Styles that can be changed after control creation by sending messages to the control. And, styles that can be changed after the control is created by accessing the control window directly.

The ooDialog programmer chooses the window styles for dialog controls when he defines the dialog, either by using a resource editor for dialogs defined with resource scripts or binary compiled resources, or by using the Add... Methods for a user dialog. After the dialog control has been created, the individual dialog control classes provide methods to change those styles that can be changed, either by sending the proper message to the control or by accessing the control window directly.

Requires:

The DialogControl class requires the class definition file oodwin32.cls:

::requires oodwin32.cls

Attributes:

Instances of the DialogControl class have the following attributes:

FactorX

The horizontal size of one dialog unit, in pixels.

FactorY

The vertical size of one dialog unit, in pixels.

SizeX

The width of the dialog control, in dialog units, when the Rexx object that represents the control is created.

Note: The SizeX attribute is not changed by ooDialog after the object is instantiated. If the programmer resizes the dialog control manually, and requires that the value of the attribute be correct, then the programmer would need to update the value herself.

SizeY

The height of the dialog control, in dialog units, when the Rexx object that represents the control is created.

Note: The SizeY attribute is not changed by ooDialog after the object is instantiated. If the programmer resizes the dialog control manually, the programmer would also need to update the value of this attribute herself, if she requires that the value remain correct.

Methods:

Instances of the DialogControl class implement the methods listed in the following DialogControl Instance Methods table.

Table 6-1. DialogControl Instance Methods

Method......on page
AbsRect2LogRectAbsRect2LogRect
AssignFocusAssignFocus
CaptureMouseCaptureMouse
ClearClear
ClearRectClearRect
ClientToScreenClientToScreen
ConnectFKeyPressConnectFKeyPress
ConnectKeyPressConnectKeyPress
CreateBrushCreateBrush
createFontcreateFont
CreateFontExCreateFontEx
CreatePenCreatePen
Cursor_AppStartingCursor_AppStarting
Cursor_ArrowCursor_Arrow
Cursor_CrossCursor_Cross
Cursor_NoCursor_No
CursorPosCursorPos
Cursor_WaitCursor_Wait
DeleteFontDeleteFont
DeleteObjectDeleteObject
DisableDisable
DisconnectKeyPressDisconnectKeyPress
DisplayDisplay
DrawDraw
DrawAngleArcDrawAngleArc
DrawArcDrawArc
DrawLineDrawLine
DrawPieDrawPie
DrawPixelDrawPixel
EnableEnable
FillDrawingFillDrawing
FontColorFontColor
FontToDCFontToDC
ForegroundWindowForegroundWindow
FreeDCFreeDC
GetArcDirectionGetArcDirection
GetClientRectGetClientRect
GetDCGetDC
getExStyleRawgetExStyleRaw
GetFocusGetFocus
GetIDGetID
GetMouseCaptureGetMouseCapture
GetPixelGetPixel
GetPosGetPos
GetRectGetRect
GetSizeGetSize
getStyleRawgetStyleRaw
getTextSize (deprecated)getTextSize (deprecated)
getTextSizeScreengetTextSizeScrenn
GroupGroup
HasKeyPressConnectionHasKeyPressConnection
HideHide
HideFastHideFast
HScrollPosHScrollPos
isEnabledisEnabled
isMouseButtonDownisMouseButtonDown
isVisibleisVisible
LoadBitmapLoadBitmap
LogRect2AbsRectLogRect2AbsRect
MoveMove
ObjectToDCObjectToDC
OpaqueTextOpaqueText
ProcessMessageProcessMessage
RectangleRectangle
RedrawRedraw
RedrawClientRedrawClient
RedrawRectRedrawRect
ReleaseMouseCaptureReleaseMouseCapture
RemoveBitmapRemoveBitmap
ResizeResize
RestoreCursorShapeRestoreCursorShape
ScreenToClientScreenToClient
ScrollScroll
SetArcDirectionSetArcDirection
SetColorSetColor
SetCursorPosSetCursorPos
SetFocusSetFocus
SetFocusToWindowSetFocusToWindow
SetFontsetFont
SetForegroundWindowSetForegroundWindow
SetHScrollPosSetHScrollPos
SetVScrollPosSetVScrollPos
SetRectSetRect
SetTitleSetTitle
ShowShow
ShowFastShowFast
TabStopTabStop
TabToNextTabToNext
TabToPreviousTabToPrevious
TitleTitle
Title=Title=
TransparentTextTransparentText
UpdateUpdate
ValueValue
Value=Value=
VScrollPosVScrollPos
WriteWrite
WriteToButtonWriteToButton
WriteToWindowWriteToWindow

Appearance and Behavior Methods

The following methods deal with the appearance or the behavior of the dialog control. The list contains methods to get or change the size, position, visibility, behavior, etc., of dialog controls.

Show

>>-aDialogControl~Show-----------------------------------------><


The Show method makes a dialog control visible and activates it.

Example:

The following example makes the edit control NAME visible and activates it:

MyDialog~GetEditControl("NAME")~Show

Hide

>>-aDialogControl~Hide-----------------------------------------><


The Hide method makes a dialog or dialog control invisible and activates another dialog or dialog control.

Example:

MyDialog~GetEditControl("NAME")~Hide

HideFast

>>-aDialogControl~HideFast-------------------------------------><


The HideFast method marks a dialog or dialog control as invisible but does not redraw it. Send the Update method (see page Update) to the dialog or dialog control to force a redraw.

Example:

MyDialog~GetEditControl("NAME")~HideFast
...
MyDialog~Update

ShowFast

>>-aDialogControl~ShowFast-------------------------------------><


The ShowFast method marks a dialog or dialog control as visible but does not redraw it. Send the Update method (see page Update) to the dialog or dialog control to force a redraw.

Example:

MyDialog~GetEditControl("NAME")~ShowFast
...
MyDialog~Update

Display


                               +-NORMAL---+------+--+
                               |          +-FAST-+  |
>>-aDialogControl~Display(--"--+-DEFAULT--+------+--+--"--)----><
                               |          +-FAST-+  |
                               +-HIDE-----+------+--+
                               |          +-FAST-+  |
                               +-INACTIVE-----------+


The Display method displays (shows, makes visible, or invisible) a dialog control as specified.

Argument:

This argument can be one of the following keywords (case is not significant.) If no argument is given, the default keyword is NORMAL:

NORMAL

Shows (makes visible) the dialog control. Same as calling the Show method (see page Show).

DEFAULT

Default is an alias for NORMAL. The behavior is exactly the same for the two keywords.

HIDE

Hides (makes invisible) the dialog control. Same as calling the Hide method (see page Hide).

INACTIVE

Displays (shows, makes visible,) the dialog control in its current state. The active dialog remains active. When this method is invoked with the NORMAL keyword the dialog the control belongs to will be made the active window. If instead the INACTIVE keyword is used, the active window will not be changed. (Obviously, if the dialog that the control belongs to is already the active window, the INACTIVE keyword behaves exactly the same as the NORMAL keyword.

To each keyword, except the INACTIVE keyword, you can add FAST, separated by a blank, to suppress the redrawing of the dialog control.

Example:

The following statement makes a tree control in the dialog visible without redrawing it.

MyDialog~GetTreeControl(IDC_TREECONTROL_FILES)~Display("NORMAL FAST")
This is usually done when there are a number of controls to make visible at one time. The programmer would make them all visible without redrawing. Then use the Update method to repaint everything at once.

isVisible

>>--isVisible--------------------------------------------------><

Tests if the window (dialog or dialog control) is visible.

Arguments:

There are no arguments.

Return value:

Returns .true if the window is visible, otherwise .false

Example:

if \ self~isVisible then self~show

Enable

>>-aDialogControl~Enable---------------------------------------><


The Enable method enables a dialog or dialog control to accept user interaction.

Example:

MyDialog~GetEditControl("Name")~Enable

Disable

>>-aDialogControl~Disable--------------------------------------><


The Disable method disables a dialog or dialog control.

Example:

MyDialog~GetEditControl("Name")~Disable

isEnabled

>>--isEnabled--------------------------------------------------><

Tests if the window (dialog or dialog control) is enabled

Arguments:

There are no arguments.

Return value:

Returns .true if the window is enabled, otherwise .false

Example:

::method toggleState private
listView = self~getListControl(IDC_LV_NAMES)
if listView~isEnabled then
   listView~disable
else
   listView~enable

Group

>>-aDialogControl~Group(--+-----------+--)---------------------><
                          +-wantStyle-+

Add or remove the group style for this 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 only argument is

wantStyle

A boolean (.true or .false) to indicate whether the 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 optional argument to the method is not a boolean.

-2

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

-1

There is an (internal) problem with the resource ID of the control.

0 or greater

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

TabStop

>>-aDialogControl~TabStop(--+-----------+--)--------------------><
                            +-wantStyle-+

Add or remove the tab stop style for the 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 only argument is:

wantStyle

A boolean (.true or .false) to indicate whether the 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

There is an (internal) problem with the resource ID of the control.

0 or greater

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

Resize

>>-aDialogControl~Resize(--width--,--height--+-----------------------------+--)-><
                                             |       +----------------+    |
                                             |       V                |    |
                                             +-,--"----+-HIDEWINDOW-+-+--"-+
                                                       +-SHOWWINDOW-+
                                                       +-NOREDRAW---+


The Resize method resizes a dialog or dialog control.

Arguments:

The arguments are:

width

The new width of the dialog or dialog control, in dialog units.

height

The new height of the dialog or dialog control, in dialog units.

showOptions

One or more of the following keywords, separated by blanks:

HIDEWINDOW

The dialog or dialog control is to be made invisible.

SHOWWINDOW

The dialog or dialog control is to be made visible.

NOREDRAW

The dialog or dialog control is to be repositioned without redrawing it.

Return value:

0

Resizing was successful.

1

Resizing failed.

Example:

The following example resizes the tree view control FILES almost to the size of the window and displays the new size:

obj = MyDialog~GetTreeControl("FILES")
if obj = .Nil then return
obj~Resize(MyDialog~SizeX -10, MyDialog~SizeY -20)
parse value obj~GetSize with width height
say "New width of window is" width "and new height is" height

Move

>>-aDialogControl~Move(--xPos--,--yPos--+----------------------------+--)-><
                                        |      +----------------+    |
                                        |      V                |    |
                                        +-,-"----+-HIDEWINDOW-+-+--"-+
                                                 +-SHOWWINDOW-+
                                                 +-NOREDRAW---+


The Move method moves the associated dialog or dialog control to the specified position.

Arguments:

The arguments are:

xPos

The new horizontal position of the dialog or dialog control, in dialog units.

yPos

The new vertical position of the dialog or dialog control, in dialog units.

showOptions

One or more of the following keywords, separated by blanks:

HIDEWINDOW

The dialog or dialog control is to be made invisible.

SHOWWINDOW

The dialog or dialog control is to be made visible.

NOREDRAW

The dialog or dialog control is to be repositioned without redrawing it.

Return value:

0

Moving was successful.

1

Moving failed.

Example:

The following example repositions the tree view control FILES to the upper left corner of the window and displays the new position:

obj = MyDialog~GetTreeControl("FILES")
if obj = .Nil then return
obj~Move(1,1)
parse value obj~GetPos with x y
say "New horizontal position of window is" x "and new vertical position is" y

SetForegroundWindow

>>-aDialogControl~SetForegroundWindow(--hwnd--)---------------------------><


The SetForegroundWindow method changes the foreground window to the window specified. The new window must be a top-level window or a dialog window. You can not make a dialog control window the foreground window.

Arguments:

The only argument is:

hwnd

The handle to the window that is to become the foreground window.

Return value:

The handle to the previous foreground window, or 0 if this method failed.

Example:

This example makes another dialog the foreground window and returns the window handle of the current foreground window to the caller, or returns -1 if there was an error:

::method switchToReportDlg
  expose reportDlg
  currentHwnd = self~setForeGroundwindow(reportDlg~dlgHandle)
  if currentHwnd == 0 then return -1  -- Report an error
  return currentHwnd

ForegroundWindow

>>-aDialogControl~ForegroundWindow-----------------------------><


The ForegroundWindow method returns the handle to the current foreground window.

Return value:

The handle to the foreground window, or 0 if this method failed.

GetID

>>-aDialogControl~GetID----------------------------------------><


The GetID method retrieves the identification number of the associated dialog or dialog control.

Return value:

The numeric ID.

Example:

The following example displays 1 in most cases:

say MyDialog~GetButtonControl("IDOK")~GetID

getStyleRaw

>>--getStyleRaw---------------------------------><

The getStyleRaw method retrieves the window style flags of the dialog or dialog control. The flags are returned in their numeric format. This allows the programmer to determine the current style of any dialog or control. However, the programmer needs to be able to look up the numeric value of the window style flags to make use of this functionality. This can be done using the Windows documentation and the Platform SDK.

Arguments:

There are no arguments.

Return value:

The numeric value of the window style flags.

Example:

The following example gets the style flags for a tree control and then checks to see if drag and drop is enabled and if label editing is enabled.

The value of the style flags has the potential of being larger than can be accommodated by the default numeric digits. Use numeric digits 11 if the returned value needs to be manipulated, for instance to use d2x on the value.

Note: It is not necessary to convert the style value in the example to its hexadecimal string representation before using it as an argument in the and() method. That is just done in the example for display purposes.

  ...

  numeric digits 11
  TVS_DISABLEDRAGDROP = "0x0010"
  TVS_EDITLABELS      = "0x0008"

  treeControl = self~getTreeControl(IDC_TREE)
  style = treeControl~getStyleRaw
  style = "0x" || style~d2x~right(8, '0')

  if .DlgUtil~and( style, TVS_DISABLEDRAGDROP ) <> 0 then str1 = 'disabled'
  else str1 = 'enabled'

  if .DlgUtil~and( style, TVS_EDITLABELS ) <> 0 then str2 = 'enabled'
  else str2 = 'disabled'

  say 'Tree-view Control styles'
  say '  Raw style:    ' style
  say '  Drag and drop:' str1
  say '  Edit labels:  ' str2

/* Output could be: */

Tree-view Control styles
  Raw style:     0x5000002F
  Drag and drop: enabled
  Edit labels:   enabled

getExStyleRaw

>>--getExStyleRaw---------------------------------><

The getExStyleRaw method retrieves the extended window style flags of the dialog or dialog control. The flags are returned in their numeric format. This function is very similar to the getStyleRaw() method, allowing the programmer to get the extended window flags. The numeric value of the extended style flags can be looked up using the Windows documentation and the Platform SDK.

Arguments:

There are no arguments.

Return value:

The numeric value of the window extended style flags.

Example:

The following example gets the extended style flags for a list-view control and displays them to the screen in hexadecimal format. The value displayed in the example indicates the following styles.

WS_EX_NOPARENTNOTIFY == 0x00000004
WS_EX_CLIENTEDGE == 0x00000200


::method printExStyle private
  expose list

  val = list~getExStyleRaw

  numeric digits 11
  val = '0x' || val~d2x~right(8, 0)
  say "List control extended style flag:"
  say " " val
  say

/* Output could be: */

List control extended style flags:
  0x00000204

GetRect

>>-aDialogControl~GetRect--------------------------------------><


Retrieves the dimensions of the rectangle surrounding the associated dialog or dialog control. The coordinates are relative to the upper left corner of the screen and are specified in screen pixels. The order is: left, top, right, bottom; where 'left' and 'top' are the x and y coordinates of the upper left-hand corner of the rectangle, and 'right' and 'bottom' are the coordinates of the bottom right-hand corner.

Return value:

The coordinates of the dialog or dialog control, separated by blanks.

Example:

The following example calculates the width and height of an entry line:

parse value MyDialog~GetEditControl("Name")~GetRect with left top,
right bottom
width = right - left
height = bottom - top

SetRect

>>-aDialogControl~SetRect(--x--,--y--,--width--,--height-->

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

The SetRect method sets new coordinates for the associated dialog or dialog control.

Arguments:

The arguments are:

x,y

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

width

The new width of the dialog or dialog control, in screen pixels.

height

The new height of the dialog or dialog control, in screen pixels.

showOptions

One or more of the following keywords, separated by blanks:

NOMOVE

The upper left position of the dialog or dialog control is not changed.

NOSIZE

The size of the dialog or dialog control is not changed.

HIDEWINDOW

The dialog or dialog control is to be made invisible.

SHOWWINDOW

The dialog or dialog control is to be made visible.

NOREDRAW

The dialog or dialog control is to be repositioned without redrawing it.

Return value:

0

Repositioning was successful.

1

Repositioning failed.

GetClientRect

>>-aDialogControl~GetClientRect(--+------+--)------------------><
                                  +-hwnd-+


The GetClientRect method returns the client rectangle of a dialog or dialog control in screen pixels. The client coordinates specify the upper left and lower right corners of the client area. Because the client coordinates are relative to the upper left corner of the client area of a dialog or dialog control, the coordinates of the upper left corner are (0,0).

Arguments:

The only argument is:

hwnd

The handle to a dialog or dialog control. If this argument is omitted, the dimensions of the associated dialog or dialog control are returned.

Return value:

The client rectangle in the format "left top right bottom", separated by blanks.

GetSize

>>-aDialogControl~GetSize--------------------------------------><


The GetSize method returns the width and height of the dialog or dialog control, in dialog units.

Return value:

The width and height, separated by a blank.

Example:

For an example, see Resize.

AssignFocus

>>-aDialogControl~AssignFocus----------------------------------><


The AssignFocus method sets the input focus to the associated dialog control.

GetFocus

>>-aDialogControl~GetFocus-------------------------------------><


The GetFocus method returns the handle to the dialog control that currently has the input focus.

Return value:

The handle to the dialog control that has the input focus, or 0 if this method failed.

SetFocus

>>-aDialogControl~SetFocus(--hwnd--)---------------------------><


The SetFocus method sets the input focus to a dialog control and returns the handle of the control that previously had the focus.

Arguments:

The only argument is:

hwnd

The handle to the dialog control that is to receive the input focus.

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.

SetFocusToWindow

>>-aDialogControl~SetFocusToWindow(--hwnd--)-------------------><


The SetFocusToWindow method moves the input focus to another top-level window or dialog. This has the effect of bringing that window to the foreground. This method returns a handle to the dialog control that previously had the input focus.

Arguments:

The only argument is:

hwnd

The handle to the top-level window or dialog that is to receive the input focus.

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.

SetColor

>>-aDialogControl~SetColor(--background--,--foreground--)------><


The SetColor method sets the background and foreground colors of the dialog control.

Arguments:

The arguments are:

background

The color number of the background color.

foreground

The color number of the foreground color.

Return value:

0

The color has been assigned.

1

The selected color was already assigned.

Example:

The following example sets the background color of list box FILES to blue:

MyDialog~GetListBox("FILES")~SetColor(4, 15)

Update

>>-aDialogControl~Update---------------------------------------><


The Update method makes the contents of the dialog or dialog control invalid and therefore forces it to be updated.

Title

>>-aDialogControl~Title----------------------------------------><


The Title method retrieves the title of the dialog or dialog control.

Return value:

0

The title was retrieved.

1

Retrieving the title failed.

Title=

>>-aDialogControl~Title=--new_title----------------------------><


The Title= method sets the title of the dialog or dialog control.

Arguments:

The only argument is:

new_text

A text string that is to be used as the title or text of the dialog or dialog control.

Return value:

0

The title was set.

1

Setting the title failed.

Example:

The following example changes the label of radio button CHOICE2:

MyDialog~GetRadioControl("CHOICE2")~Title="&Object Rexx (preferred choice)"
MyDialog~Redraw

SetTitle

>>-aDialogControl~SetTitle(--new_title--)----------------------><


The SetTitle method sets the title of the dialog or dialog control. It is equal to Title=.