IAcceleratorKey

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.


IAcceleratorKey - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IAcceleratorKey


Overload 1
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
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.

characterKey
The character key for the accelerator key. The first character of characterKey is used to define the accelerator key. Any other characters in the string are ignored.
modifier
A combination of modifier or auxiliary keys that the user must press along with the character key to run the action. IKey defines the set of available modifiers. Specifying a value of IKey::noModifier requires the user to press the character key by itself to run the accelerator key's action.
actionType
The type of action that the accelerator key runs.
commandId
The identifier for the application or system command that the accelerator key runs. This value is ignored if actionType has a value of ICommand::help.

Exception

IInvalidParameter You specified an uninitialized ICommand::ActionType value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
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.

virtualKey
The virtual key for the accelerator key. You can specify any virtual key code provided by the presentation system for this parameter, although IKey provides a list of portable virtual keys.
modifier
A combination of modifier or auxiliary keys that the user must press along with the virtual key to run the action. IKey defines the set of available modifiers. Specifying a value of IKey::noModifier requires the user to press the virtual key by itself to run the accelerator key's action.
actionType
The type of action that the accelerator key runs.
commandId
The identifier for the application or system command that the accelerator key runs. This value is ignored if actionType has a value of ICommand::help.

Exception

IInvalidParameter You specified an uninitialized ICommand::ActionType value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IAcceleratorKey(const ACCEL& accelerator)

Use this constructor to create an object from a data structure defined by the presentation system.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

accelerator is a reference to a unpublished structure.

OS/2 Considerations

accelerator is a reference to an _ACCEL structure.

Windows Considerations

accelerator is a reference to a tagACCEL structure.


[view class]
operator =
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Action Definitions

An accelerator key associates an action with a keystroke. The action can be an application command, system command, or help request.


[view class]
actionType
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
commandId
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setCommand
public:
IAcceleratorKey& setCommand(ICommand::CommandId commandId)

Defines the accelerator key to run the specified application command as its action.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

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.


[view class]
setHelpKey
public:
IAcceleratorKey& setHelpKey()

Defines the accelerator key to generate a contextual help request as its action.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setSystemCommand
public:
IAcceleratorKey& setSystemCommand( ICommand::CommandId commandId )

Defines the accelerator key to run the specified system command as its action.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

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.


Comparisons

Comparison functions indicate if two IAcceleratorKey objects are the same, or if they define actions for the same keystroke combination.


[view class]
isLike
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator !=
public:
bool operator !=(const IAcceleratorKey& key) const

Specifies if two accelerator keys use a different key combination or run a different action.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

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.


[view class]
operator <
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Specifies if two accelerator keys use the same key combination and run the same action.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

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.


[view class]
uniqueKeyFor
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Conversions

Conversion functions provide an alternative way to represent accelerator keys.


[view class]
asACCEL
public:
ACCEL asACCEL() const

Converts an accelerator key object into a data structure defined by the presentation system for use with its APIs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The accelerator key is converted into a structure defined by Open Class Library. Open Class Library does not externalize the format of this structure.

OS/2 Considerations

The accelerator key is converted into an _ACCEL structure.

Windows Considerations

The accelerator key is converted into a tagACCEL structure.
Note: Some information may be lost during this conversion, because a tagACCEL structure has no way to differentiate the different types of actions supported by IAcceleratorKey.


Key Definitions

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.


[view class]
character
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
keyModifier
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setKey

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.


Overload 1
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: To make Alt, Ctrl, or Shift an accelerator key, specify a virtual key value of IKey::kAlt, IKey::kCtrl, or IKey::kShift with IKey::noModifier. Do this instead of using IKey::kNoKey with a modifier.

Exception

IInvalidParameter You cannot specify IAccelerator::kNoKey as the virtual key.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

You can pass a KeySym value defined by the X Window System, for virtualKey.


Overload 2
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

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).


[view class]
virtualKey
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IAcceleratorKey - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data