Examples

This section provides comprehensive examples showing how to use vibegui in different scenarios.

Basic Examples

Simple Form

Here’s a simple contact form example:

"""Simple contact form example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

config = {
    "window": {
        "title": "Contact Form",
        "width": 400,
        "height": 350
    },
    "fields": [
        {
            "name": "name",
            "label": "Full Name",
            "type": "text",
            "required": True,
            "placeholder": "Enter your full name"
        },
        {
            "name": "email",
            "label": "Email",
            "type": "email",
            "required": True,
            "placeholder": "your.email@example.com"
        },
        {
            "name": "phone",
            "label": "Phone Number",
            "type": "text",
            "placeholder": "+1 (555) 123-4567"
        },
        {
            "name": "message",
            "label": "Message",
            "type": "textarea",
            "required": True,
            "placeholder": "Enter your message here..."
        }
    ],
    "submit_button": True,
    "submit_label": "Send Message",
    "cancel_button": True
}

def handle_submit(data):
    print("Contact form submitted:")
    for key, value in data.items():
        print(f"  {key}: {value}")


if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.set_submit_callback(handle_submit)
    gui.show()

    sys.exit(app.exec())

Advanced Form with Validation

"""Advanced form with validation example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

config = {
    "window": {
        "title": "User Registration",
        "width": 500,
        "height": 600
    },
    "fields": [
        {
            "name": "username",
            "label": "Username",
            "type": "text",
            "required": True,
            "placeholder": "Choose a username",
            "tooltip": "Username must be unique"
        },
        {
            "name": "password",
            "label": "Password",
            "type": "password",
            "required": True,
            "tooltip": "Password must be at least 8 characters"
        },
        {
            "name": "confirm_password",
            "label": "Confirm Password",
            "type": "password",
            "required": True
        },
        {
            "name": "email",
            "label": "Email Address",
            "type": "email",
            "required": True
        },
        {
            "name": "age",
            "label": "Age",
            "type": "number",
            "min_value": 13,
            "max_value": 120,
            "required": True
        },
        {
            "name": "country",
            "label": "Country",
            "type": "select",
            "options": ["USA", "Canada", "UK", "Australia", "Germany", "France"],
            "required": True
        },
        {
            "name": "birthdate",
            "label": "Birth Date",
            "type": "date",
            "required": True
        },
        {
            "name": "terms",
            "label": "I agree to the terms and conditions",
            "type": "checkbox",
            "required": True
        }
    ],
    "submit_button": True,
    "submit_label": "Register",
    "cancel_button": True
}

def validate_registration(data):
    # Custom validation
    if data.get('password') != data.get('confirm_password'):
        print("Error: Passwords do not match")
        return False

    if len(data.get('password', '')) < 8:
        print("Error: Password must be at least 8 characters")
        return False

    return True

def handle_registration(data):
    if validate_registration(data):
        print("Registration successful!")
        print(f"Welcome, {data['username']}!")
    else:
        print("Registration failed. Please check your inputs.")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.set_submit_callback(handle_registration)
    gui.show()

    sys.exit(app.exec())

Tabbed Interface Example

