Vue3 Touch Keyboard

The Keyboard component from the vue3-touch-keyboard package, based on the vue-touch-keyboard package by icebob, is a customizable touch keyboard for Vue 3 applications. It can be used to provide a touch interface for text input fields.
Provided by 3POS / www.3pos.de

Installation

First, install the package using npm:

``

bash

npm install vue3-touch-keyboard



Include style in your main.js

javascript

../node_modules/vue3-touch-keyboard/dist/style.css





Usage



Import the

Keyboard

 component and use it in your Vue component:

jsx

import { Keyboard } from 'vue3-touch-keyboard';



export default {

  components: {

    Keyboard

  }

}





Then, use the

Keyboard

 component in your template:

html





Props



The

Keyboard

 component accepts the following props:



-

input

 (HTMLInputElement|HTMLTextAreaElement): The input element to update with the keyboard input.

-

layout

 (String|Object): The layout of the keyboard. Can be a string representing a predefined layout or an object defining a custom layout.

-

defaultKeySet

 (String): The default key set to display on the keyboard. Default is 'default'.

-

accept

 (Function): The function to call when the accept key is pressed.

-

cancel

 (Function): The function to call when the cancel key is pressed.

-

change

 (Function): The function to call when the input value changes.

-

next

 (Function): The function to call when the next key is pressed.

-

options

 (Object): Additional options for the keyboard.



Events



The

Keyboard

 component emits a custom event when a key with a function is pressed. The name of the event is the function name of the key.



Methods



The

Keyboard

 component provides several methods that can be used to interact with the keyboard:



-

getLayout

: Retrieves the layout object based on the layout prop.

-

changeKeySet

: Changes the current key set to the specified name.

-

toggleKeySet

: Toggles the current key set between the specified name and the default key set.

-

getCaptionOfKey

: Retrieves the caption of a key.

-

getClassesOfKey

: Retrieves the classes of a key.

-

getKeyStyle

: Retrieves the style of a key.

-

supportsSelection

: Checks if the input element supports text selection.

-

getCaret

: Retrieves the current caret position in the input element.

-

backspace

: Deletes the selected text or the character before the caret position.

-

insertChar

: Inserts a character at the caret position.

-

mousedown

: Handles the mousedown event on the keyboard.

-

clickKey

: Handles the click event on a key.

-

setFocusToInput

: Sets focus to the input element and updates the caret position.



Styles



The

Keyboard

 component uses scoped CSS, which means that the styles are applied only to this component. You can customize the appearance of the keyboard by overriding the CSS classes in your own styles. The component uses the following CSS classes:



-

vue3-touch-keyboard

: The main class for the keyboard component.

-

keyboard

: The class for the keyboard itself.

-

line

: The class for a line of keys.

-

key

: The class for a key.

-

placeholder

: The class for a placeholder key.

-

activated

: The class for an activated key.



Example



Here's an example of how to use the

Keyboard

 component:

html





In this example, the

Keyboard component is linked to an input field. When the accept key is pressed, the onAccept method is called with the current text of the input field. When the cancel key is pressed, the onCancel

 method is called.

Vue3 Touch Keyboard Composable Documentation



This package provides a composable

useTouchKeyboard for Vue 3 applications, allowing control over the Keyboard.vue

 component. This composable facilitates the integration of a touch keyboard into your Vue 3 application.



Usage



1. Import the composable

    

    Import the

useTouchKeyboard

 composable in your component.

js

    import { useTouchKeyboard } from 'vue3-touch-keyboard';



    

2. Call the composable in your

setup function



    

    Call the

useTouchKeyboard function in your setup

 function.

jsx

    setup() {

      const touchKeyboard = useTouchKeyboard();

      // ...

      return {

        // ...

        touchKeyboard,

      };

    }



    

    You can now use the returned object to control the touch keyboard.

    



API



The

useTouchKeyboard

 function returns an object with the following properties and methods:



-

options

: An object containing the current options for the touch keyboard component.

-

keyboardLocale

: The current locale of the keyboard. (uses localstorage to persist state)

-

layouts

: An object containing the available keyboard layouts.

-

keyboardEnabled

: A boolean indicating whether the touch keyboard is enabled. (uses localstorage to persist state)

-

setLocalLayout(locale)

: A function to set the local layout based on the provided locale.

-

toggleTouchKeyboard(isEnabled)

: A function to toggle the visibility of the touch keyboard.

-

showTouchKeyboardWithoutEvent()

: A function to show the touch keyboard without any event.

-

showTouchKeyboard(e)

: A function to show the touch keyboard based on the focus event.

