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

~IAcceleratorKey

      public:
      ~IAcceleratorKey()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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.

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

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

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.

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

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.

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

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.

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

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.

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.

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.

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

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None