IAcceleratorTable

The IAcceleratorTable class represents a set of accelerator keys (also known as keyboard accelerators), which are shortcut keys for running an action. These keys are represented by IAcceleratorKey objects.

Any window can have an accelerator table associated with it. You can assign an accelerator table to a window using the IAcceleratorTable class. You can also set the accelerator table for a window by doing any of the following:

However, for your application to add, replace, remove, or query the keys in the accelerator table, you must use the IAcceleratorTable and IAcceleratorKey classes.

At runtime, Open Class Library checks all key presses, except those that are special to the operating system, for being possible accelerator keys (on the OS/2 platform, the operating system provides this support instead of Open Class Library). Open Class Library starts this checking at the window with the input focus, which might be a radio button or entry field. Open Class Library compares the key against the accelerator keys defined in the window's accelerator table. If the window has no accelerator table or the accelerator table does not contain a matching accelerator key, Open Class Library proceeds to the window's parent window, which might be a canvas. Open Class Library continues to compare the key against the accelerator table of each window in the parent chain until it finds a match or the failed match occurs at a frame window.

If Open Class Library finds a match, it discards the keyboard event, replacing it with a command event or help request (the action defined for the matched accelerator key). Open Class Library sends the new event to the window with the accelerator table that contains the matching accelerator key. If the failed match occurred at a frame window, Open Class Library dispatches the keyboard event to the window with the input focus.

See ICommandEvent for details on how an unprocessed command event propagates (most control windows do not reroute command events they receive). By default, an unprocessed help request propagates up the parent window chain until it reaches a frame window.
Note: The presentation system defines system accelerator keys that it will automatically enable based on the system menu items used by a frame window. You do not need to create an accelerator table to use the system accelerator keys, and these accelerator keys will not be reflected in the IAcceleratorTable object you create for a window.


IAcceleratorTable - Member Functions and Data by Group

Constructors & Destructor

You can construct, copy, assign, and destruct objects of this class.


[view class]
~IAcceleratorTable
public:
~IAcceleratorTable()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IAcceleratorTable


Overload 1
public:
IAcceleratorTable(const IResourceId& resId)

Use this constructor to create an IAcceleratorTable object that contains accelerator keys loaded from an accelerator table resource in a resource library.

resId
Identifies the accelerator table and resource library.

Exception

IAccessError An error occurred while querying the accelerator table from the presentation system.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IAcceleratorTable(bool systemQueueKeys)

Use this constructor to create an IAcceleratorTable object that contains the accelerator keys used by the system queue of the presentation system, or an IAcceleratorTable object that contains no accelerator keys.

systemQueueKeys
Flag that specifies how the accelerator table should be constructed. If false, the accelerator table is created empty. Otherwise, the accelerator table contains the system accelerator keys.

Note: Changing the contents of the IAcceleratorTable object does not alter the system accelerator keys.

Exception

IAccessError An error occurred while querying the accelerator table from the presentation system.

Supported Platforms

Windows OS/2 AIX
No Yes No


Overload 3
public:
IAcceleratorTable(const IAcceleratorTable& accelTbl)

Use this copy constructor to create an accelerator table with the same entries as the specified one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IAcceleratorTable(const IWindow* window = 0)

Use this constructor to create an IAcceleratorTable object that contains the accelerator keys used by the specified window. Passing a window to this constructor is equivalent to calling IWindow::acceleratorTable.

window
If 0, the accelerator table is constructed with no keys. Otherwise, the accelerator table contains the accelerator keys of the window.

Note: You can cause changes to the contents of the accelerator table to be immediately reflected by the window. See the functions that modify an accelerator table for more information.

Exception

IAccessError An error occurred while querying the accelerator table from the presentation system.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IAcceleratorTable(const IAccelTblHandle& accelTblHandle)

Use this constructor to create an IAcceleratorTable object that contains the accelerator keys in an existing accelerator table.

accelTblHandle
The handle of the existing accelerator table.

Note: Changing the contents of the IAcceleratorTable object does not alter the accelerator keys used by the existing accelerator table.

Exception

IAccessError An error occurred while querying the accelerator table from the presentation system.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
IAcceleratorTable& operator =( const IAcceleratorTable& accelTbl )

Use this assignment operator to initialize an accelerator table with the same entries as the specified one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Changing Keys

IAcceleratorTable allows you to modify a collection of accelerator keys by adding, replacing, or removing individual keys.