"""Tabbed interface example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

config = {
    "window": {
        "title": "Employee Management",
        "width": 600,
        "height": 500
    },
    "fields": [
        # Personal Information fields
        {"name": "first_name", "label": "First Name", "type": "text", "required": True},
        {"name": "last_name", "label": "Last Name", "type": "text", "required": True},
        {"name": "employee_id", "label": "Employee ID", "type": "text", "required": True},
        {"name": "department", "label": "Department", "type": "select",
         "options": ["Engineering", "Sales", "Marketing", "HR", "Finance"]},
        {"name": "hire_date", "label": "Hire Date", "type": "date", "required": True},
        # Contact Details fields
        {"name": "email", "label": "Work Email", "type": "email", "required": True},
        {"name": "phone", "label": "Phone Number", "type": "text"},
        {"name": "emergency_contact", "label": "Emergency Contact", "type": "text"},
        {"name": "address", "label": "Address", "type": "textarea"},
        # Job Details fields
        {"name": "position", "label": "Position", "type": "text", "required": True},
        {"name": "salary", "label": "Salary", "type": "number", "min_value": 0},
        {"name": "full_time", "label": "Full-time Employee", "type": "checkbox", "default_value": True},
        {"name": "start_time", "label": "Start Time", "type": "time"},
        {"name": "benefits", "label": "Benefits Package", "type": "select",
         "options": ["Basic", "Standard", "Premium"]}
    ],
    "use_tabs": True,
    "tabs": [
        {
            "name": "personal_info",
            "title": "Personal Information",
            "fields": ["first_name", "last_name", "employee_id", "department", "hire_date"]
        },
        {
            "name": "contact_details",
            "title": "Contact Details",
            "fields": ["email", "phone", "emergency_contact", "address"]
        },
        {
            "name": "job_details",
            "title": "Job Details",
            "fields": ["position", "salary", "full_time", "start_time", "benefits"]
        }
    ],
    "submit_button": True,
    "submit_label": "Save Employee",
    "cancel_button": True
}

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.show()

    sys.exit(app.exec())

Custom Buttons Example

"""Custom buttons example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

config = {
    "window": {"title": "Data Entry Form", "width": 500, "height": 400},
    "fields": [
        {"name": "name", "label": "Name", "type": "text"},
        {"name": "email", "label": "Email", "type": "email"},
        {"name": "notes", "label": "Notes", "type": "textarea"}
    ],
    "custom_buttons": [
        {
            "name": "clear_form",
            "label": "Clear All",
            "style": "background-color: #ff6b6b; color: white;"
        },
        {
            "name": "load_template",
            "label": "Load Template",
            "style": "background-color: #4ecdc4; color: white;"
        },
        {
            "name": "save_draft",
            "label": "Save Draft",
            "style": "background-color: #45b7d1; color: white;"
        }
    ],
    "submit_button": True,
    "cancel_button": True
}

def clear_form(button_config, form_data):
    gui.clear_form()
    print("Form cleared!")

def load_template(button_config, form_data):
    template_data = {
        "name": "John Template",
        "email": "template@example.com",
        "notes": "This is a template entry."
    }
    gui.set_form_data(template_data)
    print("Template loaded!")

def save_draft(button_config, form_data):
    gui.save_data_to_file("draft.json")
    print("Draft saved!")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.set_custom_button_callback('clear_form', clear_form)
    gui.set_custom_button_callback('load_template', load_template)
    gui.set_custom_button_callback('save_draft', save_draft)
    gui.show()

    sys.exit(app.exec())

Data Persistence Example

"""Data persistence example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

config = {
    "window": {"title": "Settings Manager", "width": 450, "height": 350},
    "fields": [
        {"name": "theme", "label": "Theme", "type": "select",
         "options": ["Light", "Dark", "Auto"], "default_value": "Auto"},
        {"name": "language", "label": "Language", "type": "select",
         "options": ["English", "Spanish", "French", "German"]},
        {"name": "auto_save", "label": "Auto-save", "type": "checkbox", "default_value": True},
        {"name": "backup_interval", "label": "Backup Interval (hours)", "type": "number",
         "min_value": 1, "max_value": 24, "default_value": 6}
    ],
    "custom_buttons": [
        {"name": "load_settings", "label": "Load Settings"},
        {"name": "save_settings", "label": "Save Settings"},
        {"name": "reset_defaults", "label": "Reset to Defaults"}
    ]
}

settings_file = "user_settings.json"

def load_settings(button_config, form_data):
    if os.path.exists(settings_file):
        if gui.load_data_from_file(settings_file):
            print("Settings loaded successfully!")
        else:
            print("Failed to load settings.")
    else:
        print("No saved settings found.")

def save_settings(button_config, form_data):
    if gui.save_data_to_file(settings_file):
        print("Settings saved successfully!")
    else:
        print("Failed to save settings.")

def reset_defaults(button_config, form_data):
    defaults = {
        "theme": "Auto",
        "language": "English",
        "auto_save": True,
        "backup_interval": 6
    }
    gui.set_form_data(defaults)
    print("Settings reset to defaults!")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.set_custom_button_callback('load_settings', load_settings)
    gui.set_custom_button_callback('save_settings', save_settings)
    gui.set_custom_button_callback('reset_defaults', reset_defaults)

    # Auto-load settings on startup
    if os.path.exists(settings_file):
        gui.load_data_from_file(settings_file)

    gui.show()

    sys.exit(app.exec())

Field Change Callbacks

"""Field change callbacks example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

