Florence aims at being easy. To launch Florence from the command line, type:

$ florence

From a MATE desktop, you can launch Florence from the menu Applications->Accessibility->Florence Virtual keyboard. If you prefer that Florence is launched at MATE startup, choose the menu item System->Preferences->Sessions, click on the Startup programs tab, then click Add and enter /usr/bin/florence so Florence is launched with MATE at next boot.

When Florence is running, an icon should appear in your notification area, usually at the top right corner of the screen. Clicking of the icon makes Florence appear or disappear from the screen. Right clicking on it makes a menu appear. On this menu, you can use the quit item to stop Florence.

Input methods

Florence can be used with 4 different input methods. Each method has advantages and drawbacks. It is up to you to select the right one for your usage pattern.

  1. The default input method is the "mouse" method. This is adapted for mouse/trackpad input. It is pretty straightforward. Just click on the key with a mouse button to press it. Release the mouse button to release the key. The advantage of this method is its simplicity. It does not require learning. The drawback is that is requires a pointing device with a button and that the user is able to use it.

  2. The second input method is the "touch" method. This is adapted for touch screen input. The difference with the mouse input method is that it not possible to touch the keyboard without clicking. In this mode, the keys are pressed on touch end.

  3. The next method is the "timer" method. Use this method if you are unable to use a button. Point a key with the pointer and a timer is triggered. When the timer expires, the key is pressed and immediately released. The timer is cancelled if the pointer leaves the key. Note you can still press a mouse button to activate the key if you have one available. The advantage of this method is that it does not require a button. The drawbacks are that it is slower than the button method and that you can not hold a key pressed.

  4. The last method is the "ramble" method. Like the timer method, the ramble method does not require a button. This method can be faster than the timer method but requires dexterity and training to be used efficiently. The ramble method can be passive: no button necessary, or active: deaf while the pointer button is not pressed. There are two sub-methods for rambling.

    1. The time-based ramble method requires good timing. While you move the pointer, Florence will detect keys that are to be activated based on the time the pointer stays over them. With this method, you can press the same key multiple times by moving the pointer to near the border of the key and back to the center. This method can be pretty fast with good training.

    2. The distance-based ramble method requires some dexterity to be used efficiently. The distance the pointer moves over the key is measured and the key is activated when it reaches a threshold. The key can be pressed multiple times by moving the pointer over the key repeatedly. A second threshold is there to detect multiple occurences. To use this method efficiently, apply quick gestures over the keys you want to activate.

Florence modes

Florence has several states affecting how it functions and how it interacts with the user.

In auto-hide mode, Florence hides itself when it detects you don't need it. There are several rules to detect when Florence is needed and those rules rely on the at-spi framework. For instance, Florence will be shown if you select an editable widget, as it should probably be edited with a keyboard. Florence will hide itself when the editable widget is unfocused. This does not work if the widget isn't accessible with at-spi. In particular, QT3 widgets may not work properly with Florence. You should make sure your applications support at-spi if you intend to use Florence in hidden mode. When this mode is off, Florence is always visible on the screen.

The auto hide mode requires accessibility to be activated, which means the at-spi registry daemon is running and applications are using it.

Figure 1. Florence extensions

Shows the extensions available.

The above figure shows the different parts of the default layout. There are other layouts that can be selected in the settings dialog (layout tab).

The default keyboard layout can be extended with 4 extensions to the core keyboard. The Florence key pad is an extension to the left of the main keyboard which contains keys to access special Florence functions: see below for a complete list of Florence functions. The arrows keypad is an extension added to the right of the core keyboard and contains the arrow keys along with navigation keys. The numpad extension contains the numeric keys and the function keys extension contains the function keys. Each extension can be activated and deactivated independantly. The extensions are relative to the selected layout.

Florence keys

The following keys give access to special Florence functions. They are located on the "Florence keys" extension.

Figure 2. Minimize key

Minimize key.

The minimize key hides the keyboard. The program is still running and the keyboard can be shown again by clicking on the icon or by selecting a text entry widget when auto-hide mode is on.

Figure 3. Configuration key

Configuration key.

The configuration key opens the configuration dialog. See the configuration chapter for more information about the configuration dialog.

Figure 4. Move key

Move key.

You can move the keyboard around the screen with the move key. Press the move key, move the pointer and release the button when the keyboard is located where you want it.

Figure 5. Bigger key

Bigger key.

Press the bigger key to increase the size of the keyboard.

Figure 6. Smaller key

Smaller key.

Press the smaller key to decrease the size of the keyboard.

Figure 7. Close key

Close key.

Press the close key to terminate the program. The close key is accessible when the alt modifier key is pressed, at the location of the minimize key.

Figure 8. Switch key

Switch key.

The switch key is accessible when the alt modifier key is pressed, at the location of the configuration key. The label of the key shows the current language of the keyboard. Press it to switch to the next laguage. Pressing it several times cycles through the available language layouts. On GNOME/MATE, the available language layouts can be configured with the gnome-keyboard-properties program (in the layout tab). If only one language is configured, pressing this key has no effect, it just shows the language layout currently configured.

Modifier keys

Some keys have a modifier attribute, just like on a real hardware keyboard. When they are pressed, the effect of other non-modifier keys is changed. The Shift and Caps_lock keys are instances of such keys. There are two types of modifier keys: the locker and non-locker modifier keys. The locker keys are activated when pressed and deactivated when pressed again. Non-locker modifier keys must be pressed at the same time as the non-modifier keys in order to change their effect.

