Introduction

Quick keys are ubiquitous across different applications and operating systems. They can be powerful but also a bit frustrating for users. Many users are not even aware of them. Those that are use them as a productivity tool. Using the mouse is nice, but if you want real speed, why reach over to the mouse to click on the ribbon or the menu and select bold when you can just hit Ctrl+B on the keyboard? With the mouse, I count at a minimum two or even three gestures to make the text bold. For a quick key, it is just one. Compared to MS Word, GoFiler has many, many more keys, in excess of 200 for Page View alone!

In the release of GoFiler 5.1c, I made substantial changes in the way quick keys are managed and processed. This has been a long time coming, and was a tedious job but it was well worth it. Custom keys can now be programmed at application startup and on the fly with Legato API commands.

What is a Quick Key?

Press Ctrl+S and in most applications, the current work is saved. Press Ctrl+C and the current item is copied to the clipboard. Each computer platform has variations of quick keys; for example, with a Mac you might hold the command key with another key, in Linux, the Ctrl key, and so on. Windows also features menu item keyboard shortcuts. Those start with the Alt or Menu key and are followed by a series or chord of keys. For example, Alt F S will save in most applications. Note that the “+” notation is absent. This is because Windows menu keys (menu shortcuts) are pressed in a series: Alt and then F and finally S. Quick keys are pressed at the same time, more or less by holding Ctrl and then pressing S as Ctrl+S. By convention, spelled keys like Home or Alt are bold italic.

Operationally, quick keys and menu key series are very different. For quick keys, Windows uses a thing called an accelerator table. As keys are pressed on the keyboard, they are passed through the Windows accelerator translate function. If the function captures a defined quick key, the keyboard actions are translated into a command or menu function. So, if Ctrl+S is defined as the FILE_SAVE menu function, then the numeric ID for FILE_SAVE is sent as a command just as if it was selected from the menu or ribbon. If the key combination is not translated, it is passed to the window that has keyboard focus for whatever processing it may perform.

Menu Shortcuts

Menu shortcuts work a bit differently than quick keys. After pressing the Alt key, all keyboard input is directed to the menu shortcut handler. The Windows API has a conventional handler, but for Novaworks’ applications using the ribbon, a custom handler is invoked (this is because the basic Windows API does not have a native ribbon tool). On a conventional menu, this will underline active characters in menu items. For Novaworks’ ribbons (and MS Word), little highlight boxes will appear indicating the active keys. For example, pressing Alt:

and then F:

and then S will result in the File | Save function being run. These keys are controlled by the application function database. Popup menus also use this by underlining the keys:

In this case, the O, U, F, and D keys become the next menu shortcut key. A similar scheme is used for dialogs:

Quick Keys

A quick key on the other hand is independent of the ribbon (note that in certain implementations of applications, however, disabling menu functions will disable quick keys). For example:

is the same function as described for the menu shortcut, but holding Ctrl and pressing S invokes the function. At a low level, the Windows API processes the keys using the accelerator table. The key command is then processed by the application frame of GoFiler.

Processing a Quick Key

As just discussed, the first step in a quick key action is accelerator processing. If defined, the key combination is translated to a menu function. Within the function group table, there are quick key functions, that is, an entry that is simply a quick key without related set of underlying application code to run. Quick key functions are passed to the quick key processor for a specific view.

Nearly all quick key positions are defined in the menu function table even if they are not mapped. The entry will have one of three codes:

M — Mapped — Set in accelerator table and the key can be programmed or mapped.

R — Reserved for Application — Set in accelerator table but permanently mapped to a function.

V — Processed by View Reserved — Not in the accelerator but defined as a place holder.

Mapped keys mean that the accelerator captures the command and relays it via a key menu function. For example, CtrlAlt+F will invoke the F_KEY_CONTROL_ALT function. If the function is not further mapped in a quick key table for the active view, nothing will happen.

Reserved keys are simple and fixed to a specific menu function. They are all the typical key combinations, such as open, save, copy, paste, cut, etc. Many of these functions either do not require a view or are universal.

