# Namespace: CB_Keyboard

## CB_Keyboard

Static class to manage the keyboard and other input devices that generate key codes. It will return itself if it is tried to be instantiated.

Source:
  - CrossBase/input/CB_Keyboard.js, line 11

### Namespaces

chars
extended
keys

### Members

#### <static, readonly> keysDown :Object

  Object that will store the status for each key detected, using the key code as index and a boolean as their value (true when down or false when released).

  ##### Type:

  - Object
  Default Value:
    - {}
  Source:
    - CrossBase/input/CB_Keyboard.js, line 26

#### <static, readonly> keysPressed :array

  Array with the codes of the keys pressed recently (it will be cleared after the chosen milliseconds set with the `CB_Keyboard.setKeysPressedExpiration` function).

  ##### Type:

  - array
  Default Value:
    - []
  Source:
    - CrossBase/input/CB_Keyboard.js, line 36

#### <static, readonly> typedString :string

  Stores the string typed recently (it will be cleared after the chosen milliseconds set with the `CB_Keyboard.setTypedStringExpiration` function).

  ##### Type:

  - string
  Source:
    - CrossBase/input/CB_Keyboard.js, line 58

#### <static, readonly> typedStringCodes :array

  Array with the codes of the string typed recently (it will be cleared after the chosen milliseconds set with the `CB_Keyboard.setTypedStringExpiration` function).

  ##### Type:

  - array
  Default Value:
    - []
  Source:
    - CrossBase/input/CB_Keyboard.js, line 48

### Methods

#### <static> clearKeysDown(keepPressed)

  Clears (empties totally or partially) the `CB_Keyboard.keysDown` object which contains the detected keys pressed or released.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `keepPressed` | boolean | If set to true, it will keep the pressed keys.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3207

#### <static> clearKeysPressed(keepPressed)

  Clears (empties totally or partially) the `CB_Keyboard.keysPressed` array which contains the key codes pressed recently.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `keepPressed` | boolean | If set to true, it will keep the pressed keys (taken from the `CB_Keyboard.keysDown` object).

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3315

#### <static> clearTypedString(keepPressed)

  Clears (empties totally or partially) the `CB_Keyboard.typedString` string and the `CB_Keyboard.typedStringCodes` array.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `keepPressed` | boolean | If set to true, it will keep the values belonging to the currently-pressed keys (taken from the `CB_Keyboard.keysDown` object).

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3434

#### <static> getKeyCode(e [, avoidNormalize]) → {integer}

  Returns the key code that is contained in the given keyboard event.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `e` | Event |  |  | Keyboard event object.
  `avoidNormalize` | boolean | <optional> | false | If it is not set to true, it will call the `CB_Events.normalize` function internally before.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3159
  To Do:
    - Have in mind that keyCode is deprecated.

  ##### Returns:

  Returns the key code.

  Type
    integer

#### <static> getKeysDown() → {Object}

  Returns the `CB_Keyboard.keysDown` object which contains the detected keys pressed or released.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3227

  ##### Returns:

  Returns the `CB_Keyboard.keysDown` object.

  Type
    Object

#### <static> getKeysPressed() → {array}

  Returns the `CB_Keyboard.keysPressed` array which contains the key codes pressed recently (it will be cleared after the chosen milliseconds set with the `CB_Keyboard.setKeysPressedExpiration` function).

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3338

  ##### Returns:

  Returns the `CB_Keyboard.keysPressed` array.

  Type
    array

#### <static> getKeysPressedExpiration() → {integer}

  Returns the milliseconds after which the `CB_Keyboard.keysPressed` array is always cleared (emptied). The time always starts counting from zero again when a key is pressed (onKeyDown event is fired).
  To define this amount of time, the `CB_Keyboard.setKeysPressedExpiration` method must be used.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3368

  ##### Returns:

  Returns the milliseconds of expiration defined for the `CB_Keyboard.keysPressed` array.

  Type
    integer

#### <static> getTypedString() → {string}

  Returns the `CB_Keyboard.typedString` string which contains the string typed recently (it will be cleared after the chosen milliseconds set with the `CB_Keyboard.setTypedStringExpiration` function).

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3485

  ##### Returns:

  Returns the `CB_Keyboard.typedString` string.

  Type
    string

#### <static> getTypedStringCodes() → {array}

  Returns the `CB_Keyboard.typedStringCodes` array which contains the key codes pressed that belongs to the string typed recently (it will be cleared after the chosen milliseconds set with the `CB_Keyboard.setTypedStringExpiration` function).

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3496

  ##### Returns:

  Returns the `CB_Keyboard.typedStringCodes` array.

  Type
    array

#### <static> getTypedStringExpiration() → {integer}

  Returns the milliseconds after which the `CB_Keyboard.typedString` string and the `CB_Keyboard.typedStringCodes` array are always cleared (emptied). The time always starts counting from zero again when a key is pressed (onKeyPress event is fired).
  To define this amount of time, the `CB_Keyboard.setTypedStringExpiration` method must be used.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3526

  ##### Returns:

  Returns the milliseconds of expiration defined for the `CB_Keyboard.typedString` string and the `CB_Keyboard.typedStringCodes` array.

  Type
    integer

