Chapter 14. Button Controls

Table of Contents
ButtonControl Class
RadioButton Class
CheckBox Class
GroupBox Class
AnimatedButton Class

In Windows the Button control has a number of different types or kinds. Most button types have a number of different styles. The style of a button effects its behavior and appearance. The appearance of a button is usually maintained by the operating system in combination with the programmer.

In general people refer to "pushing," "clicking," or "checking" a button. The mouse is used to click a button and the enter key to push a button. Checking a button can be done with the mouse or the keyboard. Buttons have a state, the most common of which are checked, unchecked, pushed, and focused.

The five kinds of buttons are:

ooDialog provides these classes to allow the programmer to interface with the underlying button controls:

Table 14-1. ooDialog Button Control Classes

Button Control TypeooDialog Class
Push ButtonButtonControl Class
Check Box ButtonCheckBox Class
Raido ButtonRadioButton Class
Group BoxGroupBox Class
Owner Drawn ButtonAnimatedButton Class, ButtonControl Class

ButtonControl Class

Push buttons are rectangular controls containing a label (a text string,) an icon, or a bitmap defined by the programmer. The label or image indicates what the button does when it is pushed or clicked. A push button is either standard or default.

Standard push buttons usually start an operation. The button will receive the keyboard focus when the user clicks it. On the other hand, the default push button will indicate the default choice, which would normally be the most common choice. The default button does not have to have the input focus to be selected. It is selected by the user pressing the ENTER key when the dialog box has the focus, no matter which control currently has the input focus.

The ButtonControl class provides methods to query and modify push button controls. In addition, the class has methods that allow the Rexx programmer to partially implement owner drawn buttons using bitmaps.

Requires:

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

::requires "oodwin32.cls"

Subclass of:

The button control class is a subclass of the DialogControl class and therefore inherits all methods of that class.

Mixin Class Inherits:

The button control class inherits from the following mixin classes, (indirectly through the DialogControl class.)

The WindowBase

The WindowExtensions

Instantiation:

Use the getButtonControl() method to retrieve an object of the button control class.

Dynamic Definition:

To dynamically define a button control in a UserDialog class, use one of the add button methods described in the Add Button Control section. That section also describes methods for adding radio buttons, check boxes, etc.. Only the addButton... methods are used to add a ButtonControl object.

Event Notification

The programmer can use these methods to recieve notifications of button control events: the connectButton() method, or the connectButtonNotify() method.

Methods:

The ButtonControl class implements the class and instance methods listed in the following table.

Table 14-2. ButtonControl Instance Methods

Method......on page
changeBitmapchangeBitmap
clickclick
dimBitmapdimBitmap
displaceBitmapdisplaceBitmap
drawBitmapdrawBitmap
getBitmapSizeXgetBitmapSizeX
getBitmapSizeYgetBitmapSizeY
getBmpDisplacementgetBmpDisplacement
getIdealSizegetIdealSize
getImagegetImage
getImageListgetImageList
getTextMargingetTextMargin
pushpush
scrollscroll
scrollBitmapFromToscrollBitmapFromTo
scrollTextscrollText
setImagesetImage
setImageListsetImageList
setTextMarginsetTextMargin
statestate
state=state=
style=style=

push

>>--push---------------------------------------><

The push method simulates the user pushing the associated button control. It allows a Rexx programmer to produce the exact same behavior from within an ooDialog program as the behavior produced by the user pushing the button in the dialog.

Arguments:

There are no arguments to this method.

Return value:

This method does not return a value.

Example:

This example comes from an imaginary program that has a list of window handles. The dialog has a Refresh button that the user can push to update the window list. The code comes from a section of the program that is checking if a specific window handle is valid. If the handle is not valid, the code simulates the user pushing the Refresh button to update the window list.

::method validateHandle private
    use strict arg hwnd
    if \ self~isWindowHandle(hwnd) then do
        self~getButtonControl(IDC_PB_REFRESH)~push
        return .false
    end
    ...
