Connect Event Methods

The following methods create a connection between an event of the Windows dialog, or a dialog control, and a method of the Rexx dialog object. In the Windows user interface, as the user interacts with the system, events are generated that specify what the action of the user was. Mouse clicks, keyboard presses, moving or sizing windows, all generate events. In the ooDialog framework, when a specific event is connected to a method, that method will be invoked each time the event occurs.

In a UserDialog the Connect... event methods for buttons are called automatically from the Add... methods. However, for most events like the resize or move events, the connection needs to be made explicitly. In general, events should be connected before the dialog is shown on the screen. So, the Connect... event methods can be used in the InitDialog method. In a UserDialog, the DefineDialog method is a good place for the Connect... event methods. If the programmer is overriding the Init method, the Connect... event methods can be placed there. But, be sure the methods are not used until after the superclass has been initialized.

Note: The method name that is to be invoked when the specified event occurs must be less than 256 characters.

ConnectResize

>>-aBaseDialog~ConnectResize(--msgToRaise--)-------------------><


The ConnectResize method connects a dialog resize event with a method. It is called each time the size of the dialog is changed.

Arguments:

The only argument is:

msgToRaise

The message that is to be sent each time the dialog is resized. Provide a method with a matching name.

Return value:

This method does not return a value.

Example 1:

  dlg = .ResizingDialog~new
  dlg~createCenter(100, 60, "Resize Me", "THICKFRAME")
  dlg~execute("SHOWTOP")

::requires 'ooDialog.cls'

::class 'ResizingDialog' subclass UserDialog

::method init
  forward class (super) continue

  self~connectResize("onSize")

::method onSize
  use arg sizeEvent, sizeInfo

  -- Wait until the last size event message, in a series of messages, arrives.
  msg = self~peekDialogMessage
  if msg~left(6) = "ONSIZE" then return

  -- sizeInfo contains information about the new width and height in pixels.
  w = .DlgUtil~loWord(sizeinfo) / self~factorX
  h = .DlgUtil~hiWord(sizeinfo) / self~factorY
  say "New width=" w ", new height=" h

Example 2:

This example is pulled from the File Viewer example at the end of the "Appearance and Behavior Methods" section. A complete working example is presented there that uses a number of the base dialog methods.


::method defineDialog
  expose wasMinimized

  wasMinimized = .false
  style = "VSCROLL HSCROLL MULTILINE READONLY"
  self~addEntryLine(IDC_MULTILINE, "cEntry", 0, 0, 170, 180, style)
  self~connectResize("onSize")
  ...

/* The first arg, sizeEvent, is a flag that the OS sends specifying the type of
 * size event.  We are only interested in these 3 flags:
 *
 * SIZE_RESTORED   = 0
 * SIZE_MINIMIZED  = 1
 * SIZE_MAXIMIZED  = 2
 */
::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

Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, use Init as the place for this connection - but not before init:super has been called.

ConnectMove

>>-aBaseDialog~ConnectMove(--msgToRaise--)---------------------><


The ConnectMove method connects a dialog move event with a method. It is called each time the position of the dialog is changed.

Arguments:

The only argument is:

msgToRaise

The message that is to be sent each time the dialog is moved. Provide a method with a matching name.

Return value:

This method does not return a value.

Example:

::class MyDlgClass subclass UserDialog

::method init
  forward class (super) continue

  self~connectMove(onMove)

::method onMove
  use arg unUsed, posInfo

  -- Look at our message queue to see if the next message in the queue is also
  -- onMove.  If so, just return.
  msg = self~peekDialogMessage
  if msg~left(6) = "ONMOVE" then return

  -- Now, we should be done moving, print out where we are.
  x = .DlgUtil~loWord(posInfo)
  y = .DlgUtil~hiWord(posInfo)
  say 'At coordinate (' x',' y' ) on the screen. (In pixels.)'

Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, use Init as the place for this connection - but not before init:super has been called.

ConnectPosChanged

>>-aBaseDialog~ConnectPosChanged(--msgToRaise--)---------------><


The ConnectPosChanged method connects a change regarding the dialog coordinates with a method. It is called each time the size, position, or place in the Z order of the dialog is changed.

Arguments:

The only argument is:

msgToRaise

The message that is to be sent each time the coordinates of the dialog are changed. Provide a method with a matching name.

Return value:

This method does not return a value.

Example:

::class MyDlgClass subclass UserDialog