config = {
    "window": {"title": "Dynamic Form", "width": 400, "height": 300},
    "fields": [
        {"name": "user_type", "label": "User Type", "type": "select",
         "options": ["Student", "Teacher", "Administrator"], "required": True},
        {"name": "student_id", "label": "Student ID", "type": "text"},
        {"name": "grade_level", "label": "Grade Level", "type": "number", "min_value": 1, "max_value": 12},
        {"name": "department", "label": "Department", "type": "text"},
        {"name": "admin_level", "label": "Admin Level", "type": "select",
         "options": ["Level 1", "Level 2", "Level 3"]}
    ]
}

def on_user_type_change(field_name, value):
    print(f"User type changed to: {value}")

    # Enable/disable fields based on user type
    if value == "Student":
        gui.set_field_value("student_id", "")
        gui.set_field_value("grade_level", "")
        # In a real implementation, you would show/hide fields here
        print("Showing student-specific fields")
    elif value == "Teacher":
        gui.set_field_value("department", "")
        print("Showing teacher-specific fields")
    elif value == "Administrator":
        gui.set_field_value("admin_level", "")
        print("Showing administrator-specific fields")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.add_field_change_callback('user_type', on_user_type_change)
    gui.show()

    sys.exit(app.exec())

Layout Examples

Different layout styles for organizing fields:

"""Layout examples showing different field organization styles."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

# Vertical layout (default - stacks fields vertically)
vertical_config = {
    "window": {"title": "Vertical Layout", "width": 400, "height": 400},
    "layout": "vertical",
    "fields": [
        {"name": "field1", "label": "Field 1", "type": "text"},
        {"name": "field2", "label": "Field 2", "type": "text"},
        {"name": "field3", "label": "Field 3", "type": "number"}
    ]
}

# Horizontal layout (arranges fields in a row)
horizontal_config = {
    "window": {"title": "Horizontal Layout", "width": 600, "height": 200},
    "layout": "horizontal",
    "fields": [
        {"name": "first", "label": "First", "type": "text"},
        {"name": "middle", "label": "Middle", "type": "text"},
        {"name": "last", "label": "Last", "type": "text"}
    ]
}

# Grid layout (responsive 2-column grid)
grid_config = {
    "window": {"title": "Grid Layout", "width": 600, "height": 400},
    "layout": "grid",
    "fields": [
        {"name": "fname", "label": "First Name", "type": "text"},
        {"name": "lname", "label": "Last Name", "type": "text"},
        {"name": "email", "label": "Email", "type": "email"},
        {"name": "phone", "label": "Phone", "type": "text"},
        {"name": "city", "label": "City", "type": "text"},
        {"name": "state", "label": "State", "type": "text"}
    ]
}

# Form layout (label-field pairs)
form_config = {
    "window": {"title": "Form Layout", "width": 500, "height": 400},
    "layout": "form",
    "fields": [
        {"name": "username", "label": "Username", "type": "text"},
        {"name": "password", "label": "Password", "type": "password"},
        {"name": "remember", "label": "Remember me", "type": "checkbox"}
    ]
}

# Use different layouts in tabs
tabbed_layout_config = {
    "window": {"title": "Mixed Layouts", "width": 600, "height": 500},
    "fields": [
        {"name": "v1", "label": "Field 1", "type": "text"},
        {"name": "v2", "label": "Field 2", "type": "text"},
        {"name": "g1", "label": "Field 1", "type": "text"},
        {"name": "g2", "label": "Field 2", "type": "text"},
        {"name": "g3", "label": "Field 3", "type": "text"},
        {"name": "g4", "label": "Field 4", "type": "text"}
    ],
    "use_tabs": True,
    "tabs": [
        {
            "name": "vertical_tab",
            "title": "Vertical Tab",
            "layout": "vertical",
            "fields": ["v1", "v2"]
        },
        {
            "name": "grid_tab",
            "title": "Grid Tab",
            "layout": "grid",
            "fields": ["g1", "g2", "g3", "g4"]
        }
    ]
}

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=grid_config, backend='qt')
    gui.show()

    sys.exit(app.exec())

Nested Fields Example

Using dot notation for hierarchical data structures:

"""Nested fields example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import json
import os

