Queue keyboard event

Syntax

Queue keyboard event {key-sequence or calculation}

Description

This command queues a "keyboard" event or series of events. It simulates keyboard entry by the user from within your methods. You can enter the key sequence in several ways:

1. Recording a key sequence
   When your cursor is positioned at the end of the command, you can press the Helper button (at the bottom left of the editor panel), or press Alt-H on Windows or Cmnd+Opt+H on macOS to open the Key Sequence Recorder. You can use the Start Recording and Stop Recording buttons to specify the keys to be generated. During the recording, all key events are echoed to the Key sequence parameter field, and are not acted on by Omnis in any other way (for example, pressing Ctrl/Cmnd-Q will NOT suddenly quit Omnis). Click events, however, behave normally so you can click on Stop recording button.

2. Entering into the text field
   You can enter the text representation manually to generate the keys. Syntax checking is done at design time. When recording is off, you can edit the Key sequence parameter manually. This lets you delete key combinations or enter key sequences by hand. Since spaces are used to automatically separate key presses, the special key name SPACE will have to be manually entered to generate a "space key" event.

3. Specifying a calculation
   You can enter a calculation like concatenating text fields, which will contain the text representation of the keys to be generated. Syntax checking is done at runtime. Incorrect key sequence syntax will result in a runtime error. When you use a calculation, the general calculation syntax applies, which is checked at design time.

Key names

Special keys or key combinations are represented using the names of the keys. When a given key combination is run on another platform, a conversion is carried out internally so that, for example, alt-c under Windows becomes opt-c under MacOSX. The list below summarizes the conversion:

Windows and Linux

Modifier Key names: shift-, alt-, ctrl-

Special Key names: Space, Up, Down, Left, Right, PgUp, PgDn, PgLeft, PgRight, Home, End, Tab, Return, Enter, Bkspc, Clear, Cancel, Minus, Move, Del, Ins, Exit

MacOSX

Modifier Key names: shift-, opt-, com-

Special Key names: Space, Up, Down, Left, Right, PgUp, PgDn, PgLeft, PgRight, Home, End, Tab, Return, Enter, Bkspc, Clear, Cancel, Minus, Move, Del.

Set current field

If queued key events are intended for an edit field or a list, it is advisable to queue a "set current field" event before generating the key events. On the other hand, general key events, for example, menu accelerators or shortcut keys, do not require a specific current field.

Key event restrictions under Windows and Linux

Under Windows, you can use alt-<key> sequences to select menu options from the menu bar. Since the menu bar is handled by the operating environment, and Queue keyboard event generates internal Omnis events, queuing alt-<key> events will NOT drive the menu bar. Thus, for example, queuing alt-f will not drop the File menu.

As a consequence of the above restriction, evKey events are not generated for queued alt-<letter> sequences either.

A second situation where evKey events are not generated is when you queue alt-control-<letter> events. These key combinations are normally used to produce accented characters, and this facility exists only in some but not all keyboards. Since Windows does not generate character messages, these events do not generate evKey.

WARNING When queuing events on pushbuttons there is a danger of recursion under Windows and Linux, but also under macOS if buttons have been given Windows behavior, that is, they get the focus. Normally, when the focus is on a pushbutton, you can activate it by pressing the space bar. If that pushbutton receives an evClick event and has a queued space key event WITHOUT a set current field, the space key event will be sent back to the pushbutton, thereby generating another evClick, which again activates the space key event. Infinite recursion occurs, resulting in a crash.

Key event restriction under macOS

Under macOS, you use opt-<letter> to generate extended characters. When queued key events include such opt-<letter> sequences, evKey is not generated.

Example

# button method
On  evClick
  Open window instance wMyWindow
  Queue keyboard event {y o u r n a m e}
 # paste button 
On  evClick
  Queue keyboard event {ctrl-V}