::method Init
  self~init:super(...)
  self~ConnectPosChanged("OnNewPos")

::method OnNewPos
  say "The new rectangle is" self~GetWindowRect(self~DlgHandle)

Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, use Init as the place for this connection - but not before init:super has been called.

ConnectMouseCapture

>>-aBaseDialog~ConnectMouseCapture(--msgToRaise--)------------->>


The ConnectMouseCapture method connects a method with the lose-mouse-capture event. It is called each time the dialog loses the mouse capture. This can happen, for example, when you move a dialog with the mouse and release the left mouse button.

Arguments:

The only argument is:

msgToRaise

The message that is to be sent each time the mouse capture is lost in the dialog. Provide a method with a matching name.

Return value:

This method does not return a value.

ConnectHelp

>>-aBaseDialog~ConnectHelp(--msgToRaise--)-----------------------><


The ConnectHelp method connects the Windows Help event with a method in the dialog class. The Windows Help event occurs when the user presses the F1 key. (Only the Help events generated when the dialog is the active window are connected.)

Arguments:

The only argument is:

msgToRaise

The name of the method that is to be invoked.

Return value:

0

No error.

1

An (internal) error prevented the message from being connected to a method.

Event Method Arguments

The ooDialog method connected to the Help event will receive the following four arguments in the order listed:

id

The resource ID of the dialog, dialog control, or menu item that had the focus when the F1 key was pressed.

type

Specifies if the ID in argument 1 was from a window (a dialog or dialog control) or from a menu item. This argument will either be WINDOW or MENU.

mouseX

The x coordinate of the mouse at the time the F1 key was pressed. This value is an absolute screen coordinate (pixel) and note that the mouse will not necessarily be over the dialog.

mouseY

The y coordinate of the mouse at the time the F1 key was pressed.

Example:


::method Init
    self~init:super
    ...
    self~connectResize(onResize)
    self~connectHelp(onHelp)
    ...

::method onHelp
    use arg id, type, mouseX, mouseY
    if type == "MENU" then w = 'Menu id' id; else w = 'Dialog id' id
    say "Help request:"
    say " " w
    say "  Mouse position x:" mouseX "y:" mouseY

/* As the user presses the F1 key at various times when the dialog has the focus
 * the output might be as follows:
 */

Help request:
  Dialog id 12
  Mouse position x: 420 y: 106
Help request:
  Menu id 60
  Mouse position x: 204 y: 93
Help request:
  Menu id 65
  Mouse position x: 203 y: 166
Help request:
  Dialog id 14
  Mouse position x: 218 y: 410
Help request:
  Dialog id 80
  Mouse position x: 387 y: 462

ConnectKeyPress

>>-aBaseDialog~ConnectKeyPress(--msgToRaise--,--keys-+------------+--)----><
                                                    +-,--filter--+

The ConnectKeyPress method connects a key press event with a method in the dialog class. A single key or multiple keys can be connected to the same method. Multiple methods can be connected for key press events, but only 1 method can be connected to any single key.

The underlying Windows dialog must exist before this method can be used. That means it can be used in InitDialog or any time thereafter. There is a maximum limit of 63 methods, per dialog, that can be connected to key press events. Connections can be removed (see the DisconnectKeyPress method) if there is no longer a need for a notification of a key press.

A similar method is a member of the DialogControl class. It is important to note this distinction between the two methods. The method of the BaseDialog (this method) will capture any key press event when the dialog is the active window. The method of the DialogControl class will only capture a key press when the control has the keyboard focus.

Arguments:

The arguments are:

msgToRaise

The name of the method that is to be invoked when the key press event happens.

keys

The key (or keys) for which the key press event is to be connected. A single key or multiple keys can be specified. A range of keys can be used. Each single key or range of keys is separated by a comma. A range of keyes is denoted by using the dash character "-". White space within the keys argument is ignored.

The keys are specified by the numeric value defined by Microsoft for its virtual key set. These numeric values are 0 through 255, although both 0 and 255 are not used. The VirtualKeyCodes class can be used to make a program more readable.

Note: The programmer can use the Windows documentation and Platform SDK to obtain the full list of the virtual key numbers.

In addition there are a few keywords that can be used to specify some common key ranges. These keywords are:

ALL

All keys.

FKEYS

All Function keys, other than F1. (In Windows the F1 key is the help key and the ConnectHelp method should be used for F1.)

