---
name: "Prima::KeySelector"
section: "3"
platform: "linux"
package: "libprima-perl"
version: "1.28-1.3+b3"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/Prima::KeySelector"
---

# Prima::KeySelector(3)

key combination widget and routines

## NAME

Prima::KeySelector - key combination widget and routines

## DESCRIPTION

The module provides a standard widget for selecting a user-defined key combination. The widget class allows import, export, and modification of key combinations.

The module provides a set of routines, useful for conversion of a key combination between representations.

## SYNOPSIS

```
        my $ks = Prima::KeySelector-> create( );
        $ks-> key( km::Alt | ord('X'));
        print Prima::KeySelector::describe( $ks-> key );
```

## API

### Properties

- key INTEGER

  Selects a key combination in integer format. The format is described in "Hot key" in Prima::Menu, and is a combination of `"km::XXX"` key modifiers and either a `"kb::XXX"` virtual key, or a character code value.

  The property allows almost, but not all possible combinations of key constants. Only `"km::Ctrl"`, `"km::Alt"`, and `"km::Shift"`  modifiers are allowed.

### Methods

All methods here can ( and must ) be called without the object syntax; - the first parameter must not be neither package nor  widget.

- describe KEY

  Accepts KEY in integer format, and returns string description of the key combination in human readable format. Useful for supplying an accelerator text to a menu.

  ```
          print describe( km::Shift|km::Ctrl|km::F10);
          Ctrl+Shift+F10
  ```

- export KEY

  Accepts KEY in integer format, and returns string with a perl-evaluable expression, which after evaluation resolves to the original KEY value. Useful for storing a key into text config files, where value must be both  human readable and easily passed to a program.

  ```
          print export( km::Shift|km::Ctrl|km::F10);
          km::Shift|km::Ctrl|km::F10
  ```

- shortcut KEY

  Converts KEY from integer format to a string, acceptable by `"Prima::AbstractMenu"` input methods.

  ```
          print shortcut( km::Ctrl|ord('X'));
          ^X
  ```

- translate\_codes KEY, \[ USE\_CTRL = 0 \]

  Converts KEY in integer format to three integers in the format accepted by "KeyDown" in Prima::Widget event: code, key, and modifier. USE\_CTRL is only relevant when KEY first byte ( `"KEY & 0xFF"` ) is between 1 and 26, what means that the key is a combination of an alpha key with the control key. If USE\_CTRL is 1, code result is unaltered, and is in range 1 - 26. Otherwise, code result is converted to the character code ( 1 to ord('A'), 2 to ord('B') etc ).

## AUTHOR

Dmitry Karasik, \<dmitry@karasik.eu.org\>.

## SEE ALSO

Prima, Prima::Widget, Prima::Menu.