config = {
    "window": {"title": "Application Settings", "width": 600, "height": 500},
    "layout": "form",
    "fields": [
        # Global settings
        {"name": "global.app_name", "label": "Application Name",
         "type": "text", "default_value": "My App"},
        {"name": "global.version", "label": "Version",
         "type": "text", "default_value": "1.0.0"},

        # Database settings
        {"name": "database.host", "label": "Database Host",
         "type": "text", "default_value": "localhost"},
        {"name": "database.port", "label": "Database Port",
         "type": "int", "default_value": 5432},
        {"name": "database.name", "label": "Database Name",
         "type": "text", "required": True},

        # UI settings
        {"name": "ui.theme", "label": "Theme",
         "type": "select", "options": ["light", "dark", "auto"],
         "default_value": "auto"},
        {"name": "ui.font_size", "label": "Font Size",
         "type": "int", "min_value": 8, "max_value": 24, "default_value": 12}
    ],
    "submit_button": True
}

def on_submit(data):
    print("Settings saved:")
    print(json.dumps(data, indent=2))
    # Output will be nested:
    # {
    #   "global": {"app_name": "...", "version": "..."},
    #   "database": {"host": "...", "port": ..., "name": "..."},
    #   "ui": {"theme": "...", "font_size": ...}
    # }

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.set_submit_callback(on_submit)
    gui.show()

    sys.exit(app.exec())

Float Formatting Example

Controlling decimal precision for float fields:

"""Float formatting example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os

config = {
    "window": {"title": "Measurements", "width": 500, "height": 500},
    "layout": "form",
    "fields": [
        {"name": "price", "label": "Price ($)", "type": "float",
         "format_string": ".2f", "default_value": 99.99},

        {"name": "temperature", "label": "Temperature (°C)", "type": "float",
         "format_string": ".1f", "default_value": 23.5},

        {"name": "precision", "label": "High Precision", "type": "float",
         "format_string": ".4f", "default_value": 3.1416},

        {"name": "scientific", "label": "Large Number", "type": "float",
         "format_string": ".2e", "default_value": 1234567.89},

        {"name": "percentage", "label": "Completion", "type": "float",
         "format_string": ".1%", "default_value": 0.856},

        {"name": "currency", "label": "Revenue", "type": "float",
         "format_string": ",.2f", "default_value": 12345.67}
    ],
    "submit_button": True
}

if __name__ == "__main__":
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_dict=config, backend='qt')
    gui.show()

    sys.exit(app.exec())

Loading from JSON Files

Create a JSON configuration file:

{
    "window": {
        "title": "My Application",
        "width": 500,
        "height": 400
    },
    "fields": [
        {
            "name": "title",
            "label": "Title",
            "type": "select",
            "options": ["Mr.", "Ms.", "Dr.", "Prof."],
            "required": true
        },
        {
            "name": "name",
            "label": "Full Name",
            "type": "text",
            "required": true
        }
    ],
    "submit_button": true,
    "cancel_button": true
}

Then load it in Python:

"""JSON configuration loading example."""
from vibegui import GuiBuilder
from qtpy.QtWidgets import QApplication
import sys
import os
from pathlib import Path

# Get the path to the example JSON file
example_json = Path(__file__).parent / "example_config.json"

if __name__ == "__main__":
    # Load from JSON file
    app = QApplication(sys.argv)
    gui = GuiBuilder(config_path=str(example_json), backend='qt')
    gui.show()

    sys.exit(app.exec())

For more examples, check the examples/ directory in the vibegui repository.