Home / Virtual Keyboard

Virtual Keyboard Configuration

Overview

The SaleFlex POS system supports database-driven virtual keyboard configuration. All visual aspects of the virtual keyboard (colors, sizes, fonts, etc.) are stored in the database and can be customized without changing code.

Features

  • Dynamic Configuration: All keyboard settings loaded from database
  • Multiple Themes: Switch between different keyboard themes instantly
  • Enable/Disable: Toggle virtual keyboard on/off (use physical keyboard when disabled)
  • Hot Reload: Settings can be reloaded without restarting the application
  • Fully Customizable: Font, colors, button sizes, spacing, and more

Database Model

The PosVirtualKeyboard table stores all keyboard configuration settings:

Key Fields

  • name: Theme name (e.g., "DEFAULT_VIRTUAL_KEYBOARD")
  • is_active: Controls if virtual keyboard is shown
  • keyboard_width / keyboard_height: Total keyboard dimensions
  • font_family / font_size: Button font settings
  • button_width / button_height: Regular button dimensions
  • button_background_color: Button background (supports gradients)
  • button_pressed_color: Button color when pressed
  • button_border_color / button_border_width / button_border_radius: Border styling

Pre-installed Themes

DEFAULT_VIRTUAL_KEYBOARD

Size: 970x315 pixels

Theme: Light gradient

Font: Noto Sans CJK JP, 20px

Best for: Standard touchscreen displays

DARK_THEME_KEYBOARD

Size: 970x315 pixels

Theme: Dark gradient

Font: Noto Sans CJK JP, 20px

Best for: Night mode or dark UI themes

COMPACT_KEYBOARD

Size: 750x250 pixels

Theme: Light gradient (smaller)

Font: Noto Sans CJK JP, 16px

Best for: Smaller screens or when space is limited

How to Use

Enable/Disable Virtual Keyboard

from data_layer.engine import Engine
from data_layer.model.definition import PosVirtualKeyboard

# Disable virtual keyboard (use physical keyboard)
with Engine().get_session() as session:
    keyboards = session.query(PosVirtualKeyboard).all()
    for kb in keyboards:
        kb.is_active = False
    session.commit()

# Enable specific theme
with Engine().get_session() as session:
    theme = session.query(PosVirtualKeyboard).filter_by(
        name="DEFAULT_VIRTUAL_KEYBOARD"
    ).first()
    theme.is_active = True
    session.commit()

Switch Themes

from user_interface.control.virtual_keyboard import KeyboardSettingsLoader

# Reload settings (use after making database changes)
KeyboardSettingsLoader.reload_settings()

# Check if keyboard is enabled
is_enabled = KeyboardSettingsLoader.is_keyboard_enabled()

Create Custom Theme

from data_layer.engine import Engine
from data_layer.model.definition import PosVirtualKeyboard

with Engine().get_session() as session:
    custom = PosVirtualKeyboard(
        name="MY_CUSTOM_THEME",
        is_active=False, # Don't activate yet
        keyboard_width=800,
        keyboard_height=280,
        font_family="Arial",
        font_size=18,
        button_width=70,
        button_height=35,
        button_background_color="rgb(220, 220, 220)",
        button_pressed_color="rgb(50, 150, 250)",
        # ... set other properties as needed
    )
    session.add(custom)
    session.commit()

Troubleshooting

Virtual Keyboard Not Showing

  1. Check if is_active is True for at least one keyboard theme
  2. Verify database connection
  3. Check KeyboardSettingsLoader initialization in logs

Styles Not Updating

  1. Call KeyboardSettingsLoader.reload_settings() after database changes
  2. Restart application if settings were changed before initialization

Custom Theme Not Appearing

  1. Ensure is_deleted is False
  2. Check that theme name doesn't conflict with existing themes
  3. Activate the theme by setting is_active=True