Introduction To Theming

Fleksy Keyboard SDK supports themes to change the keyboard’s look and feel, adapting the keyboard app per requirements. This is especially useful when adjusting the keyboard per brand guidelines and app activities. In addition, themes give your app a more polished look and provide the user much better UX.

Theme Object

Developers can create themes for Fleksy Keyboard SDK in JSON format or native object per platform. For Android, the object is of type KeyboardTheme, while for iOS, the JSON is parsed and passed to the StyleConfiguration class.

Themes created for Fleksy Keyboard SDK when in JSON format are stored either in the assets or Resources directory for the app (differs as per platform). A theme object contains various properties of different types that allows customizing other aspects and behavior of the keyboard app.

Examples

The below example shows a JSON theme (object) with a key Fresh, in a file named themes.json.

{
  "Fresh": {
    "name": "Fresh",
    "key":"system-light",
    "colors": {
        "key_letters" : "#000000",
        "key_background" : "#ffffff",
        "key_shadow" : "#a9abad",
        "button_letters" : "#3d3d3f",
        "button_background" : "#ccced5",
        "button_background_pressed" : "#bdc1c6",
        "hover_letters" : "#000000",
        "hover_background" : "#ccced5",
        "hover_selected_letters" :  "#ffffff",
        "hover_selected_background" : "#5e96f6",
        "button_action_letters" : "#ffffff",
        "button_action_background" : "#1a73e8",
        "button_action_background_pressed" : "#0651a6",
        "spacebar_letters" : "#000000",
        "spacebar_background" : "#ccced5",
        "track_pad_cursor" : "#1a73e8"
    },
    "background": {
      "gradient": [
        "#ffffff"
      ]
    },
    "extras":{
        "look_feel_system":"true"
    },
    "companion_theme": {
      "is_dark": true,
      "key": "Darkside"
    }
  }
}

Properties

A JSON theme (object) has the following properties:

Property Name Type Description Platform
background Object Background of the theme Android, iOS
colors Object Colors of the theme Android, iOS
companion_theme Object A dark or light companion theme Android, iOS
dimensions Object Dimensions of the theme Android
extras Object Special behavior type Android, iOS
icons Object Icons, and tiles of the theme Android, iOS
is_user_theme Boolean Whether is a user made theme Android, iOS
key String Identifier of the string Android, iOS
name String Name of the theme Android, iOS
sounds Object Sounds of the theme iOS

background

The background object is a key/value map of a background property to a background value.

For example:

{
  "Fireworks": { 
    "background": { 
      "gradient": ["#f50000", "#ff8000"],
      "image_filename": "fireworks.png",
      "image_alpha": 1,
      "image_position": "scale"
    },
    ...
  },
}

A background object has the following properties:

Property Name Type Description Default value
gradient Array The background gradient of the keyboard layout.

