Utilities

Utility classes and functions for validation, file operations, and platform detection.

Common utilities used across different GUI backends.

vibegui.utils.set_nested_value(data, key_path, value)

Set a value in a nested dictionary using dot notation.

Parameters:

• data (Dict[str, Any]) – The dictionary to modify

• key_path (str) – Dot-separated key path (e.g., “project.name”)

• value (Any) – The value to set

Return type:

None

vibegui.utils.get_nested_value(data, key_path, default=None)

Get a value from a nested dictionary using dot notation.

Parameters:

• data (Dict[str, Any]) – The dictionary to search

• key_path (str) – Dot-separated key path (e.g., “project.name”)

• default (Any | None) – Default value if key not found

Returns:

The value at the key path, or default if not found

Return type:

Any

vibegui.utils.flatten_nested_dict(data, parent_key='', separator='.')

Flatten a nested dictionary into a flat dictionary with dot notation keys.

Parameters:

• data (Dict[str, Any]) – The nested dictionary to flatten

• parent_key (str) – The parent key path (for recursion)

• separator (str) – The separator to use (default: ‘.’)

Returns:

Flattened dictionary with dot notation keys

Return type:

Dict[str, Any]

class vibegui.utils.NestedValueMixin

Bases: object

Mixin providing get_all_values and set_all_values with nested field support.

Assumes the class has: - self.widgets: Dict[str, Any] - dictionary of field name to widget - get_widget_value(field_name: str) -> Any - method to get value from a widget - set_widget_value(field_name: str, value: Any) -> bool - method to set value on a widget

get_all_values()

Get values from all widgets, creating nested dictionaries for dot notation field names.

Return type:

Dict[str, Any]

set_all_values(values)

Set values for all widgets from a dictionary, supporting nested structures.

Parameters:

values (Dict[str, Any])

Return type:

None

class vibegui.utils.WidgetFactoryMixin

Bases: object

Mixin providing common widget factory delegation methods.

Assumes the class has a self.widget_factory attribute. Provides standardized methods for form data manipulation and field access.

get_form_data()

Get all form data as a dictionary.

Return type:

Dict[str, Any]

set_form_data(data)

Set form data from a dictionary.

Parameters:

data (Dict[str, Any])

Return type:

None

clear_form()

Clear all form fields.

Return type:

None

get_field_value(field_name)

Get the value of a specific field.

Parameters:

field_name (str)

Return type:

Any

set_field_value(field_name, value)

Set the value of a specific field.

Parameters:

• field_name (str)

• value (Any)

Return type:

bool

class vibegui.utils.FieldStateMixin

Bases: object

Mixin providing common field state management methods.

Assumes the class has a self.widget_factory attribute with widgets dict. Subclasses must implement _enable_widget and _show_widget methods for their specific backend.

enable_field(field_name, enabled=True)

Enable or disable a specific field.

Parameters:

• field_name (str)

• enabled (bool)

Return type:

None

show_field(field_name, visible=True)

Show or hide a specific field.

Parameters:

• field_name (str)

• visible (bool)

Return type:

None

class vibegui.utils.ButtonHandlerMixin

Bases: object

Mixin providing common button click handler logic.

Assumes the class has: - _validate_required_fields() -> bool - get_form_data() -> Dict[str, Any] - submit_callback, cancel_callback, custom_button_callbacks attributes - _show_error(message: str) method

class vibegui.utils.ConfigLoaderMixin

Bases: object

Mixin providing common configuration loading logic.

Assumes the class has: - self.config_loader attribute - self.config attribute to store loaded config - _build_gui() or _build_ui() method (optional if _should_build_ui_on_config_load returns False)

load_config_from_file(config_path)

Load configuration from a JSON file and optionally build GUI.

Parameters:

config_path (str)

Return type:

None

load_config_from_dict(config_dict)

Load configuration from a dictionary and optionally build GUI.

Parameters:

config_dict (Dict[str, Any])

Return type:

None

class vibegui.utils.CallbackManagerMixin(*args, **kwargs)

Bases: object

Mixin providing common callback management functionality for GUI builders.

Provides standardized callback storage and setter methods for: - submit_callback: Called when form is submitted - cancel_callback: Called when form is cancelled - custom_button_callbacks: Dictionary of callbacks for custom buttons - field_change_callbacks: Dictionary of callbacks for field changes

set_submit_callback(callback)

Set a callback function to be called when the form is submitted.

Parameters:

callback (Callable[[Dict[str, Any]], None]) – Function that takes form data dict as argument

Return type:

None

set_cancel_callback(callback)

Set a callback function to be called when the form is cancelled.

Parameters:

callback (Callable[[], None]) – Function with no arguments

Return type:

None

set_custom_button_callback(button_id, callback)

Set a callback function for a custom button.

Parameters:

• button_id (str) – ID/name of the custom button

• callback (Callable) – Callback function (signature may vary by backend)

Return type:

None

remove_custom_button_callback(button_id)