return .true

click

>>--click----------------------------------------><

The click method programmatically clicks the associated button control. It simulates the user clicking the button and produces exactly the same behavior as if the user had clicked on the button with the mouse.

Arguments:

This method takes no arguments.

Return value:

This method does not return any value.

Example:

This example closes the dialog as if the user had clicked the cancel button. (Provided of course that the dialog has a cancel button.)

self~getButtonControl(IDCANCEL)~click

state

>>--state----------------------------------------><

The state method retrieves the current state of the associated button control.

Return value:

A text string that can contain one or more of the following keywords, separated by blanks:

"CHECKED"

The radio button or the check box is checked. A radio button is checked when it contains a black dot, a check box is checked when it contains a check mark.

"UNCHECKED"

The radio button or the check box is not checked. A radio button is not checked when it does not contain a black dot and a check box is not checked when it does not contain a check mark.

"INDETERMINATE"

A 3-state check box button is neither checked nor unchecked. Only 3-state check box buttons can be in this state. When in the indeterminate state, the check box button is drawn in a visually distinctive manner that is different from checked or unchecked. Exactly how the indeterminate state is drawn is dependent on the operating system version.

"PUSHED"

When a button is in the pushed state it is drawn as a sunken button, otherwise it is drawn as a raised button. The user causes a button to be in the pushed state by clicking the button with the left mouse button. As long as the mouse button is held down, the button will be drawn as pushed. When the user releases the mouse button, the button will resume its not pushed state. When this keyword is not in the text string, the button is not in the pushed state.

"FOCUS"

The button has the keyboard focus. When this keyword is missing from the text string, the button does not have the focus.

Example:

button = MyDialog~GetButtonControl("IDOK")
if button == .Nil then return
say button~State

The result could be "UNCHECKED FOCUS".

state=

>>--state=--newState-----------------------------><

The state= method sets the state for the associated button control.

Arguments:

The only argument is:

newState

A text string that contains one or more of the following keywords, separated by a blank:

CHECKEDUNCHECKED
PUSHEDNOTPUSHED
INDETERMINATEFOCUS

CHECKED

The radio button or the check box is to be set to the "checked" state.

UNCHECKED

The radio button or the check box is to be set to the "unchecked" state.

PUSHED

The button is to be set to the "pushed" state.

NOTPUSHED

The "pushed" state is to be removed from the button.

INDETERMINATE

The 3-state check box button is to be set to the "indeterminate" state. This state can only be applied to 3-state check box buttons.

FOCUS

The button is to be set to the "focused" state.

Example:

button = MyDialog~GetButtonControl("IDOK")
if button == .Nil then return
button~state="FOCUS PUSHED"

Notes:

Some points to remember when using this method.

  1. The checked, unchecked or indeterminate states have no meaning for a push button. Setting a push button to one of these states therefore has no effect.

  2. A radio button or check box can be set to only one of the checked, unchecked or indeterminate states. If more than one of these states is specified in the text string the button is set to the state that is first in the string.

  3. Only 3-state check box buttons can be set to the indeterminate state. If this keyword is used for a button that is not a 3-state button then the button's state is not changed.

  4. To change a button state to not focused programmatically use one of the ooDialog methods that move the focus: TabToNext, TabToPrevious, SetFocus, FocusItem, etc..

style=

>>--style=--newStyle-----------------------------><

The style= method changes the style of the associated button control.

Note: In the past, the documentation for this method was incomplete or misleading. There are really two aspects to a button, its type (or kind) and its style. Many of the button styles only have meaning within the same type of button. These styles can not be applied to a button of a different type after the button has been created.

For instance, the AUTOCHECKBOX style can only be applied to a check box type of button. Trying to give this style to a radio type button has no effect. Because of this, certain of the style key words have no effect. They are listed here only because they were listed in previous versions of the documentation. This may have lead someone to use the key word in their code. An example is the GROUPBOX key word. The group box type of button only has one style. This style can not be applied to any other type of button, so setting the style of any button to GROUPBOX has no effect, and has never had any effect.