Note: The first color of the gradient is assigned to the background color.
[“#FFFFFF”]
image_filenameimage_alpha String The background image file.

Note: The file must be available at the configured images folder.
null
image_alpha Float The image’s alpha, between 0 and 1.

Note: The image is drawn above the background gradient.
1.0
image_position String The image position and scale method.

scale: The image is scaled and cropped to fill the keyboard layout at the center.
center: The image is positioned at the center without scaling or cropping.
“scale”

colors

The colors object is a key/value map of a color property to a string hex color. All color properties are optional.

For example:

{
  "Fireworks": { 
    "colors": { 
      "key_letters" : "#8090A0",
      "key_background" : "#203040"
    },
    ...
  },
}

A colors object has the following properties:

Property Name Type Description Default value
key_letters String The text color of the letters on the keys “#000000”
key_background String The key cap’s background color.

Note: When set, keys and buttons will have spacing and shadow
null
key_shadow String The shadow color for the key caps null
button_letters String The icon color of the button keys key_letters
button_background String The background color of the button keys key_background
button_background_pressed String The background color of the button when pressed hover_background
button_action_letters String The icon color of the action button button_letters
button_action_background String The background color of the action button. button_background
button_action_background_pressed String The background color of the action button when pressed button_background_pressed
button_shift_letters String The icon color of the shift button button_letters
button_shift_background String The background color of the shift button button_background
button_shift_background_pressed String The background color of the shift button when pressed button_background_pressed
button_backspace_letters String The icon color of the backspace button button_letters
button_backspace_background String The background color of the backspace button button_background
button_backspace_background_pressed String The background color of the backspace button when pressed button_background_pressed
hover_letters String The text color of the hover when hovering a key. key_letters
hover_background String The background color of the hover when hovering a key. <Background>
hover_selected_letters String The text color of the selected item while long-pressing on a multi-label key. <Background>
hover_selected_background String The background color of the selected item while long-pressing on a multi-label key. key_letters
suggestion_letters String The text color of the non selected suggestions key_letters
suggestion_background String The background color of the suggestions strip null
suggestion_selected_letters String The text color of the selected suggestion key_letters
spacebar_letters String The text color of the text and icons on the spacebar button_letters
spacebar_background String The background color of the spacebar button_background
spacebar_background_pressed String The background color of the spacebar when pressed button_background_pressed
track_pad_cursor String The color of the cursor in the track pad key_letters
home_background String The background color of the middle row null
swipe_line String The color of the swipe line when swipe typing is enabled button_action_background, key_letters

companion_theme

The companion theme object defines a related theme based on whether it is dark or light.

For example:

{
  "Darkside": { 
    "companion_theme": { 
      "is_dark": false,
      "key": "Lightside"
    },
    ...
  },
}

A companion_theme object has the following properties:

Property Name Type Description Default value
is_dark Boolean Whether the companion theme is dark.

Note: Implies the reverse for the parent theme
false
key String The companion theme key null

extras

Following are the correct extra types for certain behaviors:

Property Name Type Description Platform
Chameleon Boolean The background color is set to the dominant color of the app in use. Android, iOS
Rainbow_pops Boolean The color of the key press tiles changes on each key press with the colors of the rainbow. iOS
Timelapse Boolean The color of the background changes over time. Android
Swipechange Boolean The color of the key press tiles changes on each swipe. iOS
look_feel_system Boolean The theme has a look & feel like the system keyboard iOS

dimensions

Only available on Android

The dimensions object is a key/value map of a dimension property to device-independent pixel float values.

For example:

{
  "Fireworks": { 
    "dimensions": { 
      "keycap_spacing_vertical": 5.0,
      "keycap_spacing_horizontal": 2.5,
      "key_shadow_height": 1.0
    },
    ...
  },
}

A dimensions object has the following properties:

Property Name Type Description Default value
keycap_spacing_vertical Float The vertical spacing between keys is applied to each key’s top and bottom.

Note: Only applies when key_backround is set.
5.0
keycap_spacing_horizontal Float The horizontal spacing between keys is applied to each key’s left and right.

Note: Only applies when key_backround is set.
2.5
key_hover_height Float The hover height when the hover style is fixed. 74.0
key_hover_width Float The width of the hover when the hover style is set to fix. 42.0
key_shadow_height Float The height of the shadow.

Note: Only applies when key_backround is set.
1.0

icons

The icons object is a key/value map of an icon property to an array of icon characters values. The character should map to a character in the icons fonts.

For example:

{
  "Fireworks": { 
    "icons": { 
      "tile": [""],
    },
    ...
  },
}

An icons object has the following properties:

Property Name Type Description Default value
tile Array When set, the tile character to use for the key presses.

Note: When more than one item is in the array, it cycles each character on each key press.
Note: When not set, uses the default hover bar.
null

sounds

Only available on iOS

The sounds object is a key/value map of a sound property to a sound resource value.

For example:

{
  "Fireworks": { 
    "sounds": { 
      "swipe_horizontal": "swipe_h_firework",
      "tap": "tap_firework",
      "swipe_vertical": "swipe_v_firework"
    },
    ...
  },
}

A sounds object has the following properties:

Property Name Type Description Default value
tap String The sound to use for key presses null
swipe_vertical String The sound to use for vertical swipes null
swipe_horizontal String The sound to use for horizontal swipes null

Packing JSON themes in App

The JSON themes are stored in app’s asset directory on Android apps. On iOS apps, they are stored in the keyboard target’s Resources directory.

The assets and Resources directories are absent by default on new projects unless created manually. For more information on app resources, check official Android guide or official iOS guide as required.

Examples

The below example shows instructions for Android and iOS platforms, assuming that the themes.json file containing all the themes stored is in the ~/Downloads directory.

For Android:

With a terminal open at the root of the android project:

Copy the themes.json file to the assets directory:

$ cp ~/Downloads/themes.json app/src/main/assets

For iOS:

With a terminal open at the root of the target (Custom Keyboard Extension):

Copy the themes.json file to the Resources directory:

$ cp ~/Downloads/themes.json /Resources

Loading Theme on Startup

The initial theme loaded by the keyboard app on startup can be configured within the createConfiguration method, which is overridden to provide the initial configuration used by the keyboard app. In addition, this method’s style parameter accepts an object of type StyleConfiguration that contains various parameters to work with themes.

On Android, StyleConfiguration accepts the theme (object) key directly as themes are automatically read from the assets directory. However, on iOS, there is no automatic reading, and thus themes must be manually read into a Dictionary object.

When only one value is set for a light or dark theme, it will be used for both light and dark modes.

Examples

For Android:

To set a JSON theme (object) present in the assets directory:

  • Create an instance of the StyleConfiguration class and provide a specific theme object’s key that should be loaded.
  • Pass the instance created above to the createConfiguration’s style parameter.

The below code sample showcases how the initial theme can be configured when the theme is in the JSON format and present in the assets directory:

 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import co.thingthing.fleksy.core.keyboard.KeyboardConfiguration
import co.thingthing.fleksy.core.keyboard.KeyboardService

class SampleKeyboardService : KeyboardService() {

    override fun createConfiguration(): KeyboardConfiguration {
        return KeyboardConfiguration(
            license = KeyboardConfiguration.LicenseConfiguration(
                licenseKey = "<your-license-key>",
                licenseSecret = "<your-license-secret>"
            ),
            style = KeyboardConfiguration.StyleConfiguration(
                themeKey = "<your-theme-object-key>" // e.g. "Fresh" (if using the example JSON theme)
                darkThemeKey = "<your-dark-theme-object-key>" // In case of a different dark theme
            )
        )
    }

}

In case when the theme objects are of type KeyboardTheme, consider using forceTheme and forceDarkTheme parameters of StyleConfiguration. If either forceTheme or forceDarkTheme is set, only the forced themes will be used, regardless of the value set in themeKey or darkThemeKey.

For iOS:

To read and set a JSON theme (object) present in the Resources directory:

Ensure that the theme is present in the Resources directory and being bundled in the target or manually handle possible exceptions to prevent crashes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import FleksyKeyboardSDK

class KeyboardViewController: FleksyKeyboardSDK.FKKeyboardViewController {

    override func createConfiguration() -> KeyboardConfiguration {
        // Load the theme from Resources directory
        let fileURL = Bundle.main.url(forResource: "themes", withExtension: ".json")
        let data = try! Data(contentsOf: fileURL!, options: .mappedIfSafe)
        let jsonTheme = try! JSONSerialization.jsonObject(with: data, options: []) as? [String: Any]

        let style = StyleConfiguration(theme: jsonTheme!, withDarkTheme: jsonTheme!)

        let appPopup = AppearancePopup()
        let appLongpress = AppearanceLongPress()
        let appearance = AppearanceConfiguration(
            objPopup: appPopup,
            objTouch: nil,
            objLongpress: appLongpress
        )

        let typing = TypingConfiguration()
        let panelConfig = PanelConfiguration()
        let debugConfig = DebugConfiguration(debug: ())

        let licenseConfig = LicenseConfiguration(
            licenseKey: "<your-license-key>",
            licenseSecret: "<your-license-secret>"
        )

        return KeyboardConfiguration(
            panel: panelConfig,
            capture: nil,
            style: style,
            appearance: appearance,
            typing: typing,
            specialKeys: nil,
            license: licenseConfig,
            debug: debugConfig
        )
    }
}

Changing Theme on the Fly

Changing themes while the keyboard is running is a common use case supported by the Fleksy Keyboard SDK.

For Android:

The ThemesHelper class provides 2 overload methods to change theme namely:

In case when the theme objects are of type KeyboardTheme, consider using changeTheme method that takes theme instance as a parameter.

For iOS:

The ReloadTheme method on iOS allows to reload theme on the fly. This method returns a bool that indicates whether the action was successful or not.

Additional Resources

For more information on working with themes, consider checking out the API reference documentation for the respective platform, which documents all the available methods to customize the keyboard built with Fleksy Keyboard SDK.


Last updated on September 9, 2022