The IAcceleratorKey class represents a shortcut key for running an action. Such a key is called a keyboard accelerator or accelerator key. An accelerator key is defined as a keystroke and the action that the keystroke runs. An example of a keyboard accelerator is Alt+F4. Pressing this key combination typically runs the Close system command, which closes the active frame window.
The keystroke consists of a character key or virtual key, and an optional modifier. A character key has the character it types on its key top, such as A or a. A virtual key, such as Enter or F5, generally does not have an associated character value. Along with a character key or virtual key, you can optionally require the user to press a modifier, which can be the Shift, Alt, or Ctrl key, or a combination of these keys.
The action that an accelerator key runs can be an application command, system command, or a help request. Although a standard use for an accelerator key is to run the action defined for a menu item, an accelerator key does not require a corresponding menu item. Defining an accelerator key does not cause the text of a menu item that invokes the same action to be modified in any way. You are responsible for changing the text of a menu item if you want it to identify an accelerator key (for example, by changing the text in a menu resource or by calling IMenuItem::setText).
You use IAcceleratorKey objects to build, query, and modify the contents of an IAcceleratorTable object.
You can construct, copy, assign, and destruct objects of this class.
![]() |
public:
~IAcceleratorKey()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IAcceleratorKey(const IAcceleratorKey& key)
Use this copy constructor to create an accelerator key object from an existing IAcceleratorKey object. The key combination and action used by the new object are copied from the existing object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IAcceleratorKey( const IString& characterKey, const IKey::KeyModifier& modifier, ICommand::ActionType actionType = ICommand::applicationCommand, ICommand::CommandId commandId = 0 )
Use this constructor to create an accelerator key for a character key.
IInvalidParameter | You specified an uninitialized ICommand::ActionType value. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IAcceleratorKey( IKey::VirtualKey virtualKey, const IKey::KeyModifier& modifier, ICommand::ActionType actionType = ICommand::applicationCommand, ICommand::CommandId commandId = 0 )
Use this constructor to create an accelerator key for a virtual key.
IInvalidParameter | You specified an uninitialized ICommand::ActionType value. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IAcceleratorKey()
Use the default constructor to create an empty accelerator key (one that has no key combination and runs no action). Use the setKey function to assign the accelerator key a key combination. Use the setCommand, setSystemCommand, or setHelpKey function to assign it an action.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IAcceleratorKey(const ACCEL& accelerator)
Use this constructor to create an object from a data structure defined by the presentation system.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
accelerator is a reference to a unpublished structure.
accelerator is a reference to an _ACCEL structure.
accelerator is a reference to a tagACCEL structure.
![]() |
public:
IAcceleratorKey& operator =(const IAcceleratorKey& key)
Use this assignment operator to set the value of an existing accelerator key object equal to that of another IAcceleratorKey object. This function copies both the key combination and action.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
An accelerator key associates an action with a keystroke. The action can be an application command, system command, or help request.
![]() |
public:
ICommand::ActionType actionType() const
Identifies if the accelerator key runs an application command, system command, or invokes help. You can use this function to determine whether to treat the value returned by IAcceleratorKey::commandId as the identifier of an application or system command.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
ICommand::CommandId commandId() const
If the accelerator key runs an application or system command, this function returns the identifier of the command. If the accelerator key invokes help, this function returns 0. You can determine the type of action that the key runs using IAcceleratorKey::actionType.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IAcceleratorKey& setCommand(ICommand::CommandId commandId)
Defines the accelerator key to run the specified application command as its action.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Limit commandId to values under 0xF000 to avoid conflicts with system command identifiers. If you use a system command identifier, the resulting action will be a system command instead of an application command.
![]() |
public:
IAcceleratorKey& setHelpKey()
Defines the accelerator key to generate a contextual help request as its action.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IAcceleratorKey& setSystemCommand( ICommand::CommandId commandId )
Defines the accelerator key to run the specified system command as its action.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The value of commandId must be a system command provided by the Windows operating system. If you use an application command identifier, the resulting action will be an application command instead of a system command.
Comparison functions indicate if two IAcceleratorKey objects are the same, or if they define actions for the same keystroke combination.
![]() |
public:
bool isLike(const IAcceleratorKey& key) const
Identifies if two accelerator keys use the same key combination. This function returns true if both use the same character key or virtual key, and the same combination of Alt, Ctrl, and Shift. This function ignores any differences in the actions that the two accelerator keys run.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool operator !=(const IAcceleratorKey& key) const
Specifies if two accelerator keys use a different key combination or run a different action.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
This function also accounts for the AF_SCANCODE and AF_LONEKEY flags that IAcceleratorKey does not externalize. These flags are kept for IAcceleratorKey objects constructed from an _ACCEL structure or queried from an IAcceleratorTable object that was constructed from a Presentation Manager accelerator table.
![]() |
public:
bool operator <(const IAcceleratorKey& key) const
Identifies if two accelerator keys use a different key combination or run a different action, and specifies an ordering for placing the accelerator keys into a sorted sequence.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool operator ==(const IAcceleratorKey& key) const
Specifies if two accelerator keys use the same key combination and run the same action.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
This function also accounts for the AF_SCANCODE and AF_LONEKEY flags that IAcceleratorKey does not externalize. These flags are kept for IAcceleratorKey objects constructed from an _ACCEL structure or queried from an IAcceleratorTable object that was constructed from a Presentation Manager accelerator table.
![]() |
protected:
static unsigned long uniqueKeyFor( const IAcceleratorKey& key )
Returns a value that uniquely identifies the key combination used by the accelerator key. IAcceleratorTable uses this value to place IAcceleratorKey objects into a keyed set.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Conversion functions provide an alternative way to represent accelerator keys.
![]() |
public:
ACCEL asACCEL() const
Converts an accelerator key object into a data structure defined by the presentation system for use with its APIs.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The accelerator key is converted into a structure defined by Open Class Library. Open Class Library does not externalize the format of this structure.
The accelerator key is converted into an _ACCEL structure.
The accelerator key is converted into a tagACCEL structure.
Note:
An accelerator key associates an action with a key combination. The keystroke can be a character or virtual key that is optionally combined with the Alt, Ctrl, and/or Shift keys.
![]() |
public:
IString character() const
Returns the character key defined for the accelerator key. If the accelerator key uses a virtual key instead of a character key, this function returns a 0-length IString.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IKey::KeyModifier keyModifier() const
Returns the modifier or auxiliary keys defined for the accelerator key. The user must press these keys with the character or virtual key to run the action of the accelerator key. The returned value will be IKey::noModifier or some combination of the IKey::alt, IKey::ctrl, and IKey::shift values.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
Assigns the specified key combination to the accelerator key. The keystroke consists of a character or virtual key, and an optional modifier key, such as Alt, Ctrl, Shift, or a combination of any of these keys.
public:
IAcceleratorKey& setKey( IKey::VirtualKey virtualKey, const IKey::KeyModifier& modifier = IKey::noModifier )
Use this function to assign a virtual keystroke to the accelerator key.
Note:
IInvalidParameter | You cannot specify IAccelerator::kNoKey as the virtual key. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
You can pass a KeySym value defined by the X Window System, for virtualKey.
public:
IAcceleratorKey& setKey( const IString& accelKey, const IKey::KeyModifier& modifier = IKey::noModifier )
Use this function to define a character key combination for the accelerator key. The first character held by accelKey is used as the character key. Any other characters in the string are ignored.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Only character values in the range from 0x20 up to and including 0x7E are processed. Any other character is ignored and treated as a null character.
To create an accelerator key with any other character, including characters not in the Latin I character set, use the version of IAcceleratorKey::setKey that takes an IKey::VirtualKey value. Specify the KeySym value for the character, as defined by the X Window System, as the virtual key value (for example, XK_Atilde).
![]() |
public:
IKey::VirtualKey virtualKey() const
Returns the virtual key defined for this accelerator key.
If the accelerator key uses a platform-dependent virtual key, this function returns a value other than one of those provided by IKey.
If the accelerator key uses a character key instead of a virtual key, this function returns IKey::kNoKey. You can also use the function IAcceleratorKey::character to determine if the accelerator key uses a character key.
Windows | OS/2 | AIX |
Yes | Yes | Yes |