-

hideTouchKeyboard()

: A function to hide the touch keyboard.

-

dismissOnScreenKeyboard(e)

: A function to dismiss the on-screen keyboard based on the provided event.

-

getKeyBoardLayout(locale, layout)

: A function to get the keyboard layout based on the provided locale and layout.



Input Attributes



To use the touch keyboard composable with an input element, add the

data-use-touch-keyboard

 attribute to it.

Note that you need to use your own wrapper arround the Keyboard.vue component.

You can also use showTouchKeyboard method in a focus event of the target input if you don't want to use data-use-touch-keyboard attribute, but both serve the same purpose

html



or





To set a specific layout for the keyboard, use the

data-layout

 attribute:

html

The

data-layout

 attribute can be set to any of the available layouts: 'normal', 'numeric', 'compact'. If the specified layout does not exist, it will default to 'normal'.



Vue3 Touch Keyboard - OnScreenKeyboard Component



The

OnScreenKeyboard component is a wrapper around the Keyboard component. It uses useTouchKeyboard

 composable to manage the state of the keyboard and provides an interface to show and hide the keyboard.

It is recommended to use this component as global as possible (for example in the App.vue if you want to make it available for all components), as it handles all the inputs that enables the touch keyboard via setting the data-use-touch-keyboard attribute in the target input



Usage



Import the

OnScreenKeyboard

 component and use it in your Vue component:

jsx

import { OnScreenKeyboard } from 'vue3-touch-keyboard';



export default {

  components: {

    OnScreenKeyboard

  }

}





Then, use the

OnScreenKeyboard

 component in your template:

html





Composable



The

OnScreenKeyboard component uses the useTouchKeyboard

 composable to manage the state of the keyboard.

Example



Here's an example of how to use the

OnScreenKeyboard

 component:

html





In this example, the

OnScreenKeyboard

 component is linked to an input field. When the input field is focused



Notes

the

OnScreenKeyboard component automatically manages the keyboard state through the useTouchKeyboard

 composable, providing a seamless touch keyboard experience.



Feel free to customize the use of the

Keyboard.vue component in a wrapper by utilizing the useTouchKeyboard composable. This composable can also be employed as a utility to control any wrapper around the Keyboard.vue component. Additionally, persistent state variables such as keyboardLocale and keyboardEnabled

 are available for further customization.

html





In this modified example, the

useTouchKeyboard composable is utilized to control the state of the touch keyboard. The input field is tagged with the data-use-touch-keyboard attribute and a specific layout is set with the data-layout

 attribute.



This comprehensive approach allows for global usage of the touch keyboard, controlled by the