ALPHA

The keys A though Z.

NUMERIC

The keys 0 through 9. Note that these are the normal number keys, not the keypad numbers on an enhanced keyboard.

ALPHANUMERIC

The keys A through Z and 0 through 9.

Note: Case is insignificant for these keywords as is the order of the keywords. A keyword not in the list will result in a return of -1. However, if the argument contains other valid key tokens, those keys will be connected to the method. If there are no other valid key tokens, then no connection is made.

filter

A (simplistic) filter that is applied to the key press event for the key(s) specified. The filter is a string of keywords separated by blanks. (Case is not significant, neither is the order of the words. Any words other than the specified keywords are ignored.) The possible keywords are: SHIFT, CONTROL, ALT, AND, NONE.

Shift, control, and alt specify that the corresponding key must be down at the time of the key press event. These keywords are combined in a boolean expression. The default is an OR expression. If the AND keyword is present then the boolean expression is an AND expression. If the NONE keyword is used, it means that none of the shift, control, or alt keys can be down at the time of the key press event. (When NONE is used, all other words in the string are ignored.)

Some examples may make this more clear:


::method initDialog

  -- Using the below, the onAltCD method would be invoked when the user types
  -- Alt-Shift-C or Alt-Shift-D.  But the method would not be invoked for Alt-C
  -- or Shift-D (or any other key press event.)

  keys = self~vCode('C') "," self~vCode('D')
  self~connectKeyPress(onAltCD, keys, "ALT AND SHIFT")

  -- The below would invoke the onAltCD method any time a C or a D was typed
  -- with either the Alt or the Control key down.  This would include Alt-C,
  -- Alt-Shift-C, Ctrl-Alt-Shift-C, etc..

  self~connectKeyPress(onAltCD, keys, "ALT CONTROL")

  -- The below would invoke the onAltCD method only when Alt-C or Alt-D was
  -- typed.

  self~connectKeyPress(onAltCD, keys, "ALT AND")

  -- The below would invoke the onF4 method only when the F4 key was pressed by
  -- itself. Alt-F4, Ctrl-F4, etc., would not invoke the method.

  self~connectKeyPress(onF4, self~vCode('F4'), "NONE")

Return value:

The return values are:

0

Success.

-1

A problem with one of the arguments, such as skipping a required argument, using an incorrect format for the keys or the filter arguments, etc.. Note that it is possible to get a return of -1 but still have some keys connected. For instance in the following example the C and D keys would be connected and the filter applied. The ""dog"" token would result in -1 being returned:


  keys = self~vCode('C') ", dog," self~vCode('D')
  ret = self~connectKeyPress('onAltCD', keys, "ALT AND SHIFT")
  say 'Got a return of:' ret
  say "Have connection to onAltCD?" self~hasKeyPressConnection('onAltCD')

  -- The output would be:
  Got a return of: -1
  Have connection to onAltCD? 1

-2

The underlying mechanism in the Windows API that is used to capture key events failed.

-4

An (internal) problem with the dialog window.

-5

Memory allocation error in the underlying Windows API.

-6

The maximum number of connections has been reached.

-7

The msgToRaise method is already connected to a key down event for this dialog.

Event Method Arguments

The ooDialog method connected to the key press event will receive the following five arguments in the order listed:

keyCode

The numeric code of the key pressed.

shift

A boolean (true or false) that denotes whether a shift key was down or up at the time of the key press. It will be true if a shift key was down and false if the shift key was not down.

control

True if a control key was down at the time of the key press, false if it was not.

alt

True if an alt key was down at the time of the key press, false if it was not.

extraInfo

This argument is a string containing keywords. It supplies extra information about the keyboard state at the time of a key press event. The string will contain some combination of these keywords

numOn

Num Lock was on at the time of the key press event.

numOff

Num Lock was off.

capsOn

Caps Lock was on at the time of the key press event.

capsOff

Caps Lock was off.

scrollOn

Scroll Lock was on at the time of the key press event.

scrollOff

Scroll Lock was off.

lShift

The left shift key was down at the time of the key press event.

rShift

The right shift key was down.

lControl

The left control key was down at the time of the key press event.

rControl

The right control key was down.

lAlt

The left alt key was down at the time of the key press event.

rAlt

The right alt key was down.

Example:

The following example is from a fictitious customer order system. As the user is filling out a customer order using the customer order dialog, he has the F2 through F5 short cut keys available. F2 brings up a customer look up dialog. F3 looks up info on the product number entered in an edit control. F4 resets the form by clearing all the fields. F5 is used to print out the finished invoice.

::method initDialog

  ...

  -- Capture F2 key presses, but not Ctrl-F2 or Alt-F2, etc..
  self~connectKeyPress(onF2, self~vCode('F2'), "NONE")

  -- Same idea for F3, F4, and F5.  This uses the actual numeric value for the
  -- keys without bothering to use the VirtualKeyCodes class to translate.
  self~connectKeyPress(onF3, 114, "NONE")
  self~connectKeyPress(onF4, 115, "NONE")
  self~connectKeyPress(onF5, 116, "NONE")

  ...

::method onF2
  self~showCustomerLookupDialog

::method onF3

  prodNum = self~getEditControl(IDC_EDIT_PRODUCT)~getText
  if prodNum \== "" then self~showProductInfo(prodNum)

::method onF4
  self~resetAllFields

::method onF5
  self~printInvoice

ConnectFKeyPress

>>-aDialogControl~ConnectFKeyPress(--msgToRaise--)-------------><


The ConnectFKeyPress method connects a function key press to a method in the dialog instance. This works for function keys F2 through F24, without the shift, control, or alt keys also being pressed. The underlying Windows dialog must exist before this method can be invoked. This is a convenience method and is exactly equivalent to:

::method initDialog
  ...
  keys = self~vCode('F2') "-" self~vCode('F24')
  self~connectKeyPress(msgToRaise, keys, "NONE")

Arguments:

The required argument is:

msgToRaise

The method to be invoked for the F key press event.

Return value:

The return values are:

0

Success.

-2

The underlying mechanism in the Windows API that is used to capture key events failed.

-4

An (internal) problem with the dialog window.

-5

Memory allocation error in the underlying Windows API.

-6

The maximum number of connections has been reached.

-7

The msgToRaise method is already connected to a key down event for this dialog.

Example:

The following example is a variation on the example shown for the ConnectKeyPress method. It connects all the function keys to the same method and then determines what action to take by examining which key was pressed.

::method initDialog

  ...

  -- Capture all function key presses.
  self~connectFKeyPress(onFKey)

  ...

::method onFKey
  use arg keyPressed

  select
    when self~keyName(keyPressed) == 'F2' then self~showCustomerLookupDialog

    when keyPressed = 114 then do
      prodNum = self~getEditControl(IDC_EDIT_PRODUCT)~getText
      if prodNum \== "" then self~showProductInfo(prodNum)
    end

    when keyPressed = 115 then self~resetAllFields
    when keyPressed = 116 then self~printInvoice

    otherwise do
      -- Not interested in any other function keys
      nop
    end
  end

DisconnectKeyPress

>>-aBaseDialog~DisconnectKeyPress(--+--------------+--)--------><
                                    +--methodName--+

The DisconnectKeyPress method disconnects a key press event from a method that was previously connected using ConnectKeyPress. If no method name is specified than all key press event connections are removed. Otherwise, only the key press events connected to the specific method are removed.

Arguments:

The single optional argument is:

methodName

If methodName is specified, only the key press events connected to that method are disconnected. If the argument is omitted, then all key press events for the dialog will be disconnected.

Return value:

The return values are:

0

Success.

-1

The specified methodName is not connected to any key press events for this dialog.

-2

This return code can only occur when removing the connection for a single methodName. It indicates that after removing the connection, the underlying mechanism in the Windows API that captures the key press events could not be re-initialized. (It is doubtful this error would ever occur.)

Example:

The following example is a variation on the example shown for the ConnectKeyPress method. It builds on the fictitious customer order system. The F7 key saves the completed invoice into the system and enters a different phase of the companies business process. At this point (for whatever fictitious business reason) the fields can no longer be cleared and the user is not allowed to look up customer or product information. But, the user may still need to print the invoice. To prevent the accidental press of the hot keys causing the wrong action, those key presses are disconnected.

To demonstrate how key press connections can be added and removed through out the live time of the dialog, this example adds the F9 hot key. F9 starts a new order entry cycle and re-connects the hot keys used during the creation of a customer invoice. When the user then saves the next completed invoice, key press connections are removed, when she starts a new invoice key press connections are restored. This cycle could continue though out the day without the user ever closing the main dialog.