When activated, the locker keys turn red (the color can be changed in the settings dialog) and the symbol displayed on all non-modifier keys is changed accordingly. If a non-modifier key is pressed while a locker key is active, its effect will be modified according to it.

When using a mouse, it is not possible to press 2 keys at the same time. As a solution to this problem, Florence latches non-locker modifiers when pressed. When a modifier is latched, it turns green (that color can be changed in the settings dialog). It will remain latched until another non-modifier key is pressed. If a latched key is pressed again, it turns red and becomes locked. A locked modifier will remain locked until it is pressed again to become released.


The configuration dialog is accessible via the system tray and floating icon (right click on it and select Preferences) or via the command line with the -c or --config switch: florence --config or via the configuration button on the keyboard if present. Hacking configuration is possible via dconf (see the hacking section)

Some selected options are not applied until you click the 'Apply' button. Some other options are taken into account immediately but can be cancelled with the 'Cancel' button while they have not been applied.

The settings options have been divided into 4 groups in order to ease understanding and searching for them.

Style configuration

Figure 9. Style preferences dialog

Shows the style preferences dialog.

The following style options are configurable:

  1. Style: select your style by clicking on the style icon.

  2. Default keys colour: set the background colour of normal keys.

  3. Latched keys colour: set the background colour of latched keys.

  4. Activated keys colour: set the background colour of the keys that are pressed or locked.

  5. Focused key colour: set the background colour of the key that is under the pointer.

  6. Symbol colour: set the colour of the symbol or text printed on keys.

  7. Outline colour: set the colour surronding the key symbols. This color is used to improve visibility of the symbols. It should contrast with the symbol color.

  8. Focus zoom: set the scaling factor of the focused key. Useful for visualy impaired people.

  9. Enable sound: when this box is checked, the keyboard generates sound feedback when a key is hovered, pressed or released.

  10. Use system font: when this box is checked, the labels on the keys use the default system font. When this box is unchecked, the font selected below is used instead.

  11. Keyboard font: With this parameter you can select the font used to draw key labels and its size.

Window configuration

Figure 10. Window preferences dialog

Shows the window preferences dialog.

  1. Decorated: decorates the window with a title bar. Makes it easy to move the window.

  2. Transparent: allows you to see the windows behind the keyboard between the keys and to click on them.

  3. Resizable: allow you to set the visual scale of the keyboard with the window manager. Some window managers require the decorated option to be activated in order to resize the window.

  4. Task bar: make Florence appear on the desktop task bar.

  5. Always on top: tells to the window manager to always keep the keyboard on top of other windows.

  6. System tray icon: Display an icon in the system tray to control the keyboard: you can right-click on it to display the Florence menu and left-click on it to show or hide the keybaord.

  7. Floating icon: Like the system tray icon but not attached to the system tray. You can drag the icon around the screen to move it where you want it.

  8. Opacity: set the window opacity in order to see the other windows through the keys. The window manager must support compositing and it must be activated for this option to work.

Behaviour configuration

Figure 11. Behaviour preferences dialog

Shows the behaviour preferences dialog.

  1. Input method: select the input method. Some input methods may have additional configuration options.

  2. Auto hide: switch auto-hide mode on and off.

  3. Move to near selected widget: this option is only available when auto-hide mode is activated. When activated, the keyboard will be moved to near the last selected editable widget every time you select a new one in order to minimize pointer distance from the keyboard.

  4. Intermediate icon: In auto-hide mode, don't show the keyboard directly on editable widgets, but make an intermediate icon appear instead. Click on the intermediate icon to show the actual keyboard. This option makes Florence less intrusive: for instance, if you want to read a document without editing, the intermediate icon takes less screen space than the keyboard.

Layout configuration

Figure 12. Layout preferences dialog

Shows the layout preferences dialog.

The first combo box allows you to choose your keyboard layout. The extensions are relative to the layout. They can be activated or deactivated independently. For the "Standard layout" layout, there are 4 extensions:

  1. Navigation keys: activate/deactivate the arrows keypad.

  2. Numeric keys: activate/deactivate the numpad extension.

  3. Function keys: activate/deactivate the function keys extensions.

  4. Action keys: activate/deactivate the action keys extensions.

Command line options

florence [OPTION] ... [COMMAND] [ARG]

The florence command accepts the following options:

  1. -h (--help): print help message and exit.

  2. -V (--version): print Florence version and exit.

  3. -c (--config): open configuration dialog.

  4. -d (--debug): launch Florence in verbose mode.

  5. -f (--focus) [window]: with this option, any florence input will go to the selected window. The window argument is the name of the window (the one that most window managers put in the title bar). if the window argument is not provided, florence will select the last focused window. This option is useful for window managers that don't support the 'not focusable' hint and focus the keyboard window instead of the output one. It can also be useful if you want to input text to a window that is not focused. This option must be used for the keyboard to work in GDM.

  6. -u (--use-config) file: use the configuration file provided instead of dconf. The configuration file is a key-value pair file with sections. An example of configuration file is provided at /usr/share/florence/florence.conf (the path may be changed with the --prefix configure option).

The following commands are available to control the keyboard from a script:

  1. show : show the keyboard.

  2. hide : hide the keyboard.

  3. move x,y : move the keyboard at x,y position on the screen.