Preferences System

Overview

Ember's preferences system provides persistent storage for application settings, user preferences, and workspace state. The system is built around the AppPreferences and AppPreferencesManager classes.

AppPreferencesManager

The central singleton for accessing and managing preferences.

Basic Usage

#include "Utils/AppPreferences.h"
 
auto& prefs = EmberForge::AppPreferencesManager::GetInstance();
 
// Read preferences
bool darkMode = prefs.GetThemeMode() == ThemeMode::Dark;
int fontSize = prefs.GetFontSize();
 
// Write preferences
prefs.SetThemeMode(ThemeMode::Dark);
prefs.SetFontSize(12);
 
// Save to disk
prefs.SavePreferences();

Initialization

// In App::OnInit()
auto& prefs = AppPreferencesManager::GetInstance();
prefs.LoadPreferences();  // Load from ~/.config/ember/preferences.json

Preference Categories

Theme Settings

Setting	Type	Description
ThemeMode	Enum	Light, Dark, or System
AccentColor	wxColour	UI accent color
FontSize	int	Base font size
FontFamily	string	Font family name

// Theme mode
prefs.SetThemeMode(ThemeMode::Dark);
ThemeMode mode = prefs.GetThemeMode();
 
// Accent color
prefs.SetAccentColor(wxColour(0, 120, 215));
wxColour accent = prefs.GetAccentColor();

Window Settings

Setting	Type	Description
WindowPosition	Point	Main window position
WindowSize	Size	Main window size
WindowMaximized	bool	Maximized state
AuiPerspective	string	Panel layout

// Window geometry
prefs.SetWindowSettings(WindowSettings{
    .position = {100, 100},
    .size = {1280, 720},
    .maximized = false
});
 
auto settings = prefs.GetWindowSettings();

Main Panel Settings

Setting	Type	Description
ShowGrid	bool	Show background grid
GridSize	int	Grid cell size
SnapToGrid	bool	Enable grid snapping
CanvasColor	Color	Background color

MainPanelSettings panel;
panel.show_grid = true;
panel.grid_size = 20;
panel.snap_to_grid = true;
prefs.SetMainPanelSettings(panel);

Behavior Tree View Settings

Setting	Type	Description
DefaultZoom	float	Initial zoom level
AutoFitOnLoad	bool	Fit tree to view on load
AnimateTransitions	bool	Animate view changes
NodeSpacing	int	Space between nodes
LevelSpacing	int	Space between tree levels

BehaviorTreeViewSettings btView;
btView.default_zoom = 1.0f;
btView.auto_fit_on_load = true;
btView.node_spacing = 50;
btView.level_spacing = 80;
prefs.SetBehaviorTreeViewSettings(btView);

File Explorer Settings

Setting	Type	Description
ViewMode	Enum	Tree, Grid, or Split
SortBy	Enum	Name, Date, Size, Type
SortAscending	bool	Sort direction
ShowHiddenFiles	bool	Show hidden files
IconSize	Enum	Small, Medium, Large

FileExplorerSettings explorer;
explorer.view_mode = FileExplorerViewMode::Split;
explorer.sort_by = SortBy::Name;
explorer.icon_size = IconSize::Medium;
prefs.SetFileExplorerSettings(explorer);

Parser Settings

Setting	Type	Description
DefaultProfile	string	Default parser profile
ValidateOnLoad	bool	Validate trees on load
PreserveComments	bool	Preserve XML comments

ParserPreferences parser;
parser.default_profile = "BehaviorTree.CPP v4";
parser.validate_on_load = true;
prefs.SetParserPreferences(parser);

Keyboard Shortcuts

Setting	Type	Description
Shortcuts	map	Action → Key mapping

// Get shortcut for action
wxString shortcut = prefs.GetShortcut("file.open");  // "Ctrl+O"
 
// Set custom shortcut
prefs.SetShortcut("file.open", "Ctrl+Shift+O");

Recent Files

// Add to recent files
prefs.AddRecentFile("/path/to/file.xml");
 
// Get recent files list
auto recentFiles = prefs.GetRecentFiles();
 
// Clear recent files
prefs.ClearRecentFiles();

Preference Enums

ThemeMode

enum class ThemeMode {
    Light,   
    Dark,    
    System   
};

StartupMode

enum class StartupMode {
    Empty,       
    LastProject, 
    Welcome      
};

FileExplorerViewMode

enum class FileExplorerViewMode {
    Tree,   
    Grid,   
    Split   
};

SortBy

enum class SortBy {
    Name,
    DateModified,
    Size,
    Type
};

IconSize

enum class IconSize {
    Small,   
    Medium,  
    Large    
};

Storage Location

Preferences are stored in JSON format:

Platform	Location
Linux	~/.config/ember/preferences.json
Windows	APPDATA%\Ember\preferences.json
macOS	~/Library/Application Support/Ember/preferences.json

JSON Structure

{
    "version": 1,
    "theme": {
        "mode": "dark",
        "accent_color": "#0078D7",
        "font_size": 12
    },
    "window": {
        "x": 100,
        "y": 100,
        "width": 1280,
        "height": 720,
        "maximized": false,
        "perspective": "..."
    },
    "behavior_tree_view": {
        "default_zoom": 1.0,
        "auto_fit_on_load": true,
        "node_spacing": 50
    },
    "recent_files": [
        "/path/to/recent1.xml",
        "/path/to/recent2.xml"
    ]
}

Change Notifications

Register callbacks to be notified of preference changes:

// Register callback
int callbackId = prefs.RegisterChangeCallback([](const std::string& key) {
    if (key == "theme.mode") {
        // Theme changed, update UI
        ApplyTheme();
    }
});
 
// Unregister when done
prefs.UnregisterChangeCallback(callbackId);

PreferencesDialog

The UI for editing preferences:

PreferencesDialog dlg(parentWindow);
if (dlg.ShowModal() == wxID_OK) {
    // Preferences were saved
    // Changes already applied via callbacks
}

Dialog Sections

Section	Settings
General	Startup, language, updates
Appearance	Theme, colors, fonts
Editor	Grid, snapping, zoom
Parser	Profiles, validation
Keyboard	Shortcut customization

Best Practices

Reading Preferences

// Cache frequently-used values
class MyPanel {
    void OnPreferencesChanged(const std::string& key) {
        if (key.starts_with("theme.")) {
            m_cachedTheme = prefs.GetThemeMode();
            ApplyTheme();
        }
    }
 
    ThemeMode m_cachedTheme;
};

Providing Defaults

// Always provide sensible defaults
int zoom = prefs.GetInt("view.zoom", 100);  // Default: 100
bool grid = prefs.GetBool("view.show_grid", true);  // Default: true

Saving State

// Save state on close
void MainFrame::OnClose(wxCloseEvent& event) {
    auto& prefs = AppPreferencesManager::GetInstance();
 
    // Save window state
    prefs.SetWindowSettings(GetWindowSettings());
 
    // Save panel layout
    prefs.SetString("window.perspective",
                   m_auiManager.SavePerspective());
 
    // Persist to disk
    prefs.SavePreferences();
 
    event.Skip();
}

See Also

• UI Components - UI component system
• EmberForge::AppPreferencesManager - API reference
• EmberForge::PreferencesDialog - Preferences UI