Tutorial 33: How to Define and Use Key Events

This tutorial describes how to define and use a key event in Formspider. In a Formspider application, a keyEvent is triggered when the user presses a combination of keyboard buttons specified by the developer.

A keyEvent can be defined at the mainframe, dialog, panel or component level. A keyEvent defined at a higher level in the view hierarchy delegates down to lower levels. For example, a keyEvent defined at PanelA triggers if the defined key combination is pressed when the focus is in a component that resides in PanelB which is included in PanelA.

When a key is pressed the framework searches for an appropriate keyEvent starting from the focused component. It then climbs higher in the view hierarchy (focused component => panel (recursively) => dialog/mainframe).

You may click here to run the completed application.

Sample Application

Open Formspider IDE and click “New Application” under the “File” menu. The “New Application” dialog shows up. Enter “keyEvent” as the name of the application and “HR” as its datasource schema name. Leave other fields empty and click “OK”. This creates the “keyEvent” application with a default mainframe (called “mainFrame”) and a default panel (called “mainPanel”).

In the datasource schema of the application, create a package called “keyEvent_pkg” and open it in your favorite PL/SQL Editor. Add a procedure named “mainframe_shiftB” and ensure that the procedure is exposed in the package specification.

procedure mainframe_shiftB is
begin
  api_application.showpopupmessage('mainFrame''s SHIFT B keyEvent is fired');
end;

In the Formspider IDE expand the “Actions” accordion, select the “Actions” node and click the “+” button to create a new action. Alternatively, you may right click the “Actions” node and select “New” from the pop-up menu. The “New Action” dialog shows up. Enter “mainframe_shiftB” as the action name and “keyEvent_pkg.mainframe_shiftB” as the procedure. Click “OK” to save your action.

Creating “mainframe_shiftB” action

Expand the “Windows” node and then the “Mainframe” node from the “Containers” tree. Double click the “mainFrame” node to open it in the editor. To add the keyEvent, edit the “mainFrame” XML as the following;

<mainframe title="keyEvent" width="500" height="500">
  <events>
    <keyEvents>
      <keyEvent action="mainframe_shiftB" keyCombination="SHIFT B"/>
    </keyEvents>
  </events>
  <borderLayout>
    <cell docking="Center">
      <include panelName="mainPanel"/>
    </cell>
  </borderLayout>
</mainframe>

Create a new panel containing a button labeled “Fire”. To achieve this, expand the “Containers” accordion, select the “Panels” node in the navigation tree and click the “+” button. Alternatively, you may right click the “Panels” node and select the “New” menu item from the pop-up menu. The “New Panel” dialog shows up. Enter “subPanel” as the name of the panel and “Yellow” as the background color. Select “TitledBorder” option from border type combo box and enter “subPanel” as the border title. Click “OK” to create and open the panel in the editor.

Creating “subPanel”

Using the procedures below, define two keyEvents on the “subPanel” with “SHIFT A” and “SHIFT B” as keyCombination and define a keyEvent on the button labeled “Fire” with “SHIFT A” as keyCombination. Create the actions corresponding to each keyEvent using the procedure names as the name of the actions.

procedure subPanel_shiftA is
begin
  api_application.showpopupmessage('subPanel''s SHIFT A keyEvent is fired');
end;
procedure subPanel_shiftB is
begin
  api_application.showpopupmessage('subPanel''s SHIFT B keyEvent is fired');
end;
procedure subPanelButton_shiftA is
begin
  api_application.showpopupmessage('subPanel''s “Fire” button SHIFT A keyEvent is fired');
end;

The “subPanel” XML should look like the following;

<panel backgroundColor="Yellow" borderType="TitledBorder" borderTitle="subPanel">
  <events>
    <keyEvents>
      <keyEvent action="subPanel_shiftA" keyCombination="SHIFT A"/>
      <keyEvent action="subPanel_shiftB" keyCombination="SHIFT B"/>
    </keyEvents>
  </events>
  <borderLayout>
    <cell docking="Center">
      <button label="Fire">
        <events>
          <keyEvents>
            <keyEvent action="subPanelButton_shiftA" keyCombination="SHIFT A"/>
          </keyEvents>
        </events>
      </button>
    </cell>
  </borderLayout>