useTouchKeyboard` composable, and provides flexibility for customization in specific scenarios.

Vue3 Touch Keyboard

Installation

First, install the package using npm:

``

bash

npm install vue3-touch-keyboard



Include style in your main.js

javascript

../node_modules/vue3-touch-keyboard/dist/style.css





Usage



Import the

Keyboard

 component and use it in your Vue component:

jsx

import { Keyboard } from 'vue3-touch-keyboard';



export default {

  components: {

    Keyboard

  }

}





Then, use the

Keyboard

 component in your template:

html





Props



The

Keyboard

 component accepts the following props:



-

input

 (HTMLInputElement|HTMLTextAreaElement): The input element to update with the keyboard input.

-

layout

 (String|Object): The layout of the keyboard. Can be a string representing a predefined layout or an object defining a custom layout.

-

defaultKeySet

 (String): The default key set to display on the keyboard. Default is 'default'.

-

accept

 (Function): The function to call when the accept key is pressed.

-

cancel

 (Function): The function to call when the cancel key is pressed.

-

change

 (Function): The function to call when the input value changes.

-

next

 (Function): The function to call when the next key is pressed.

-

options

 (Object): Additional options for the keyboard.



Events



The

Keyboard

 component emits a custom event when a key with a function is pressed. The name of the event is the function name of the key.



Methods



The

Keyboard

 component provides several methods that can be used to interact with the keyboard:



-

getLayout

: Retrieves the layout object based on the layout prop.

-

changeKeySet

: Changes the current key set to the specified name.

-

toggleKeySet

: Toggles the current key set between the specified name and the default key set.

-

getCaptionOfKey

: Retrieves the caption of a key.

-

getClassesOfKey

: Retrieves the classes of a key.

-

getKeyStyle

: Retrieves the style of a key.

-

supportsSelection

: Checks if the input element supports text selection.

-

getCaret

: Retrieves the current caret position in the input element.

-

backspace

: Deletes the selected text or the character before the caret position.

-

insertChar

: Inserts a character at the caret position.

-

mousedown

: Handles the mousedown event on the keyboard.

-

clickKey

: Handles the click event on a key.

-

setFocusToInput

: Sets focus to the input element and updates the caret position.



Styles



The

Keyboard

 component uses scoped CSS, which means that the styles are applied only to this component. You can customize the appearance of the keyboard by overriding the CSS classes in your own styles. The component uses the following CSS classes:



-

vue3-touch-keyboard

: The main class for the keyboard component.

-

keyboard

: The class for the keyboard itself.

-

line

: The class for a line of keys.

-

key

: The class for a key.

-

placeholder

: The class for a placeholder key.

-

activated

: The class for an activated key.



Example



Here's an example of how to use the

Keyboard

 component:

html





In this example, the

 method is called.

Vue3 Touch Keyboard Composable Documentation



This package provides a composable

useTouchKeyboard for Vue 3 applications, allowing control over the Keyboard.vue

 component. This composable facilitates the integration of a touch keyboard into your Vue 3 application.



Usage



1. Import the composable

    

    Import the

useTouchKeyboard

 composable in your component.

js

    import { useTouchKeyboard } from 'vue3-touch-keyboard';



    

2. Call the composable in your

setup function



    

    Call the

useTouchKeyboard function in your setup

 function.

jsx

    setup() {

      const touchKeyboard = useTouchKeyboard();

      // ...

      return {

        // ...

        touchKeyboard,

      };

    }



    

    You can now use the returned object to control the touch keyboard.

    



API



The

useTouchKeyboard

 function returns an object with the following properties and methods:



-

options

: An object containing the current options for the touch keyboard component.

-

keyboardLocale

: The current locale of the keyboard. (uses localstorage to persist state)

-

layouts

: An object containing the available keyboard layouts.

-

keyboardEnabled

: A boolean indicating whether the touch keyboard is enabled. (uses localstorage to persist state)

-

setLocalLayout(locale)

: A function to set the local layout based on the provided locale.

-

toggleTouchKeyboard(isEnabled)

: A function to toggle the visibility of the touch keyboard.

-

showTouchKeyboardWithoutEvent()

: A function to show the touch keyboard without any event.

-

showTouchKeyboard(e)

: A function to show the touch keyboard based on the focus event.

-

hideTouchKeyboard()

: A function to hide the touch keyboard.

-

dismissOnScreenKeyboard(e)

: A function to dismiss the on-screen keyboard based on the provided event.

-

getKeyBoardLayout(locale, layout)

: A function to get the keyboard layout based on the provided locale and layout.



Input Attributes



To use the touch keyboard composable with an input element, add the

data-use-touch-keyboard

 attribute to it.

Note that you need to use your own wrapper arround the Keyboard.vue component.

You can also use showTouchKeyboard method in a focus event of the target input if you don't want to use data-use-touch-keyboard attribute, but both serve the same purpose

html



or





To set a specific layout for the keyboard, use the

data-layout

 attribute:

html

The

data-layout

 attribute can be set to any of the available layouts: 'normal', 'numeric', 'compact'. If the specified layout does not exist, it will default to 'normal'.



Vue3 Touch Keyboard - OnScreenKeyboard Component



The

OnScreenKeyboard component is a wrapper around the Keyboard component. It uses useTouchKeyboard

 composable to manage the state of the keyboard and provides an interface to show and hide the keyboard.

It is recommended to use this component as global as possible (for example in the App.vue if you want to make it available for all components), as it handles all the inputs that enables the touch keyboard via setting the data-use-touch-keyboard attribute in the target input



Usage



Import the

OnScreenKeyboard

 component and use it in your Vue component:

jsx

import { OnScreenKeyboard } from 'vue3-touch-keyboard';



export default {

  components: {

    OnScreenKeyboard

  }

}





Then, use the

OnScreenKeyboard

 component in your template:

html





Composable



The

OnScreenKeyboard component uses the useTouchKeyboard

 composable to manage the state of the keyboard.

Example



Here's an example of how to use the

OnScreenKeyboard

 component:

html





In this example, the

OnScreenKeyboard

 component is linked to an input field. When the input field is focused



Notes

the

OnScreenKeyboard component automatically manages the keyboard state through the useTouchKeyboard

 composable, providing a seamless touch keyboard experience.



Feel free to customize the use of the

 are available for further customization.

html





In this modified example, the

 attribute.



This comprehensive approach allows for global usage of the touch keyboard, controlled by the

useTouchKeyboard` composable, and provides flexibility for customization in specific scenarios.