If you create an IAcceleratorTable object for a window, using the constructor that accepts a const IWindow* parameter or calling IWindow::acceleratorTable, you can cause any changes you make to the accelerator keys to be immediately reflected in the accelerator key processing of the window. Each of the functions that change a key has an updateWindow argument that allows you to control whether the contents of the accelerator table should be updated to the window.

If you defer updating the window, you can later call IWindow::setAcceleratorTable to update the accelerator keys used by the window.


[view class]
addKey
public:
bool addKey( const IAcceleratorKey& newKey, bool updateWindow = true )

Adds the specified accelerator key to the table. If the accelerator key was added, this function returns true. Otherwise the table remains unchanged, and the function returns false. The accelerator key will not be added if an existing entry in the table has the same keystroke (the same character or virtual key and the same Alt, Ctrl, Shift modifiers) as the key you are trying to add.

If the accelerator key was added, all other cursors for this accelerator table become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addOrReplaceKey
public:
bool addOrReplaceKey( const IAcceleratorKey& newKey, bool updateWindow = true )

Adds the specified accelerator key to the table, or replaces an existing entry. If the accelerator table does not contain an entry with the same keystroke (the same character or virtual key and the same Alt, Ctrl, Shift modifiers), this function adds the specified key and returns true. Otherwise it replaces the matching entry and returns false.

If the accelerator key was added, all other cursors for this accelerator table become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAllKeys
public:
IAcceleratorTable& removeAllKeys(bool updateWindow = true)

Empties the accelerator table so it contains no keys. Following this function, the accelerator table is still valid and can still be assigned to a window.

Following use of this function, all cursors for this accelerator table become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeKeyAt
public:
IAcceleratorTable& removeKeyAt( Cursor& cursor, bool updateWindow = true )

Removes the accelerator key at the cursor from the table.

All other cursors for this accelerator table become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeKeyLike
public:
bool removeKeyLike( const IAcceleratorKey& key, bool updateWindow = true )

Removes from the table the accelerator key entry with the same keystroke (the same character or virtual key and the same Alt, Ctrl, Shift modifiers) as the specified key. If an entry is removed, this function returns true. Otherwise the table remain unchanged, and the function returns false.

If an accelerator key was removed, all cursors for this accelerator table become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
replaceKeyAt
public:
IAcceleratorTable& replaceKeyAt( const Cursor& cursor, const IAcceleratorKey& newKey, bool updateWindow = true )

Replaces the accelerator key at the cursor with the specified accelerator key.

Following use of this function, all other cursors for this accelerator table become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Handle Management

IAcceleratorTable allow you to convert an accelerator table object to an IAccelTblHandle object for calling APIs of the presentation system. IAcceleratorTable also gives you a way to manage the lifetime of the underlying system handle.


[view class]
destroyHandle
public:
static void destroyHandle(IAccelTblHandle& accelTblHandle)

Destroys the specified accelerator table handle.

The IAccelTblHandle class represents a system accelerator table handle, which is a system resource. Use this function to destroy the accelerator table handle created and returned by the function IAcceleratorTable::handle. Only destroy an accelerator table handle when a window no longer needs the accelerator table.
Note: If you pass the accelerator table handle to IWindow::setAcceleratorHandle, you do not have to destroy it, since IWindow will manage it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handle
public:
IAccelTblHandle handle() const

Converts the accelerator table into an accelerator table handle. If you call this function, you are responsible for destroying the accelerator table handle when it is no longer needed. See destroyHandle for details.

Generally you do not need to call this function. You can assign an accelerator table to a window by calling IWindow::setAcceleratorTable, which will manage destroying the handle for you.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Querying Keys

IAcceleratorTable allows you to examine the collection of accelerator keys, including individual accelerator keys.


[view class]
containsKeyLike
public:
bool containsKeyLike(const IAcceleratorKey& key) const

Identifies if the accelerator table contains an entry with the same keystroke (the same character or virtual key and the same Alt, Ctrl, Shift modifiers) as the specified accelerator key. If the table contains a matching entry, this function returns true. Otherwise it returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
keyAt
public:
static IAcceleratorKey keyAt(const Cursor& cursor)

Returns a copy of the accelerator key at the cursor position. The cursor must be valid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
keyCount
public:
unsigned long keyCount() const

Returns the number of accelerator keys contained in the accelerator table.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
locateKeyLike
public:
bool locateKeyLike( const IAcceleratorKey& key, Cursor& cursor ) const

Searches the accelerator table for an entry with the same keystroke (the same character or virtual key and the same Alt, Ctrl, Shift modifiers) as the specified accelerator key. If the table contains a matching entry, this function returns true and points the cursor to the entry. Otherwise this function returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IAcceleratorTable - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data