The following methods connect dialog control events to methods the programmer defines in the parent dialog class.
>>-aDialogControl~ConnectKeyPress(--msgToRaise--,--keys--+-----------+--)----><
+-,-filter--+
The ConnectKeyPress method connects a key down event, when the control has the keyboard focus, with a programmer defined method in the parent dialog of the control. The underlying Windows dialog must exist before this method can be invoked.
Note: This method is only available on systems running Windows XP or later. On earlier versions of Windows, the method will fail and return -4.
The arguments, return values, and behavior of this method are the same as those for the ConnectKeyPress method of the BaseDialog. However, the method of the BaseDialog connects any key down event when the dialog is the active window and this method of the DialogControl only connects the key down events when the specific control has the focus. See the ConnectKeyPress method of the BaseDialog for a detailed description of the arguments, return values, and behavior.
The arguments are:
The method to be invoked for the key down event.
The key, or list of keys, whose key down event will invoke the method specified by msgToRaise.
An optional filter to be applied to the key down event.
The return values are:
Success.
The underlying mechanism in the Windows API failed.
A problem with one of the arguments.
An (internal) problem with the dialog window.
An (internal) problem with the dialog administration.
This method is not supported by this version of Windows. Windows XP or later is required.
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 control.
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.
True if a shift key was down at the time of the event 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 could be from an application that supplies extended editing abilities for a multi-line edit control. When the edit control has the focus the user can use Alt-D to delete the current word, Ctrl-D to delete the current line, and Shift-Alt-D delete the current paragraph:
::method initDialog
expose editControl
editControl = self~getEditControl(IDC_EDTIT)
...
-- Capture the D key press when either the Alt or Control keys are
-- also pressed.
editControl~connectKeyPress(onDPress, self~vCode('D'), "ALT CONTROL")
...
::method onDPress
expose editControl
use arg key, shift, control, alt, info
-- Determine which of the key press combinations this is and take
-- appropriate action if it is a combination we are interested in.
isAltD = \ shift & \ control & alt
isCtrlD = \ shift & control & \ alt
isShiftAltD = shift & \ control & alt
if isAltD then self~deleteWord(editControl)
if isCtrlD the self~deleteLine(editControl)
if isShiftAltD then self~deleteParagraph(editControl)
>>-aDialogControl~ConnectFKeyPress(--msgToRaise--)-------------><
The ConnectFKeyPress method is a convenience method that connects all F key down events, when the control has the keyboard focus, with a programmer defined method in the parent dialog of the control. (This is for the standard function keys, F2 through F24.) The underlying Windows dialog must exist before this method can be invoked.
Note: This method is only available on systems running Windows XP or later. On earlier versions of Windows, the method will fail and return -4.
The arguments, return values, and behavior of this method are the same as those for the ConnectFKeyPress method of the BaseDialog. However, the method of the BaseDialog class connects any F key down event when the dialog is the active window and this method of the DialogControl class only connects the F key down events when the specific control has the focus. See the ConnectFKeyPress method of the BaseDialog for a more detailed description of the arguments, return values, and behavior.
The required argument is:
The method to be invoked for the key down event.
The return values are:
Success.
The underlying mechanism in the Windows API failed.
A problem with one of the arguments.
An (internal) problem with the dialog window.
An (internal) problem with the dialog administration.
This method is not supported by this version of Windows. Windows XP or later is required.
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 control.
The ooDialog method connected to the F key down event receives five arguments. This arguments are described in detail in the ConnectKeyPress method of the DialogControl.
The following example connects the F key down events for an edit control. The application determines which F key was pressed and takes appropriate action. For this application, the F3 key is the search key.
::method initDialog
expose editControl searchToken
editControl = self~getEditControl(IDC_EDIT)
editControl~connectFKeyPress(onFKey)
...
lastSearchToken = ""
...
::method onFKey
expose editControl searchToken
use arg key
select
when self~keyName(key) == 'F2' then do
...
end
when self~keyName(key) == 'F3' then do
description = "What word would you like to search for?"
searchToken = inputBox(description, "Search", searchToken)
if searchToken <> "" then
self~findAndHighlight(searchToken, editControl)
end
when self~keyName(key) == 'F4' then do
...
end
...
end
...
>>-aDialogControl~DisconnectKeyPress(--+--------------+--)-----><
+--methodName--+
The DisconnectKeyPress method disconnects a previously connected method with a key down event. If no method name is specified than all key down event connections are removed. Otherwise, only the key down events connected to the specific method are removed.
Note: This method is only available on systems running Windows XP or later. On earlier versions of Windows, the method will fail and return -4.
The arguments, return values, and behavior of this method are the same as those for the DisonnectKeyPress method of the BaseDialog. However, this method only works for connections made using the DialogControl's ConnectKeyPress method. It can not work with a connection made though the BaseDialog's method. See the DisconnectKeyPress method of the BaseDialog for a more detailed description of the behavior of this method.
The single optional argument is:
If methodName is specified, only the key down events connected to that method are disconnected. If the argument is omitted, then all key down events for the dialog control will be disconnected.
The return values are:
Success.
The underlying mechanism in the Windows API that captures the key down events failed to disconnect.
The specified methodName is not connected to any key down events for this control.
The underlying mechanism in the Windows API that captures the key down events was never installed.
This method is not supported by this version of Windows. Windows XP or later is required.
The following example could come from a dialog where the user can enable or disable the user of hot keys when she is working within an edit control. When the user presses the disable hot keys button, the dialog disables the hot keys for the edit control by removing the key press connections.
::method defineDialog ... self~addButton(IDC_PB_DISABLE, 60, 135, 65, 15, "Disable Hot Keys", onDisable) ... method onDisable editControl = self~getEditControl(IDC_EDIT) editControl~disconnectKeyPress
>>-aDialogControl~HasKeyPressConnection(--+--------------+--)-----><
+--methodName--+
This method is used to query if a connection to a key down event already exists.
Note: This method is only available on systems running Windows XP or later. On earlier versions of Windows, the method will fail and return -4.
The arguments, return values, and behavior of this method are the same as those for the HasKeyPressConnection method of the BaseDialog. However, this method only works for connections made using the DialogControl's ConnectKeyPress method. It can not work with a connection made though the BaseDialog's method. The HasKeyPressConnection method of the BaseDialog may provide some additional insight into the behavior of this method.
The single optional argument is:
When this argument is not used, HasKeyPressConnection queries if any key down event for the dialog control is connected to a method. When methodName is specified, the query checks for a connection to the specified method.
The returned value is always true or false.
A connection exists.
No connection exists.
The following example is from an application where the user can enable the use of hot keys when an edit control has the focus, or not. The reset push button is used in the application to reset the state of the dialog. One of the things done when the state is reset to check or uncheck a check box that shows 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
...
editControl = self~getEditControl(IDC_EDIT)
if editControl~hasKeyPressConnection then
self~getCheckControl(IDC_CHECK_FKEYSENABlED)~check
else
self~getCheckControl(IDC_CHECK_FKEYSENABlED)~uncheck
...