#### <static> isKeyDown(keyCodes [, allPressed]) → {boolean}

  Returns whether the given key codes are being pressed (any of them or all at the same time, depending on the "allPressed" parameter).

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `keyCodes` | integer | array | Object |  |  | An integer with the key code or a numeric array with the key codes that we want to check. It can also be an array of arrays, being each element a numeric array with the key codes that we want to check. Although not recommended (for performance purposes), this parameter can also support an object whose indexes are the keycodes (it will be converted to a numeric array internally).
  `allPressed` | boolean | <optional> | false | If set true, the function will only return true in the case that all given key codes are currently being pressed. Otherwise, if set to false, the function will return true in the case that any of the given key codes is currently being pressed. When the "keyCodes" is an array of arrays with key codes, it will be considered that all keys are being pressed if each single array (all of them) has at least one of its key codes pressed.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3240

  ##### Returns:

  If "allPressed" parameter is set to true, returns true in the case that all given key codes are currently being pressed. If "allPressed" parameter is set to false, returns true in the case that any of the given key codes is currently being pressed. In all other cases, it returns false.

  Type
    boolean

#### <static> normalizeEvent(e) → {Event}

  Tries to return the given keyboard event with some properties normalized (since different clients can use different values) and perhaps some new properties added (in the case they were missing), when possible. The new attached methods and properties may include polyfills, etc. It also calls the `CB_Events.normalize` function internally. Some properties added or affected could be keyCode, location, ctrlKey, altKey, shiftKey, etc.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `e` | Event | Keyboard event object. If not provided, it will use the value of "event", "window.event", "Event" or an empty object ("{}").

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3109
  To Do:
    - Calculate (if possible) the values for location, ctrlKey, altKey, etc. when added, to simulate the expected behaviour.

  ##### Returns:

  Returns the keyboard event object normalized.

  Type
    Event

#### <static> onKeyDown(callbackFunction [, keepOldFunction] [, useCapture] [, target])

  Sets a function to execute when a key is down (onKeyDown event) or removes it.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `callbackFunction` | CB_Keyboard.EVENT_CALLBACK | null |  |  | The function (event listener) that we want to execute when the event is fired. The first parameter received for this function will be the event object (already normalized by the `CB_Keyboard.normalizeEvent` function) and the second one will be the key code associated. If a null value is used, the event will be removed.
  `keepOldFunction` | boolean | <optional> | true | Defines whether we want to keep any possible previous event listener for the same target and event name or not.
  `useCapture` | boolean | <optional> | false | Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
  `target` | Object | <optional> | document | The target where we want to attach the event listener.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3601

#### <static> onKeyPress(callbackFunction [, keepOldFunction] [, useCapture] [, target])

  Sets a function to execute when a key is pressed (onKeyPress event) or removes it.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `callbackFunction` | CB_Keyboard.EVENT_CALLBACK | null |  |  | The function (event listener) that we want to execute when the event is fired. The first parameter received for this function will be the event object (already normalized by the `CB_Keyboard.normalizeEvent` function) and the second one will be the key code associated. If a null value is used, the event will be removed.
  `keepOldFunction` | boolean | <optional> | true | Defines whether we want to keep any possible previous event listener for the same target and event name or not.
  `useCapture` | boolean | <optional> | false | Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
  `target` | Object | <optional> | document | The target where we want to attach the event listener.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3587

#### <static> onKeyUp(callbackFunction [, keepOldFunction] [, useCapture] [, target])

  Sets a function to execute when a key is released (onKeyUp event) or removes it.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `callbackFunction` | CB_Keyboard.EVENT_CALLBACK | null |  |  | The function (event listener) that we want to execute when the event is fired. The first parameter received for this function will be the event object (already normalized by the `CB_Keyboard.normalizeEvent` function) and the second one will be the key code associated. If a null value is used, the event will be removed.
  `keepOldFunction` | boolean | <optional> | true | Defines whether we want to keep any possible previous event listener for the same target and event name or not.
  `useCapture` | boolean | <optional> | false | Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
  `target` | Object | <optional> | document | The target where we want to attach the event listener.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3615

#### <static> preventF11Key(e)

  Tries to prevent the default behaviour that would produce the "F11" key of a given keyboard event when the client is compatible with the HTML5 Fullscreen API and uses it to toggle (enable or disable) the fullscreen mode. It calls the `CB_Keyboard.normalizeEvent` function internally.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `e` | Event | Keyboard event object.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3537

#### <static> setKeysPressedExpiration(keysPressedExpiration) → {boolean}

  Sets the milliseconds after which the `CB_Keyboard.keysPressed` array is always cleared (emptied). The time always starts counting from zero when a key is pressed (onKeyDown event is fired).

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `keysPressedExpiration` | integer | An integer greater than 0 (zero) representing the milliseconds after which we desire that the `CB_Keyboard.keysPressed` array is cleared (emptied), if no key is pressed during this time.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3350

  ##### Returns:

  Returns true if the given time could be applied or false otherwise.

  Type
    boolean

#### <static> setTypedStringExpiration(keysPressedExpiration) → {boolean}

  Sets the milliseconds after which the `CB_Keyboard.typedString` string and the `CB_Keyboard.typedStringCodes` array are always cleared (emptied). The time always starts counting from zero when a key is pressed (onKeyPress event is fired).

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `keysPressedExpiration` | integer | An integer greater than 0 (zero) representing the milliseconds after which we desire that the `CB_Keyboard.typedString` string and the `CB_Keyboard.typedStringCodes` array are cleared (emptied), if no key is pressed during this time.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3508

  ##### Returns:

  Returns true if the given time could be applied or false otherwise.

  Type
    boolean

### Type Definitions

#### EVENT_CALLBACK(e, keyCode)

  Callback that is called before loading a file and should return true if we want to load the file or false otherwise.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `e` | Event | Keyboard event object.
  `keyCode` | integer | Key code which fired the event.

  Source:
    - CrossBase/input/CB_Keyboard.js, line 3570

#### Search results