However, within each type of button, the styles that apply to that type of button can be changed. For instance, a check box type of button that has the 3STATE style, can be changed to have the AUTOCHECKBOX style or to have the AUTO3STATE style.

Arguments:

The only argument is:

newStyle

A text string containing one or more of the following keywords separated by blanks. Common sense should be used when constructing the newStyle string. If mutually exclusive key words are used, the outcome will be dependent on the order of the key words.

DEFPUSHBUTTONTEXT NOTPUSHLIKE
LEFTTEXT MULTILINE AUTO3STATE
BOTTOM CHECKBOX RIGHT
PUSHBOX ICON NOTMULTILINE
RIGHTBUTTONNOTIFY GROUPBOX
VCENTER AUTOCHECKBOX HCENTER
RADIO BITMAP NOTNOTIFY
NOTLEFTTEXTFLAT OWNERDRAW
PUSHLIKE 3STATE TOP
AUTORADIO LEFT NOTFLAT

DEFPUSHBUTTON

In a dialog, the default push button is the button that is pushed when the Enter key is pressed. Changing the default push button will change the behavior of the dialog when the user presses the enter key.

PUSHBOX

A push button that does not display the button face or border, only the text appears. This button style is not applicable when Windows themes are in use.

RADIO

A radio button the state of which has to be maintained by the programmer.

AUTO

A radio button where the operating system maintains the check state for all radio buttons in the same group. When one radio button in the group is checked by the user, the operating system unchecks all other buttons in the group.

CHECKBOX

A check box where the state has to be maintained by the programmer. The state can only be checked or unchecked.

AUTOCHECKBOX

A check box where the operating system maintains the check state for the programmer.

3STATE

A check box button that has a grayed state as well as checked or unchecked. The greyed state shows that the check state of the button is not determined. The programmer needs to manage the state of the button when it is clicked.

AUTO3STATE

A check box button that is the same as a three-state check box except that the operating system maintains the check state for the programmer.

GROUPBOX

This key word has no effect.

OWNERDRAW

This key word has no effect.

LEFTTEXT

Places the text on the left of the button for a radio button or check box. This style and RIGHTBUTTON are equivalent.

RIGHTBUTTON

Places the button on the right of the text for a radio button or a check box. This style is the same as LEFTTEXT.

NOTLEFTTEXT

Removes the LEFTTEXT style.

TEXT

The button displays text.

ICON

The button displays an icon image.

BITMAP

The button displays a bitmap image.

LEFT

The button has its text left-justified in the button rectangle.

RIGHT

The button has its text right-justified in the button rectangle.

HCENTER

The button has its text centered horizontally in the button rectangle.

TOP

The text is placed at the top of the button rectangle.

BOTTOM

The text is placed at the bottom of the button rectangle.

VCENTER

The text is vertically centered in the button rectanble.

PUSHLIKE

Causes a radio button or check box button to behave like a push button.

MULTILINE

Causes the text for a button to wrap to multiple lines if the text is too long for the width of the button.

NOTIFY

Enables a button to send the kill focus and set focus messages. See the connectButtonNotify method of the MessageExtensions Class. If the button does not have this style, kill and set focus events will not be received, if the programmer does connectButtonNotify() to connect those events.

FLAT

Gives the button a flat appearance. This style is not applicable when Windows themes are in effect.

NOTPUSHLIKE

Removes the push like style.

NOTMULTILINE

Removes the multi-line style.

NOTNOTIFY

Removes the notify style.

NOTFLAT

Removes the flat style.

Example 1:

The following example makes the OK button the default button:

button = MyDialog~GetButtonControl("IDOK")
if button == .Nil then return
button~style="DEFPUSHBUTTON"

Example 2:

This example changes the text of a check box button depending on the state another check box. When the button text is long, the multi-line style is added and the placement of the text in relation to the button rectangle is changed. When the text is short, the button style is set back to the default style.

 
::method idCheckOne
  use arg wParam, lParam

  id = .DlgUtil~loWord(wParam)
  if self~getCheckControl(id)~checked then do
    chkButton = self~getCheckControl(IDC_CHECK_TWO)
    chkButton~style = "MULTILINE TOP HCENTER"
    chkButton~setTitle("Use IPv6 not IPv4 during this connection")
  end
  else do
    chkButton = self~getCheckControl(IDC_CHECK_TWO)
    chkButton~style = "NOTMULTILINE VCENTER LEFT"
    chkButton~setTitle("Connect")
  end

getIdealSize

>>--getIdealSize---------------------------------><

This method queries the button control for its ideal size. The ideal size is the size that best fits its text or image. (If the button has an image.)

Details

This method requires Common Control Library version 6.0 or later. If necessary use the comCtl32Version() method to determine the current version of the library.

Arguments:

This method has no arguments.

Return value:

The possible return values are:

A .Size object

The ideal size for the button.

The .nil object

Some unanticipated error. This is very unlikely to happen.

Example:

  size = self~getButtonControl(IDC_PB_REVIEW)~getIdealSize
  say 'The ideal height for the button is' size~height'
  say 'The ideal width for the button is' size~width

  /* Output might be for example:
   *   The ideal height for the button is 24
   *   The ideal width for the button is 45
   */

getTextMargin

>>--getTextMargin--------------------------------><

This method retrieves the margins used to draw text within the assoicated button control.

Details

This method requires Common Control Library version 6.0 or later. If necessary use the comCtl32Version() method to determine the current version of the library.

Arguments:

This method does not take any arguments.

Return value:

The possible return values are:

A .Rect object

The margin for drawing text in the button.

The .nil object.

An unanticipated error. This is not likely to happen.

Example:

This example gets the text margins for the Redraw button and displays the information:

margins = self~getButtonControl(IDC_PB_REDRAW)~getTextMagin
say 'The text margins for the "Redraw" button:'
say '  Left:  ' margins~left
say '  Top:   ' margins~top
say '  Right: ' margins~right
say '  Bottom:' margins~bottom

/* Output might be for example:
 *   The text margins for the "Redraw" button:
 *     Left:   1
 *     Top:    1
 *     Right:  1
 *     Bottom: 1
 */

setTextMargin

>>--setTextMargin(--margins--)-------------------><

This method sets the margins for drawing text in the associated button control.

Details

This method requires Common Control Library version 6.0 or later. If necessary use the comCtl32Version() method to determine the current version of the library.

Raises syntax errors when incorrect arguments are detected.

Arguments:

The only argument is:

margins

A .Rect object describing the new margins.

Return value:

The possible return values are:

.true

Success

.false

Failed.

Example:

This example sets a new text margin of 5 for the button control.

margins = .Rect~new(5, 5, 5, 5)
self~getButtonControl(IDC_PB_SHOW_DETAILS)~setTextMargin(margins)

getImageList

>>--getImageList---------------------------------><

This method retrieves information describing the image list for the associated button, if there is one.

Details

This method requires Common Control Library version 6.0 or later. If necessary use the comCtl32Version() method to determine the current version of the library.

Arguments:

The are no arguments to this method.

Return value:

The return value is:

A .Directory object.

The image list information is returned in a Directory object. See the setImageList() method for clarification of the information returned. The directory object has the following entries:

imageList

The .ImageList object containing the images for the button.

rect

A .Rect object that specifies the margin around the image.

alignment

The numeric flag that specifies the alignment of the image list.

The .nil object

The Nil object is returned if the button does not have an image list, or for some other unanticipated error.

Example:

This example gets the image list from the View push button and displays the information returned.


  pbView = self~getButtonControl(IDC_PB_VIEW)
  d = pbView~getImageList

  say 'Got image list:' d
  if d <> .nil then do
    say '  image:  ' d~imageList
    say '  rect:   ' d~rect
    say '  align:  ' self~getAlignmentText(d~alignment)

    say 'Image margins:' d~rect~left',' d~rect~top',' d~rect~right',' d~rect~bottom
  end
  ...