::method initDialog

  ...

  -- Capture F2 key presses, but not Ctrl-F2 or Alt-F2, etc..
  self~connectKeyPress(onF2, self~vCode('F2'), "NONE")

  -- Same idea for F3, F4, F5, and F7.  This uses the actual numeric value for
  -- the keys without bothering to use the VirtualKeyCodes class to translate.
  self~connectKeyPress(onF3, 114, "NONE")
  self~connectKeyPress(onF4, 115, "NONE")
  self~connectKeyPress(onF5, 116, "NONE")
  self~connectKeyPress(onF7, 118, "NONE")
  self~connectKeyPress(onF9, 120, "NONE")

  ...

::method onF2
  self~showCustomerLookupDialog

::method onF3

  prodNum = self~getEditControl(IDC_EDIT_PRODUCT)~getText
  if prodNum \== "" then self~showProductInfo(prodNum)

::method onF4
  self~resetAllFields

::method onF5
  self~printInvoice

::method onF7

  self~saveToDataBase
  self~disconnectKeyPress(onF2)
  self~disconnectKeyPress(onF3)
  self~disconnectKeyPress(onF4)

::method onF9

  self~resetAllFields
  self~connectKeyPress(onF2, 112, "NONE")
  self~connectKeyPress(onF3, 114, "NONE")
  self~connectKeyPress(onF4, 115, "NONE")

HasKeyPressConnection

>>-aBaseDialog~HasKeyPressConnection(--+--------------+--)--------><
                                       +--methodName--+

This method is used to query if a connection to a key press event already exists. It returns true or false so it can always be used in a boolean expression. If no argument is specified the method returns true if any key press events have been connected for the dialog and false otherwise. When the methodName argument is used, the query is only if there are key press events connected to the specified method.

Arguments:

The single optional argument is:

methodName

Query if any key press events are connected to this method.

Return value:

The returned value is always true or false.

true

A connection exists.

false

No connection exists.

Example:

The following example could come from a dialog where the user has the option to use hot keys or not. When the reset button is pushed the state of the dialog fields are reset. The hot keys enabled check box is set to reflect whether hot keys are currently enabled or not.


::method defineDialog

  ...
  self~addCheckBox(IDC_CHECK_FKEYSENABlED, , 30, 60, , , "Hot Keys Enabled")
  ...
  self~addButton(IDC_PB_RESET, 60, 135, 45, 15, "Reset", onReset)
  ...

::method onReset

  ...
  if self~hasKeyPressConnection then
    self~getCheckControl(IDC_CHECK_FKEYSENABlED)~check
  else
    self~getCheckControl(IDC_CHECK_FKEYSENABlED)~uncheck
  ...

ConnectButton

>>-aBaseDialog~ConnectButton(--id--,--msgToRaise--)------------><


The ConnectButton method connects a push button with a method.

Arguments:

The arguments are:

id

The ID of the dialog element.

msgToRaise

The message that is sent each time the button is clicked. You must provide a method with a matching name.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

Example:

::class MyDlgClass subclass UserDialog

::method Init
  self~init:super(...)
  self~ConnectButton(203, "SayHello")

::method SayHello
  say "Hello"

Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, use Init as the place for this connection - but not before init:super has been called.

ConnectBitmapButton

>>-aBaseDialog~ConnectBitmapButton(--id--,--+------------+--,--bmpNormal-->
                                            +-msgToRaise-+

>--+----------------------------------------------------------------------------+--)-><
   +-,--bmpFocused--+---------------------------------------------------------+-+
                    +-,--bmpSelected--+-------------------------------------+-+
                                      +-,--bmpDisabled--+-----------------+-+
                                                        +-,--styleOptions-+


The ConnectBitmapButton method connects a bitmap and a method with a push button. The given bitmaps are displayed instead of a Windows push button.

Arguments:

The arguments are:

id

The ID of the button.

msgToRaise

The message that is to be sent to this object when the button is clicked.

bmpNormal

The name (alphanumeric), resource ID (numeric), or handle (INMEMORY option) of a bitmap file. This bitmap is displayed when the button is not selected, not focused, and not disabled. It is used for the other button states in case the other arguments are omitted.

bmpFocused

This bitmap is displayed when the button is focused. The focused button is activated when the Enter key is pressed.

bmpSelected

This bitmap is displayed while the button is clicked and held.

bmpDisabled