Finally, View Reserved types are not mapped in the accelerator table but may be in the function list to aid in documentation. It is expected that the view will directly capture the key. For example, this could include Backspace or Enter.

The figure below helps to illustrate the process:

As key messages come in, they are passed to the Windows TranslateAccelerator function. It collects enough information to either accept it as a translated quick key or to allow the key process to be passed along as keyboard messages. A key message such as Tab or A is passed on to be potentially be processed as a virtual key or as a character (for example, A without a Shift is translated to the character ‘a’). For a command, it is processed just like a menu or ribbon command. If the function is application related, it is processed by the application desktop or frame. If a view is active, certain functions are processed by the view. Mapped quick keys, for example F_K_CONTROL_ALT, are passed to the quick key processor. The quick key processor in turn will scan the quick key function table and translate to another function or just ignore it if the key is not defined.

There is one last aspect to the quick key function table. The table can further refine a quick key via a quick key chord. For example, Ctrl+U G, toggles a rule in a table. This is invoked by pressing Ctrl+U and then the G key. Adding an additional key to a quick key makes the quick key chord.

Quick Key Tables

Each view that supports the quick key class has a quick key table. The table is loaded at the start of the application. For each view, the application will look in the user area, the program files area, and, if it cannot locate a table, it will load the internal table. The table is coded in an XML Data Sheet (XDS file) in the following form:

The table takes the following form starting after row 5 (the fields must be in the specified order):

Primary Key Function Name — This is the name of a quick key as defined in the menu function table.

File Type Context — If the view supports multiple file types (such as Code View), this is the ASCII code for the file format. Up to eight matching file formats may be specified and separated by spaces.

Chord 1 Description and Key — If multiple functions are assigned to the quick key, a chord can be defined. The first in the series needs a description, which must be located on the first letter.

Chord 2 Description and Key — A second ground can be added to further refine key chord.

Translated Function — This is the menu function to which the key translates.

View Context — If the view supports a context, it can be placed here to further differentiate the function. For example, in Page View, placing PRE in the field means the function only applies if the caret is located in a preformatted area.

Group or Class — This is used for control and documentation.

Key Description — This is used for documentation.

Each table is available from Technical Support for clients to modify and implement. Let’s look more closely at a key chord combination (I have collapsed some of the columns to make the graphic more readable):

First, this group contains various permutations of the B key. B and Sh+B are view reserved for obvious reasons. Ctrl+B maps to the common bold function (row 64). Rows 65 to 69 contain background key chords: ShAlt+B with C P R S and T options for background on cell, paragraph, row, striping and table. The first item has the description that will appear in the status bar. Let’s look at two-tiered chord:

For Ctrl+T N, rows 177 to 183 all have “N”, but when N is pressed, the next key chord message is displayed in the status bar, and A B C E O R and T can then be pressed. Note that additional first tier chords follow N.

The table is sorted on load. However, the description must be associated with the lowest letter in the group. Let’s look at the context:

To define separate functionality for script programming versus EDGAR ASCII editing or HTML editing, the file types are provided for various Fn keys. Note there can be more than one per key. When there is a file type context, it is also used for key selection.

Finally, the group class and context field are used for documentation. They are not used in operation but can be enumerated as part of the quick key properties. For example:

I will cover the enumeration scripts in a later blog. Needless to say, the group is used to categorize the major head and subheadings. In addition, sort codes can be added to the Key Description to help order the data within the script.

Conclusion

This is a basic introduction to quick keys. To get get a copy of the quick tables for modification, contact Technical Support. They can also help with customization and aid in implementation. In the next blog, I will discuss how to add or change quick keys on the fly with Legato.

Scott Theis is the President of Novaworks and the principal developer of the Legato scripting language. He has extensive expertise with EDGAR, HTML, XBRL, and other programming languages.

Additional Resources

Novaworks’ Legato Resources

Legato Script Developers LinkedIn Group

Primer: An Introduction to Legato