::method getAlignmentText private
  use strict arg align
  select
    when align = .Image~toID(BUTTON_IMAGELIST_ALIGN_CENTER) then return "center"
    when align = .Image~toID(BUTTON_IMAGELIST_ALIGN_LEFT) then return "left"
    when align = .Image~toID(BUTTON_IMAGELIST_ALIGN_RIGHT) then return "right"
    when align = .Image~toID(BUTTON_IMAGELIST_ALIGN_TOP) then return "top"
    when align = .Image~toID(BUTTON_IMAGELIST_ALIGN_BOTTOM) then return "bottom"
    otherwise return "error"
  end
  -- End select

/* Output might be for example:

  Got image list: a Directory
    image:   an ImageList
    rect:    a Rect
    align:   left
  Image margins: 1, 1, 1, 1

 */

setImageList

>>--setImageList(--imageList--,--+--------+--,--+-------+--)-------------------><
                                 +-margin-+     +-align-+

Sets, or removes the image list for the button. To remove an existing image list, the programmer passes in .nil for the first argument.

Using an image list with a button is a new feature that requires Windows XP or later. It provides an easier, more convenient way to do owner-drawn buttons. This method should be the preferred way for the ooDialog programmer to do bitmap buttons, where the primary purpose is to provide an image on the button. Using an image list will automatically give the button the same look and feel as other buttons on the system.

A .ImageList object is used to supply the images for the button. If the image list only contains 1 image at the first index, then that image is used for all button states. If more than 1 image is supplied, the the image at each index is used for the button state with this mapping:

index 0 = Normal
index 1 = Hot
index 2 = Press
index 3 = Disabled
index 4 = Defaulted
index 5 = StylusHot

StylusHot is only used on tablet computers. If more than 1 image is supplied, but some indexes do not have an image, then the system does not draw an image for that state. The programmer retains ownership of the image list. What this means in essence is the programmer decide when, or if, the image list should be released. See the discussion in the .ImageList class about releasing image lists if needed. If you release the image list while the dialog is stil active, the images on the button disappear.

A sample program: imageButton.rex in the samples directory is provided that shows how to use this method. It is in: samples\oodialog\examples.

Details

This method requires Common Control Library version 6.0 or later. If necessary use the comCtl32Version() method to determine the current version of the library.

Sets the .SystemErrorCode variable.

Raises syntax errors when incorrect arguments are detected.

Arguments:

The arguments are:

imageList

A .ImageList object containing the images for the button. If this argument is the Nil object, then any existing image list is removed.

margin

Optional. A .Rect object containing the margins around the image. The default is a 0 margin.

alignment

Optional, Specifies the alignment of the image on the button. You can use .Image~toID() to get the correct numeric value for one of the following symbols,

BUTTON_IMAGELIST_ALIGN_LEFT BUTTON_IMAGELIST_ALIGN_RIGHT
BUTTON_IMAGELIST_ALIGN_TOP BUTTON_IMAGELIST_ALIGN_BOTTOM
BUTTON_IMAGELIST_ALIGN_CENTER  

or use the numeric value itself.

The default is BUTTON_IMAGELIST_ALIGN_CENTER.

Return value:

The possible return values are:

oldImageList

If there is an existing image list, it is returned in the same format specified in the () method.

.nil

The Nil object is returned if there was no existing image list, and also if an error is encountered. In general, the .SystemErrorCode variable should be set to non-zero if an error happend.

Example:

This example creates an image list from a set of bitmap files. Each image represents one of the possible buttons states. In the program, as the button changes states, the text on the button is also changed. So, the program calculates the ideal button size using the longest label, then resets the button size to the ideal size.