This bitmap is displayed when the button is disabled.

styleOptions

One of the following keywords:

FRAME

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

USEPAL

Stores the colors of the bitmap file 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 any time. USEPAL is invalid for a bitmap loaded from a DLL.

INMEMORY

This option must be used if the named bitmaps are already loaded into memory by using the LoadBitmap method. In this case, bmpNormal, bmpFocused, bmpSelected, and bmpDisabled specify a bitmap handle instead of a file.

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. STRETCH has no effect for bitmaps loaded through a DLL.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

Example:

The following example connects a button with four bitmaps and a method:

      .
      .
      .
::method InitDialog
  self~ConnectBitmapButton(204, "BmpButtonClicked", ,
                           "AddBut_n.bmp", "AddBut_f.bmp", ,
                           "AddBut_s.bmp", "AddBut_d.bmp", "FRAME")
::method BmpButtonClicked
      .
      .
      .

See also method ChangeBitmapButton.

ConnectControl

>>-aBaseDialog~ConnectControl(--id--+---------------+--)-------><
                                    +-,--msgToRaise-+


The ConnectControl method connects a dialog control with a method.

Arguments:

The arguments are:

id

The ID of the dialog element.

msgToRaise

The message that is to be sent each time the button is clicked. Provide a method with the matching name.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

ConnectDraw

>>-aBaseDialog~ConnectDraw--(--id--+---------------+--)--------><
                                   +-,--msgToRaise-+


The ConnectDraw method connects the WM_DRAWITEM event with a method. A WM_DRAWITEM message is sent for owner-drawn buttons each time they are to be redrawn.

Arguments:

The arguments are:

id

The ID of the dialog control. If the ID is omitted, all drawing events of all owner-drawn buttons are routed to the method.

msgToRaise

The message that is to be sent each time the WM_DRAWITEM event occurs. Provide a method with the matching name. You can use USE ARG ID to retrieve the ID of the item that is to be redrawn.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

ConnectList

>>-aBaseDialog~ConnectList(--id--+---------------+--)----------><
                                 +-,--msgToRaise-+


The ConnectList method connects a list box, multiple list box, or combo box with a method. The method is called each time the user selects a new item from the list.

Arguments:

The arguments are:

id

The ID of the dialog element.

msgToRaise

The message that is to be sent each time the button is pressed. Provide a method with the matching name.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

ConnectListLeftDoubleClick

>>-aBaseDialog~ConnectListLeftDoubleClick(--id--,--msgToRaise--)-><


The ConnectListLeftDoubleClick method combines a left double-click within the list box with a method.

Arguments:

The arguments are:

id

The ID of the list box.

msgToRaise

The name of the method that is to be called.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

ConnectScrollBar

>>-aBaseDialog~ConnectScrollBar(--id--,--msgWhenUp--,--msgWhenDown-->

>--+--------------------------------------------------------------------+-->
   +-,--+-------------+--+--------------------------------------------+-+
        +-msgWhenDrag-+  +-,--+-----+--+----------------------------+-+
                              +-min-+  +-,--+-----+--+------------+-+
                                            +-max-+  +-,--+-----+-+
                                                          +-pos-+

>--+----------------------------------------------------------+-->
   +-,--+----------+--+-------------------------------------+-+
        +-progpgup-+  +-,--+----------+--+----------------+-+
                           +-progpgdn-+  +-,--+---------+-+
                                              +-progtop-+

>--+-------------------+--+------------------------------------+-->
   +-,--+------------+-+  +-,--+-----------+--+--------------+-+
        +-progbuttom-+         +-progtrack-+  +-,--progendsc-+


>--)-----------------------------------------------------------><


The ConnectScrollBar method initializes and connects a scroll bar to an Object Rexx object. Use this method in the InitDialog method.

Protected:

This method is protected.

Arguments:

The arguments are:

id

The ID of the scroll bar.

msgWhenUp

The method that is called each time the scroll bar is incremented.

msgWhenDown

The method that is called each time the scroll bar is decremented.

msgWhenDrag

The method that is called each time the scroll bar is dragged with the mouse.

min, max

The minimum and maximum values for the scroll bar.

pos

The current or preselected value.

progpgup

The method that is called each time the scroll bar is focused and the PgUp key is pressed.

progpgdn

The method that is called each time the scroll bar is focused and the PgDn key is pressed.

progtop

The method that is called each time the scroll bar is focused and the Home key is pressed.