Remove a custom button callback.

Parameters:

button_id (str) – ID/name of the custom button

Return type:

None

get_custom_button_names()

Get list of custom button IDs/names.

Returns:

List of button IDs that have been configured

Return type:

List[str]

add_field_change_callback(field_name, callback)

Add a callback function to be called when a field value changes.

Parameters:

• field_name (str) – Name of the field to monitor

• callback (Callable[[str, Any], None]) – Function that takes (field_name, value) as arguments

Return type:

None

class vibegui.utils.ValidationMixin

Bases: object

Mixin providing common validation functionality for GUI builders.

Classes using this mixin must implement: - get_form_data() -> Dict[str, Any]: Get current form data - _show_error(*args, **kwargs) -> None: Show error dialog

class vibegui.utils.DataPersistenceMixin

Bases: object

Mixin providing common data loading/saving functionality for GUI builders.

Classes using this mixin must implement: - get_form_data() -> Dict[str, Any]: Get current form data - set_form_data(data: Dict[str, Any]) -> None: Set form data - _show_error(*args, **kwargs) -> None: Show error dialog (optional, for error handling)

save_data_to_file(data_file_path, include_empty=True)

Save current form data to a JSON file.

Parameters:

• data_file_path (str) – Path where to save the JSON file

• include_empty (bool) – Whether to include fields with empty/None values

Returns:

True if successful, False otherwise

Return type:

bool

load_data_from_file(data_file_path)

Load form data from a JSON file and populate the GUI.

Parameters:

data_file_path (str) – Path to the JSON file to load

Returns:

True if successful, False otherwise

Return type:

bool

load_data_from_dict(data)

Load form data from a dictionary and populate the GUI.

Parameters:

data (Dict[str, Any]) – Dictionary containing the form data

Returns:

True if successful, False otherwise

Return type:

bool

class vibegui.utils.ValidationUtils

Bases: object

Utilities for validating form data and configurations.

static validate_required_fields(form_data, required_fields)

Validate that all required fields have values.

Parameters:

• form_data (Dict[str, Any]) – Dictionary of form field values (may be nested)

• required_fields (List[str]) – List of field names that are required (may use dot notation)

Returns:

List of missing field names (empty if all valid)

Return type:

List[str]

static validate_numeric_range(value, min_val=None, max_val=None)

Validate that a numeric value is within the specified range.

Parameters:

• value (int | float) – The numeric value to validate

• min_val (float | None) – Minimum allowed value (inclusive)

• max_val (float | None) – Maximum allowed value (inclusive)

Returns:

True if value is within range, False otherwise

Return type:

bool

class vibegui.utils.FileUtils

Bases: object

Utilities for file operations.

static save_data_to_json(data, file_path, include_empty=True)

Save data to a JSON file.

Parameters:

• data (Dict[str, Any]) – Data to save

• file_path (str) – Path to save the file

• include_empty (bool) – Whether to include empty/None values

Returns:

True if successful, False otherwise

Return type:

bool

static load_data_from_json(file_path)

Load data from a JSON file.

Parameters:

file_path (str) – Path to the JSON file

Returns:

Loaded data dictionary, or None if failed

Return type:

Dict[str, Any] | None

class vibegui.utils.PlatformUtils

Bases: object

Utilities for platform-specific operations.

static get_system()

Get the current operating system.

Return type:

str

static is_macos()

Check if running on macOS.

Return type:

bool

static is_windows()

Check if running on Windows.

Return type:

bool

static is_linux()

Check if running on Linux.

Return type:

bool

static is_dark_mode()

Detect if the system is using dark mode.

Returns:

True if dark mode is detected, False otherwise

Return type:

bool

class vibegui.utils.FormatUtils

Bases: object

Utilities for formatting values.

static format_float(value, format_string=None)

Format a float value according to the specified format string.

Parameters:

• value (float) – The float value to format

• format_string (str | None) – Format string (e.g., “.2f”, “.4f”)

Returns:

Formatted string representation

Return type:

str

static parse_float(value_str)

Parse a string to float, returning None if invalid.

Parameters:

value_str (str) – String to parse

Returns:

Parsed float value or None

Return type:

float | None

static parse_int(value_str)

Parse a string to int, returning None if invalid.

Parameters:

value_str (str) – String to parse

Returns:

Parsed int value or None

Return type:

int | None

class vibegui.utils.LayoutUtils

Bases: object

Utilities for layout calculations and adjustments.

static calculate_window_center(window_width, window_height, screen_width, screen_height)

Calculate the center position for a window.

Parameters:

• window_width (int) – Width of the window

• window_height (int) – Height of the window

• screen_width (int) – Width of the screen

• screen_height (int) – Height of the screen

Returns:

Tuple of (x, y) coordinates for centering

Return type:

tuple

static get_recommended_widget_sizes()

Get recommended widget sizes for different field types.

Returns:

Dictionary mapping field types to size recommendations

Return type:

Dict[str, Dict[str, int]]