</panel>

Double click the “mainPanel” to open it in the editor. Using the following procedures, define two keyEvents on the “mainPanel” with “SHIFT A” and “SHIFT C” as keyCombination. Create the actions corresponding to each key event using procedure names as the name of the actions.

procedure mainPanel_shiftA is
begin
  api_application.showpopupmessage('mainPanel''s SHIFT A keyEvent is fired');
end;
procedure mainPanel_shiftC is
begin
  api_application.showpopupmessage('mainPanel''s SHIFT C keyEvent is fired');
end;

Include the “subPanel” in “mainPanel” and add a button labeled “test” into “mainPanel”. The “mainPanel” XML should look like the following;

<panel backgroundColor="Pink" borderType="TitledBorder" borderTitle="mainPanel">
  <events>
    <keyEvents>
      <keyEvent action="mainPanel_shiftA" keyCombination="SHIFT A"/>
      <keyEvent action="mainPanel_shiftC" keyCombination="SHIFT C"/>
    </keyEvents>
  </events>
  <tableLayout>
    <row>
      <cell hAlign="Full" vAlign="Full">
        <include panelName="subPanel"/>
      </cell>
    </row>
    <row>
      <cell>
        <button label="test"/>
      </cell>
    </row>
  </tableLayout>
</panel>

The screenshot of the application is below;

“keyEvent” application

Run the application to examine the results. If the user presses “shift and “A” buttons on the keyboard while the focus is on the button with the label “Fire”(you can click to the component to set the focus on it) then the “subPanelButton_shiftA” action executes. However, if the focus is on the “test” button, pressing the same keyboard buttons causes the action “mainPanel_shiftA” to execute. The action “subPanel_shiftA” is never executed.

Similarly, if the user presses “shift and “B” buttons while the focus is on the “Fire” button then the “subPanel_shiftB” action executes. On the other hand, if the focus is on the “test” button, pressing the same keyboard buttons causes the action “mainframe_shiftB” to execute.

Finally, if the user presses “shift and “C” buttons, “mainPanel_shiftC” action executes regardless of where the focus is.

You may click here to run the application.

Defining a Key Combination

The keys are split into two groups; modifiers (SHIFT, CONTROL and ALT) and virtual keys (rest of the keys). A keyCombination consists of one mandatory virtual key and one or more optional modifiers.

The list of modifiers is below:
SHIFT
CONTROL
ALT

The most commonly used virtual keys are:
A B C … Z
0 1 2 3 … 9
F1 F2 F3 … F12
NUMPAD0 NUMPAD1 … NUMPAD9
UP
DOWN
LEFT
RIGHT
ENTER
ESCAPE
HOME
END
PAGE_UP
PAGE_DOWN
ADD
DIVIDE
MULTIPLY
SUBTRACT
INSERT
DELETE
NUM_LOCK
CAPS_LOCK
SCROLL_LOCK
BACK_SPACE
COMMA
LESS
PAUSE

Below is a list of examples that define various key combinations;

keyCombination Result
“A” Correct. Pressing on A fires the event.
“SHIFT” Incorrect. One virtual key must be used in the keyCombination.
“SHIFT A” Correct. Pressing on shift and A fires the event.
“SHIFT A F1” Incorrect. Cannot use more than one virtual key in one keyCombination.
“SHIFT ALT ENTER” Correct. The event fires when the user presses shift, alt and enter.
  • Ramil

    How to make “ANY KEY”? eg live search

    • http://www.gerger.co Yalim K. Gerger

      Unfortunately, you cannot do “ANY KEY” at the moment.

  • Andrew

    Hello,
    What key is ‘LESS’?

    • İbrahim Sandallı

      Hi Andrew,

      It’s the “<" key.

      Regards,
      Ibrahim