The following methods create a connection between an event of the Windows dialog, or a dialog control, and a method of the ooRexx 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.
For push buttons you connect a method to the button. The connected method is called each time the button is pressed (clicked.)
List boxes, multiple list boxes, and combo boxes can also be connected to a method that is called each time a line in the box is selected.
For a scroll bar you can specify different methods that are called depending on the user action. The user can click on the arrow buttons, drag the thumb, or use direction keys.
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.
>>-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.
The only argument is:
The message that is to be sent each time the dialog is resized. Provide a method with a matching name.
This method does not return a value.
::class MyDlgClass subclass UserDialog
::method Init
self~init:super(...)
self~ConnectResize("OnSize")
::method OnSize
use arg sizeEvent, sizeinfo /* sizeinfo contains information about the
new width and height */
msg = self~PeekDialogMessage
if msg~left(6) = "ONSIZE" then return /* not the last size
event message */
w = binaryand(sizeinfo, "0x0000FFFF") / self~FactorX
h = binaryand(sizeinfo, "0xFFFF0000") % X2D("FFFF") / self~FactorY
say "New width=" w ", new height=" hThis 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.
>>-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.
The only argument is:
The message that is to be sent each time the dialog is moved. Provide a method with a matching name.
This method does not return a value.
::class MyDlgClass subclass UserDialog
::method Init
self~init:super(...)
selfConnectMove("OnMove")
::method OnMove
use arg dummy, posinfo /* posinfo contains information
about the new position */
msg = self~PeekDialogMessage
if msg~left(6) = "ONMOVE" then return /* not the last move
event message */
w = binaryand(data, "0x0000FFFF") / self~FactorX
h = binaryand(data, "0xFFFF0000") % X2D("FFFF") / self~FactorY
say "New x=" x ", new y=" yNote: 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.
>>-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.
The only argument is:
The message that is to be sent each time the coordinates of the dialog are changed. Provide a method with a matching name.
This method does not return a value.
::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.
>>-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.
The only argument is:
The message that is to be sent each time the mouse capture is lost in the dialog. Provide a method with a matching name.
This method does not return a value.
>>-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.)
The only argument is:
The name of the method that is to be invoked.
No error.
An (internal) error prevented the message from being connected to a method.
The ooDialog method connected to the Help event will receive the following four arguments in the order listed:
The resource ID of the dialog, dialog control, or menu item that had the focus when the F1 key was pressed.
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.
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.
The y coordinate of the mouse at the time the F1 key was pressed.
::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>>-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.
The arguments are:
The name of the method that is to be invoked when the key press event happens.
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 keys.
All Function keys, other than F1. (In Windows the F1 key is the help key and the ConnectHelp method should be used for F1.)
The keys A though Z.
The keys 0 through 9. Note that these are the normal number keys, not the keypad numbers on an enhanced keyboard.
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.
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")
The return values are:
Success.
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
The underlying mechanism in the Windows API that is used to capture key events failed.
An (internal) problem with the dialog window.
Memory allocation error in the underlying Windows API.
The maximum number of connections has been reached.
The msgToRaise method is already connected to a key down event for this dialog.
The ooDialog method connected to the key press event will receive the following five arguments in the order listed:
The numeric code of the key pressed.
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.
True if a control key was down at the time of the key press, false if it was not.
True if an alt key was down at the time of the key press, false if it was not.
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
Num Lock was on at the time of the key press event.
Num Lock was off.
Caps Lock was on at the time of the key press event.
Caps Lock was off.
Scroll Lock was on at the time of the key press event.
Scroll Lock was off.
The left shift key was down at the time of the key press event.
The right shift key was down.
The left control key was down at the time of the key press event.
The right control key was down.
The left alt key was down at the time of the key press event.
The right alt key was down.
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
>>-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")The required argument is:
The method to be invoked for the F key press event.
The return values are:
Success.
The underlying mechanism in the Windows API that is used to capture key events failed.
An (internal) problem with the dialog window.
Memory allocation error in the underlying Windows API.
The maximum number of connections has been reached.
The msgToRaise method is already connected to a key down event for this dialog.
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
>>-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.
The single optional argument is:
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.
The return values are:
Success.
The specified methodName is not connected to any key press events for this dialog.
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.)
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")
>>-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.
The single optional argument is:
Query if any key press events are connected to this method.
The returned value is always true or false.
A connection exists.
No connection exists.
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
...
>>-aBaseDialog~ConnectButton(--id--+---------------+--)--------><
+-,--msgToRaise-+
The ConnectButton method connects a push button with a method.
The arguments are:
The ID of the dialog element.
The message that is sent each time the button is clicked. You should provide a method with the matching name.
The specified symbolic ID could not be resolved.
No error.
::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.
>>-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.
The arguments are:
The ID of the button.
The message that is to be sent to this object when the button is clicked.
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.
This bitmap is displayed when the button is focused. The focused button is activated when the Enter key is pressed.
This bitmap is displayed while the button is clicked and held.
This bitmap is displayed when the button is disabled.
One of the following keywords:
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.
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.
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.
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.
The specified symbolic ID could not be resolved.
No error.
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.
>>-aBaseDialog~ConnectControl(--id--+---------------+--)-------><
+-,--msgToRaise-+
The ConnectControl method connects a dialog control with a method.
The arguments are:
The ID of the dialog element.
The message that is to be sent each time the button is clicked. Provide a method with the matching name.
The specified symbolic ID could not be resolved.
No error.
>>-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.
The arguments are:
The ID of the dialog control. If the ID is omitted, all drawing events of all owner-drawn buttons are routed to the method.
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.
The specified symbolic ID could not be resolved.
No error.
>>-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.
The arguments are:
The ID of the dialog element.
The message that is to be sent each time the button is pressed. Provide a method with the matching name.
The specified symbolic ID could not be resolved.
No error.
>>-aBaseDialog~ConnectListLeftDoubleClick(--id--,--msgToRaise--)-><
The ConnectListLeftDoubleClick method combines a left double-click within the list box with a method.
The arguments are:
The ID of the list box.
The name of the method that is to be called.
The specified symbolic ID could not be resolved.
No error.
>>-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.
This method is protected.
The arguments are:
The ID of the scroll bar.
The method that is called each time the scroll bar is incremented.
The method that is called each time the scroll bar is decremented.
The method that is called each time the scroll bar is dragged with the mouse.
The minimum and maximum values for the scroll bar.
The current or preselected value.
The method that is called each time the scroll bar is focused and the PgUp key is pressed.
The method that is called each time the scroll bar is focused and the PgDn key is pressed.
The method that is called each time the scroll bar is focused and the Home key is pressed.
The method that is called each time the scroll bar is focused and the End key is pressed.
The method that is called each time the scroll box is dragged.
The method that is called each time the scroll box is released after the dragging.
The specified symbolic ID could not be resolved.
No error.
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 */>>-aBaseDialog~ConnectAllSBEvents(--id--,--Prog----------------->
>--+----------------------------------------+--)---------------><
+-,--+-----+--+------------------------+-+
+-min-+ +-,--+-----+--+--------+-+
+-max-+ +-,--pos-+
Connects all scroll bar events to one method.
This method is protected.
The arguments are:
The ID of the scroll bar
The method that is called for all events sent by the scroll bar.
The minimum and maximum values for the scroll bar.
The current or preselected value.
The specified symbolic ID could not be resolved.
No error.
>>-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.
This method is protected. You can use it only within the scope of the BaseDialog class or its subclasses.
The arguments are:
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.
The message in the Windows environment that is to be caught.
This filter is used to binary AND the incoming Windows message.
This is the first parameter that must be passed with the Windows message.
This filter is used to binary AND the wParam argument.
This is the second message parameter.
This is the filter for lParam.
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)