GUI Backends

This section documents the different GUI backend implementations.

Qt Backend

Main GUI builder class that creates Qt applications from JSON configuration. Compatible with both PySide6 and PyQt6 via qtpy.

class qtpyguihelper.qt.gui_builder.GuiBuilder(*args, **kwargs)[source]

Bases: QMainWindow

Main GUI builder class that creates Qt applications from JSON configuration.

Parameters:

config_path (str | None)
config_dict (Dict[str, Any] | None)

formSubmitted: alias of dict

fieldChanged: alias of str

load_config_from_file(config_path)[source]

Load configuration from a JSON file and build the GUI.

Parameters:: config_path (str)
Return type:: None

load_config_from_dict(config_dict)[source]

Load configuration from a dictionary and build the GUI.

Parameters:: config_dict (Dict[str, Any])
Return type:: None

get_form_data()[source]

Get all form data as a dictionary.

Return type:: Dict[str, Any]

set_form_data(data)[source]

Set form data from a dictionary.

Parameters:: data (Dict[str, Any])

clear_form()[source]

Clear all form fields.

Return type:: None

get_field_value(field_name)[source]

Get the value of a specific field.

Parameters:: field_name (str)
Return type:: Any

set_field_value(field_name, value)[source]

Set the value of a specific field.

Parameters:

field_name (str)
value (Any)

Return type:

bool

set_submit_callback(callback)[source]

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

Parameters:: callback (Callable[[Dict[str, Any]], None])
Return type:: None

set_cancel_callback(callback)[source]

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

Parameters:: callback (Callable[[], None])
Return type:: None

set_custom_button_callback(button_name, callback)[source]

Set a callback function to be called when a custom button is clicked.

Parameters:

button_name (str) – The name of the custom button as defined in the configuration
callback (Callable[[Dict[str, Any]], None]) – Function to call when button is clicked. Receives form data as parameter.

Return type:

None

remove_custom_button_callback(button_name)[source]

Remove a custom button callback.

Parameters:: button_name (str)
Return type:: None

get_custom_button_names()[source]

Get a list of all custom button names from the configuration.

Return type:: List[str]

enable_field(field_name, enabled=True)[source]

Enable or disable a specific field.

Parameters:

field_name (str)
enabled (bool)

Return type:

None

show_field(field_name, visible=True)[source]

Show or hide a specific field.

Parameters:

field_name (str)
visible (bool)

Return type:

None

load_data_from_file(data_file_path)[source]

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

Parameters:: data_file_path (str) – Path to the JSON file containing form data
Returns:: True if successful, False otherwise
Return type:: bool

load_data_from_dict(data)[source]

Load form data from a dictionary and populate the GUI. Supports nested field names using dot notation.

Parameters:: data (Dict[str, Any]) – Dictionary containing form field values (can be nested)
Returns:: True if successful, False otherwise
Return type:: bool

save_data_to_file(data_file_path, include_empty=True)[source]

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

get_data_with_metadata()[source]

Get form data with additional metadata about the configuration.

Returns:: Dict containing form data plus metadata
Return type:: Dict[str, Any]

save_data_with_metadata_to_file(data_file_path)[source]

Save form data with metadata to a JSON file.

Parameters:: data_file_path (str) – Path where to save the JSON file
Returns:: True if successful, False otherwise
Return type:: bool

static create_and_run(config_path=None, config_dict=None, app_args=None)[source]

Create and run a GUI application.

Parameters:

config_path (str | None) – Path to JSON configuration file
config_dict (Dict[str, Any] | None) – Configuration dictionary (alternative to config_path)
app_args (list | None) – Arguments for QApplication (defaults to sys.argv)

Returns:

GuiBuilder instance

Return type:

GuiBuilder

Tkinter Backend

Main GUI builder class that creates tkinter applications from JSON configuration.

class qtpyguihelper.tk.tk_gui_builder.TkGuiBuilder(config_path=None, config_dict=None)[source]

Bases: object

Main GUI builder class that creates tkinter applications from JSON configuration.

Parameters:

config_path (str | None)
config_dict (Dict[str, Any] | None)

load_config_from_file(config_path)[source]

Load configuration from a JSON file.

Parameters:: config_path (str)

load_config_from_dict(config_dict)[source]

Load configuration from a dictionary.