Since the image list API is only available with XP or later, the program checks that the API is available before proceeding. For further information on some of the methods used in the example see getIdealSize and comCtl32Version.


  ...
  if .DlgUtil~comCtl32Version  < 6 then return -2

  files = .array~new()
  files[1] = "resources\Normal.bmp"       -- Normal
  files[2] = "resources\Hot.bmp"          -- Hot (hover)
  files[3] = "resources\Pushed.bmp"       -- Pushed
  files[4] = "resources\Disabled.bmp"     -- Disabled
  files[5] = "resources\Default.bmp"      -- Default button
  files[6] = "resources\Hot.bmp"          -- Stylus hot, tablet PC only

  -- Set the flags to create a 24 bit color, masked image list.
  flags = .DlgUtil~or(.Image~toID(ILC_COLOR24), .Image~toID(ILC_MASK))
  imageList = .ImageList~create(.Size~new(61, 46), flags, 10, 10)

  images = .Image~fromFiles(files)
  cRef = .Image~colorRef(255, 255, 255)
  imageList~addImages(images, cRef)

  align = .Image~toID(BUTTON_IMAGELIST_ALIGN_LEFT)
  margin = .Rect~new(1)

  ret = pbView~setImageList(imageList, margin, align)
  if .SystemErrorCode <> 0 then do
    -- put some error handling here
    return -1
  end

  -- Temporarily set the title to the longest text, to calculate
  -- the ideal size.
  pbView~setTitle("DEATH if you touch me")
  bestSize = pbView~getIdealSize

  -- Not reset the button label and set the size to the ideal size.
  pbView~setTitle("View Pictures")
  pbView~setRect(0, 0, bestSize~width, bestSize~height, "NOMOVE")

return 0

getImage

>>--getImage----------------------------------------------------><

Retrieves a button's image if one is set, or .nil if the button does not have an image associated with it.

Arguments:

This method does not take any arguments.

Return value:

This method returns the .Image object for the button, or .nil if the button does not have an image .

Example:

In this example a bitmap has been set for the button on a popup dialog. When the dialog closes, bitmap image is retrieved from the button and released.

::method cancel
  button = self~getButtonControl(IDC_PB_PUSHME)
  image = button~getImage
  if image <> .nil then image~release
  return self~cancel:super

setImage

>>--setImage(-newImage-)----------------------------------------><

Sets, or removes, the image assoicated with a button. The image can bet a bitmap, icon, or cursor. Note that the button style has to match the type of image. For cursors and icons, the button must be an ICON button. For bitmap images, the button must be a BITMAP button.

To completely remove an image assoicated with the button use .nil for the argument.

Details

Raises syntax errors when incorrect arguments are detected.

Arguments:

The single required argument is either the .Image object to be associated with the button or .nil. The use of .nil for the argument removes any existing image.

Return value:

This method returns the old image, if there was one, otherwise .nil.

Example:

This example gets an image from the resource file for a ResDialog and assoicates it with the Push Me button.

::method initDialog
  module = .ResourceImage~new("imageButton.dll", self)
  image = module~getImage(101)
  self~getButtonControl(IDC_PB_PUSHME)~setImage(image)
  self~connectButton(IDC_PB_PUSHME, onPushMe)

ChangeBitmap

>>-aButtonControl~ChangeBitmap(--bmpNormal--,--+------------+--,-->
                                               +-bmpFocused-+

>--+-------------+--,--+-------------+--+-----------------+--)-><
   +-bmpSelected-+     +-bmpDisabled-+  +-,--+-FRAME----+-+
                                             +-USEPAL---+
                                             +-INMEMORY-+
                                             +-STRETCH--+


The ChangeBitmap method changes the bitmap of a bitmap button.

Arguments:

The arguments are:

bmpNormal

The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when the button is neither selected, nor focused, nor disabled. If you specify the bitmap handle, the INMEMORY option must be specified.

This option is used if none of the other arguments is specified.

bmpFocused

The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when the button is focused. The focused button is activated when the Enter key is pressed. If you specify the bitmap handle, the INMEMORY option must be specified.

bmpSelected

The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when the button is clicked and held. If you specify the bitmap handle, the INMEMORY option must be specified.