progbottom

The method that is called each time the scroll bar is focused and the End key is pressed.

progtrack

The method that is called each time the scroll box is dragged.

progendsc

The method that is called each time the scroll box is released after the dragging.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

Example:

In the following example, scroll bar 255 is connected to three methods and initialized with 1 as the minimum, 20 as the maximum, and 6 as the current value:

::class MyDialog subclass UserDialog
     .
     .
     .
::method DefineDialog
self~ConnectScrollBar(255,"Increase","Decrease","Drag",1,20,6)
     .
     .
     .
::method Increase
     .
     .
     .
::method Decrease
     .
     .
     .
::method Drag
     .
     .
     .
/* see CombineElWithSB below for continuation */

ConnectAllSBEvents

>>-aBaseDialog~ConnectAllSBEvents(--id--,--Prog----------------->

>--+----------------------------------------+--)---------------><
   +-,--+-----+--+------------------------+-+
        +-min-+  +-,--+-----+--+--------+-+
                      +-max-+  +-,--pos-+


Connects all scroll bar events to one method.

Protected:

This method is protected.

Arguments:

The arguments are:

id

The ID of the scroll bar

Prog

The method that is called for all events sent by the scroll bar.

min, max

The minimum and maximum values for the scroll bar.

pos

The current or preselected value.

Return value:

-1

The specified symbolic ID could not be resolved.

0

No error.

addUserMsg

>>-aBaseDialog~addUserMsg(--msgToRaise--,--msgWindows----------->

>--+--------------------------------------------------------------------+-->
   +-,--filt1--+------------------------------------------------------+-+
               +-,--wParam--+---------------------------------------+-+
                            +-,--filt2--+-------------------------+-+
                                        +-,--lParam--+----------+-+
                                                     +-,--filt3-+

>--)-----------------------------------------------------------><


The addUserMsg method connects a Windows message with an Object Rexx method. This method is designed to be used by ooDialog programmers who are familiar with the Windows API.

You have to pass the Windows message ID and the two message parameters (wParam and lParam) to specify the exact event you want to catch. In addition, you can specify filters for each parameter. Filters are useful for catching more than one message or one parameter with one method.

Details for all Windows messages and their parameters are available in the Windows documentation. The numeric value of the message IDs (and possibly the message parameters) can be looked up in the Windows platform SDK.

Protected:

This method is protected. You can use it only within the scope of the BaseDialog class or its subclasses.

Arguments:

The arguments are:

msgToRaise

The message that is to be sent to the Object Rexx dialog object each time the specified Windows message is caught. Provide a method with the same name. The maximum size for a message is limited to 256 characters.

msgWindows

The message in the Windows environment that is to be caught.

filt1

This filter is used to binary AND the incoming Windows message.

wParam

This is the first parameter that must be passed with the Windows message.

filt2

This filter is used to binary AND the wParam argument.

lParam

This is the second message parameter.

filt3

This is the filter for lParam.

Example:

The following example shows an implementation of the ConnectList method:

::class BaseDialog
      .
      .
      .
::method ConnectList
  use arg msgToRaise, id
  self~addUserMsg(msgToRaise, "0x00000111", "0xFFFFFFFF", ,
                 "0x0001"||id~d2x(4), "0xFFFFFFFF", 0, 0)

Assume that this method is called with ID=254 and msgToRaise="ListChanged". After the ConnectList is executed, the ListChanged message is sent to the Object Rexx dialog object if the following conditions are true:

  • Message "0x00000111" (WM_COMMAND) is generated by Windows in answer to an event (for example, a button is clicked or a list has changed). The filter "0xFFFFFFFF" ensures that only that message is caught; if the filter were "0xFFFFEFFF", the message "0x00001111" would be caught as well.

  • The first message parameter is "0x000100FF". The first part, "0x0001", specifies the event, and the second part, "0x00FE" (equals decimal 254), specifies the dialog control where the event occurred. By using another filter it is possible to make more than one event a trigger for the ListChanged method; for example, filter "0xFFFFFFFE" would ignore the last bit of the ID, and this the same event for dialog item 255 would call ListChanged as well.

  • The second message parameter and its filter are ignored.

The following example invokes a user-defined method DoubleClick each time the left mouse button is double-clicked:

self~addUserMsg("DoubleCick","0x00000203","0xFFFFFFFF",0,0,0,0)