Parameters:: config_dict (Dict[str, Any])

run()[source]: Run the GUI application (start the main loop).

show()[source]: Show the GUI window and bring it to the front.

hide()[source]: Hide the GUI window.

get_form_data()[source]

Get all form data as a dictionary.

Return type:: Dict[str, Any]

set_form_data(data)[source]

Set form data from a dictionary.

Parameters:: data (Dict[str, Any])

clear_form()[source]: Clear all form fields.

get_field_value(field_name)[source]

Get the value of a specific field.

Parameters:: field_name (str)
Return type:: Any

set_field_value(field_name, value)[source]

Set the value of a specific field.

Parameters:

field_name (str)
value (Any)

Return type:

bool

set_submit_callback(callback)[source]

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

Parameters:: callback (Callable[[Dict[str, Any]], None])

set_cancel_callback(callback)[source]

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

Parameters:: callback (Callable[[], None])

set_custom_button_callback(action_id, callback)[source]

Set a callback function for a custom button.

Parameters:

action_id (str)
callback (Callable[[CustomButtonConfig, Dict[str, Any]], None])

add_field_change_callback(field_name, callback)[source]

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

Parameters:

field_name (str)
callback (Callable[[str, Any], None])

save_data_to_file(data_file_path, include_empty=True)[source]

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)[source]

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)[source]

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

classmethod create_and_run(config_path=None, config_dict=None)[source]

Create a GUI builder and run it immediately.

Parameters:

config_path (str | None) – Path to JSON configuration file
config_dict (Dict[str, Any] | None) – Configuration dictionary (alternative to config_path)

Returns:

The created GUI builder instance

Return type:

TkGuiBuilder

close()[source]: Close the GUI application.

__del__()[source]: Cleanup when the object is destroyed.

Widget factory for creating tkinter widgets based on field configurations.

qtpyguihelper.tk.tk_widget_factory.set_nested_value(data, key_path, value)[source]

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., “global.project_name”)
value (Any) – The value to set

qtpyguihelper.tk.tk_widget_factory.get_nested_value(data, key_path, default=None)[source]

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., “global.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

qtpyguihelper.tk.tk_widget_factory.flatten_nested_dict(data, parent_key='', separator='.')[source]

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 qtpyguihelper.tk.tk_widget_factory.CustomColorButton(parent, initial_color='#ffffff', callback=None)[source]

Bases: Button

Custom button widget for color selection.

Parameters:

initial_color (str)
callback (Callable | None)

get_color()[source]

Get the current color.

Return type:: str

set_color(color)[source]

Set the current color.

Parameters:: color (str)

class qtpyguihelper.tk.tk_widget_factory.RadioButtonGroup(parent)[source]

Bases: object

Container for radio button groups.

add_button(text, value, **kwargs)[source]

Add a radio button to the group.

Parameters:

text (str)
value (str)

Return type:

Radiobutton

get_value()[source]

Get the selected value.

Return type:: str

set_value(value)[source]

Set the selected value.

Parameters:: value (str)

class qtpyguihelper.tk.tk_widget_factory.TkWidgetFactory[source]

Bases: object

Factory class for creating tkinter widgets based on field configurations.

set_theme_colors(theme_colors)[source]

Set theme colors for widgets.

Parameters:: theme_colors (Dict[str, str])

create_widget(parent, field_config)[source]

Create a widget based on the field configuration.

Parameters:

parent (Widget)
field_config (FieldConfig)

Return type:

Widget

create_label(parent, field_config)[source]

Create a label for the field.

Parameters:

parent (Widget)
field_config (FieldConfig)

Return type:

Label

add_change_callback(field_name, callback)[source]

Add a change callback for a field.

Parameters:

field_name (str)
callback (Callable)

get_widget_value(field_name)[source]

Get the current value of a widget.

Parameters:: field_name (str)
Return type:: Any

set_widget_value(field_name, value)[source]

Set the value of a widget.

Parameters:

field_name (str)
value (Any)

Return type:

bool

clear_widgets()[source]: Clear all widget values.

get_all_values()[source]

Get all widget values as a dictionary.

Return type:: Dict[str, Any]

set_all_values(data)[source]

Set all widget values from a dictionary.

Parameters:: data (Dict[str, Any])

wxPython Backend

wxPython GUI builder class that creates applications from JSON configuration.