bmpDisabled

The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when the button is disabled. If you specify the bitmap handle, the INMEMORY option must be specified.

styleOptions

The last argument can be one of the following:

FRAME

Draws a frame around the button. When you use this option, the bitmap button behaves like a normal Windows button except that a bitmap is shown instead of text.

USEPAL

Takes the colors of the bitmap file and stores them as the system color palette. This option is needed when the bitmap was created with a palette other than the default Windows color palette. Use it for one button only because only one color palette can be active at a time.

This option is not valid for a bitmap loaded from a dynamic-link library.

INMEMORY

This option must be used if the named bitmaps are already loaded into memory by using the LoadBitmap method (see LoadBitmap). In this case, you must specify a bitmap handle instead of a file name or ID.

STRETCH

If this option is specified and the extent of the bitmap is smaller than the extent of the button rectangle, the bitmap is adapted to match the extent of the button. This option has no effect on bitmaps loaded from a dynamic-link library.

Example:

button = MyDialog~GetButtonControl("IDOK")
if button == .Nil then return
button~ChangeBitmap("AddBut_n.bmp", "AddBut_f.bmp", "AddBut_s.bmp", ,
"AddBut_d.bmp", "FRAME")

See also ConnectBitmapButton.

DisplaceBitmap

>>-aButtonControl~DisplaceBitmap(--x--,--y--)------------------><


The DisplaceBitmap method sets the position of a bitmap within a bitmap button.

Arguments:

The arguments are:

x

The horizontal displacement, in screen pixels. A negative value can also be used.

y

The vertical displacement, in screen pixels. A negative value can also be used.

Example:

The following example moves the bitmap within the associated bitmap button 4 screen pixels to the right and 3 pixels upward:

button = MyDialog~GetButtonControl("IDOK")
if button == .Nil then return
parse value button~GetBmpDisplacement with dx dy
button~DisplacementBitmap(244, dx+4, dy-3)

GetBmpDisplacement

>>-aButtonControl~GetBmpDisplacement---------------------------><


The GetBmpDisplacement method retrieves the position of a bitmap within a bitmap button.

Return value:

The horizontal and vertical positions of the bitmap, in screen pixels and separated by a blank.

Example:

See DisplaceBitmap.

Scroll

>>-aButtonControl~Scroll(--xPos--,--yPos--,--left--,--top--,--right--,--bottom--)-><


The Scroll method moves the rectangle within the associated button and redraws the uncovered area with the button background color. It is used to move bitmaps within bitmap buttons.

Arguments:

The arguments are:

xPos, yPos

The new position of the rectangle, in screen pixels.

left, top, right, bottom

The upper left and lower right corner of the rectangle to be moved.

ScrollText

                                                         +-10-------+
>>-aButtonControl~ScrollText(--text--,--+----------+--,--+----------+--,------>
                                        +-fontName-+     +-fontSize-+

                                    +-0---------+     +-4----+     +-10----+
>--+--------------------------+--,--+-----------+--,--+------+--,--+-------+-->
   |    +----------------+    |     +-displaceY-+     +-step-+     +-sleep-+
   |    V                |    |
   +-"----+-THIN-------+-+--"-+
          +-EXTRALIGHT-+
          +-LIGHT------+
          +-MEDIUM-----+
          +-SEMIBOLD---+
          +-EXTRABOLD--+
          +-BOLD-------+
          +-HEAVY------+
          +-UNDERLINE--+
          +-ITALIC-----+
          +-STRIKEOUT--+

      +-0-----+
>--,--+-------+--)----------------------------------------------------------><
      +-color-+


The ScrollText method scrolls text in the associated button with the given font, size, and color. The text is scrolled from right to left. If the method is started concurrently, call it a second time to stop scrolling. The associated button must have the OWNERDRAWN style.

Arguments:

The arguments are:

text

A text string that is displayed and scrolled.

fontName

The name of the font used to write the text. If omitted, the system font is used.

