OnKey Events on Forms

Description

Handling key events, macro recorder example, and an application help example.

Handling Key Events 

The general approach to intercepting and handling keystrokes in your application is as follows:

  1. Test to see what key was pressed by examining the value in a_user.key.value. Keys such as 'Backspace', 'Up', 'Down' etc. will be represented using a curly bracket syntax (e.g. {Backspace})

  2. Tip: To get a list of key codes, right click in the Code Editor and select Genies, Insert Key code.. from the menu.

  3. Write code that you want to execute if a particular key was pressed. Remember that your event handler will be called multiple times for each key event ('down', 'repeat' and 'up'). The value of the key event is in a_user.key.event.

  4. If you want to prevent Alpha Anywhere from passing the key on to the form, set a_user.key.handled to .t.. If this value is .f. then the key will be passed onto the form. Otherwise, the keystroke will not be passed onto the form.

For example, this code intercepts the Shift+F10 key. The keystroke is NOT passed onto the form.

IF a_user.key.value = "{+F10}" THEN
    'set a_user.key.handled = .t. to prevent the key stroke being passed on to the Form
    a_user.key.handled = .t.
    IF a_user.key.event = "down" THEN
        ui_msg_box("","User pressed shift+F10")
    END IF
END IF

Macro Recorder Example 

Here is an example script that records and plays back keystroke macros within a form. The script is defined in a form's OnKey event.

This script can be found in the Samples\Xbasic directory off the directory in which you installed Alpha Anywhere. Open the Xbasic database and then open the MacroExample form.

Application Help Example 

The following script is presented as an example of how to call the Windows API. as a practical matter, in V5 the following script is obsolete because V5 has a WINHELP_SHOW() function.

Here is a collection of examples scripts that intercepts the F1 key and lets the application redefine HELP. The help topic is set by each field's OnArrive event, and cleared on the field's OnDepart event. In this example, it is assumed that the Xbasic application programmer has provided a windows HELP file. :

These scripts can be found in the Samples\Xbasic directory off the directory in which you installed Alpha Anywhere. Open the Xbasic database and then open the CustomHelp form.

OnKey event for form:

' Declare the WinHelp function - Published windows
' function name is WinHelpA (A is for ASCII single byte)
' there is also a WinHelpW that is multibyte (i.e. Unicode)
' WinHelp is the name our Xbasic program uses
declare user32 [email protected] LLCLL
' Define some useful constants
constant global HELP_COMMAND = 258
constant global HELP_KEY    = 257
constant global HELP_PARTIAL_KEY = 261
constant global HELP_INDEX  = 3
dim shared helptopic as C
HELP_FILENAME = :a5.get_path()+ "\invoice.hlp"
' If the user hit the {F1} key...
if (A_USER.KEY.value = "{F1}" ) then
   ' eat the key and invoke help with our help file
   A_USER.KEY.handled = .T.
   if (A_USER.KEY.event = "down") then
        if (helptopic <> "") then
          ' if a topic is defined, use the topic in the help call
           WinHelp(0, HELP_FILENAME, HELP_PARTIAL_KEY,helptopic)
      else
         ' If no help topic defined, then just show an index
         WinHelp(0, HELP_FILENAME, HELP_INDEX,"")
      end if
  end if
end if

OnArrive event for INV_NO field:

' Set the topic to be invoice numbers
dim shared helptopic as C
helptopic = "Invoice Numbers"

OnDepart event for INV_NO field:

' No longer on the invoice number field, so un-define the topic
dim shared helptopic as C
helptopic = ""

OnArrive event for Vendor_ID field:

' Set the topic to be Vendor
dim shared helptopic as C
helptopic = "Vendor"

OnDepart event for Vendor_ID field:

' No longer on the Vendor_ID field, so
' undefine the topic
dim shared helptopic as C
helptopic = ""

See Also