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:

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:

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:

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:

extras

Following are the correct extra types for certain behaviors:

dimensions

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:

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:

sounds

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:

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.

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:

• Retrieve the URL of the theme you bundled with your package
• Use the JSONSerialization class to parse the JSON data and pass it to the StyleConfiguration class.

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:

• changeTheme (by theme keys), and
• changeTheme (by theme instance).

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.

• Android API Reference
• iOS API Reference