class qtpyguihelper.wx.wx_gui_builder.WxGuiBuilder(*args, **kwargs)[source]

Bases: Frame

wxPython GUI builder class that creates applications from JSON configuration.

Parameters:

config_path (str | None)
config_dict (Dict[str, Any] | None)

load_config_from_file(config_path)[source]

Load configuration from a JSON file and build the GUI.

Parameters:: config_path (str)
Return type:: None

load_config_from_dict(config_dict)[source]

Load configuration from a dictionary and build the GUI.

Parameters:: config_dict (Dict[str, Any])
Return type:: None

get_form_data()[source]

Get all form data as a dictionary.

Return type:: Dict[str, Any]

set_form_data(data)[source]

Set form data from a dictionary.

Parameters:: data (Dict[str, Any])

clear_form()[source]: Clear all form fields.

get_field_value(field_name)[source]

Get the value of a specific field.

Parameters:: field_name (str)
Return type:: Any

set_field_value(field_name, value)[source]

Set the value of a specific field.

Parameters:

field_name (str)
value (Any)

Return type:

bool

set_submit_callback(callback)[source]

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

Parameters:: callback (Callable[[Dict[str, Any]], None])

set_cancel_callback(callback)[source]

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

Parameters:: callback (Callable[[], None])

set_custom_button_callback(button_name, callback)[source]

Set a callback function to be called when a custom button is clicked.

Parameters:

button_name (str) – The name of the custom button as defined in the configuration
callback (Callable[[Dict[str, Any]], None]) – Function to call when button is clicked. Receives form data as parameter.

remove_custom_button_callback(button_name)[source]

Remove a custom button callback.

Parameters:: button_name (str)

get_custom_button_names()[source]

Get a list of all custom button names from the configuration.

Return type:: List[str]

enable_field(field_name, enabled=True)[source]

Enable or disable a specific field.

Parameters:

field_name (str)
enabled (bool)

show_field(field_name, visible=True)[source]

Show or hide a specific field.

Parameters:

field_name (str)
visible (bool)

load_data_from_file(data_file_path)[source]

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

Parameters:: data_file_path (str)
Return type:: bool

load_data_from_dict(data)[source]

Load form data from a dictionary and populate the GUI.

Parameters:: data (Dict[str, Any])
Return type:: bool

save_data_to_file(data_file_path, include_empty=True)[source]

Save current form data to a JSON file.

Parameters:

data_file_path (str)
include_empty (bool)

Return type:

bool

static create_and_run(config_path=None, config_dict=None)[source]

Create and run a wxPython GUI application.

Parameters:

config_path (str | None)
config_dict (Dict[str, Any] | None)

Return type:

WxGuiBuilder

wxPython widget factory for creating widgets based on field configurations.

qtpyguihelper.wx.wx_widget_factory.set_nested_value(data, key_path, value)[source]

Set a value in a nested dictionary using dot notation.

Parameters:

data (Dict[str, Any])
key_path (str)
value (Any)

qtpyguihelper.wx.wx_widget_factory.get_nested_value(data, key_path, default=None)[source]

Get a value from a nested dictionary using dot notation.

Parameters:

data (Dict[str, Any])
key_path (str)
default (Any | None)

Return type:

Any

class qtpyguihelper.wx.wx_widget_factory.WxCustomColorButton(*args, **kwargs)[source]

Bases: Button

Custom button widget for color selection in wxPython.

get_color()[source]

Get the current selected color.

Return type:: wx.Colour

set_color(color)[source]

Set the current color.

Parameters:: color (wx.Colour)

class qtpyguihelper.wx.wx_widget_factory.WxCustomFileButton(*args, **kwargs)[source]

Bases: Button

Custom button widget for file selection in wxPython.

get_file_path()[source]

Get the selected file path.

Return type:: str

set_file_path(path)[source]

Set the file path.

Parameters:: path (str)

class qtpyguihelper.wx.wx_widget_factory.WxWidgetFactory[source]

Bases: object

Factory class for creating wxPython widgets from field configurations.

create_widget(parent, field_config)[source]

Create a widget based on the field configuration.

Parameters:

parent (wx.Window)
field_config (FieldConfig)

Return type:

wx.Window | None

create_label(parent, field_config)[source]

Create a label for the field.

Parameters:

parent (wx.Window)
field_config (FieldConfig)

Return type:

wx.StaticText

get_widget_value(field_name)[source]

Get the current value of a widget.

Parameters:: field_name (str)
Return type:: Any

set_widget_value(field_name, value)[source]

Set the value of a widget.

Parameters:

field_name (str)
value (Any)

Return type:

bool

get_all_values()[source]

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

Return type:: Dict[str, Any]

clear_all_widgets()[source]: Clear all widget values.

GTK Backend

Main GUI builder class that creates GTK applications from JSON configuration.

class qtpyguihelper.gtk.gtk_gui_builder.GtkGuiBuilder(config_path=None, config_dict=None, submit_callback=None, cancel_callback=None)[source]

Bases: object

Main GUI builder class that creates GTK applications from JSON configuration.

Parameters:

config_path (str | None)
config_dict (Dict[str, Any] | None)
submit_callback (Callable | None)
cancel_callback (Callable | None)

load_config_from_file(config_path)[source]

Load configuration from a JSON file.

Parameters:: config_path (str)

load_config_from_dict(config_dict)[source]

Load configuration from a dictionary.

Parameters:: config_dict (Dict[str, Any])

show()[source]: Show the GUI window and bring it to the front (cross-platform).

hide()[source]: Hide the GUI window.

run()[source]: Run the GUI application (start the main loop).

get_form_data()[source]

Get all form data as a dictionary.

Return type:: Dict[str, Any]

save_data_to_file(data_file_path, include_empty=True)[source]

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)[source]

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)[source]

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

set_form_data(data)[source]

Set form data from a dictionary.

Parameters:: data (Dict[str, Any])

clear_form()[source]: Clear all form fields.

get_field_value(field_name)[source]

Get the value of a specific field.

Parameters:: field_name (str)
Return type:: Any

set_field_value(field_name, value)[source]

Set the value of a specific field.

Parameters:

field_name (str)
value (Any)

Return type:

bool

set_submit_callback(callback)[source]

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

Parameters:: callback (Callable[[Dict[str, Any]], None])

set_cancel_callback(callback)[source]

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

Parameters:: callback (Callable[[], None])

set_custom_button_callback(action_id, callback)[source]

Set a callback function for a custom button.

Parameters:

action_id (str)
callback (Callable[[CustomButtonConfig, Dict[str, Any]], None])

add_field_change_callback(field_name, callback)[source]

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

Parameters:

field_name (str)
callback (Callable[[str, Any], None])

get_custom_button_names()[source]

Get list of custom button names.

Return type:: List[str]

classmethod create_and_run(config_path=None, config_dict=None)[source]

Create a GUI builder and run it immediately.

Parameters:

config_path (str | None) – Path to JSON configuration file
config_dict (Dict[str, Any] | None) – Configuration dictionary (alternative to config_path)

Returns:

The created GUI builder instance

Return type:

GtkGuiBuilder

close()[source]: Close the GUI application.

__del__()[source]: Cleanup when the object is destroyed.

property backend: str: Return the backend name with version info.

Widget factory for creating GTK widgets from field configurations.

class qtpyguihelper.gtk.gtk_widget_factory.GtkWidgetFactory[source]

Bases: object

Factory for creating GTK widgets from field configurations.

create_label(parent, field_config)[source]

Create a label for a field.

Parameters:

parent (gi.repository.Gtk.Widget)
field_config (FieldConfig)

Return type:

gi.repository.Gtk.Label

create_widget(parent, field_config)[source]

Create a widget based on the field configuration.

Parameters:

parent (gi.repository.Gtk.Widget)
field_config (FieldConfig)

Return type:

gi.repository.Gtk.Widget | None

get_widget_value(field_name)[source]

Get the current value of a widget.

Parameters:: field_name (str)
Return type:: Any

set_widget_value(field_name, value)[source]

Set the value of a widget.

Parameters:

field_name (str)
value (Any)

Return type:

bool

get_all_values()[source]

Get values from all widgets.

Return type:: Dict[str, Any]

set_all_values(values)[source]

Set values for all widgets from a dictionary.

Parameters:: values (Dict[str, Any])

clear_widgets()[source]: Clear all widget values.

add_change_callback(field_name, callback)[source]

Add a change callback for a field.

Parameters:

field_name (str)
callback (Callable[[str, Any], None])