fontSize

The size of the font used to write the text. If omitted, the standard size (10) is used.

fontStyle

This argument can be one or more of the keywords listed in the syntax diagram. If you use more than one keyword, put them in one string, separated by blanks.

displaceY

The vertical displacement of the text relative to the top of the client area of the window. The default is 0.

step

The amount of screen pixels that the text is moved in each cycle. The default is 4.

sleep

The time, in milliseconds, that the program waits after each movement to determine the scrolling speed. The default is 10.

color

The color index used for the text. The default is 0, which is black.

Example:

The following example scrolls the string "Hello world!" from left to right within the associated button. The text is located 2 pixels below the top of the client area, one move is 3 screen pixels, and the delay time after each movement is 15 ms.

button = MyDialog~GetButtonControl("IFOK")
if button == .Nil then return
button~ScrollText("Hello world!", "Arial", 36, "BOLD ITALIC", 2, 3, 15, 4)

GetBitmapSizeX

>>-aButtonControl~GetBitmapSizeX-------------------------------><


The GetBitmapSizeX method retrieves the width of the bitmap that is set for the associated button.

Return value:

The width of the bitmap, in screen pixels.

GetBitmapSizeY

>>-aButtonControl~GetBitmapSizeY-------------------------------><


The GetBitmapSizeY method retrieves the height of the bitmap that is set for the associated button.

Return value:

The height of the bitmap, in screen pixels.

DrawBitmap

                               +-0----+     +-0----+     +-0----+
>>-aButtonControl~DrawBitmap(--+------+--,--+------+--,--+------+--,-->
                               +-tarx-+     +-tary-+     +-srcx-+

   +-0----+     +-0-----+     +-0------+
>--+------+--,--+-------+--,--+--------+--)--------------------><
   +-srcy-+     +-width-+     +-height-+


The DrawBitmap method draws the bitmap of the associated bitmap button. You can also use this method to move a bitmap or part of it.

Contrary to the method DisplaceBitmap, which sets a permanent position for the bitmap, DrawBitmap immediately draws the bitmap, or part of it, at the specified position. If the button must be refreshed, the bitmap is drawn at the position set with DisplaceBitmap. DrawBitmap is used by ScrollBitmapFromTo, for example.

Arguments:

The arguments are:

tarx,tary

The position relative to the client area of the button where the bitmap is to be displayed. The default is 0,0.

srcx,srcy

The offsets that specify the first pixel in the bitmap to be displayed. If you omit these arguments, the pixel at position 0,0 is the first pixel displayed.

width,height

The width and height of the bitmap. If you omit these arguments or specify 0, the entire bitmap is displayed at the specified position. You can use these arguments to display only parts of the bitmap.

Return value:

0 if the bitmap could be drawn.

Note: You can use the DrawBitmap method to animate a bitmap by providing a bitmap that contains several images and use the offset and extension arguments to display a single image of the bitmap.

DimBitmap

>>-aButtonControl~DimBitmap(--bmpHandle--,--width--,--height--,-->

   +-2-----+     +-2-----+     +-10----+
>--+-------+--,--+-------+--,--+-------+--)--------------------><
   +-stepx-+     +-stepy-+     +-steps-+


The DimBitmap method draws a bitmap step by step.

Arguments:

The arguments are:

bmpHandle

A handle to the bitmap loaded with LoadBitmap.

width, height

The extensions of the bitmap.

stepx, stepy

The number of incremental pixels displayed at each step. The default is 2,2.

steps

The number of iterations used to display the bitmap. The default is 10.

Return value:

This method does not return a value.

ScrollBitmapFromTo

>>-aButtonControl~ScrollBitmapFromTo(--fromX--,--fromY--,--toX--,--toY--,-->

>--stepx--,--stepy--,--delay--,--displace--)-------------------><


The ScrollBitmapFromTo method scrolls the bitmap within the associated bitmap button from one position to another.

For an explanation of the arguments, refer to ScrollBitmapFromTo.