Class: MittensUi::Application

Inherits:
Object
  • Object
show all
Defined in:
lib/mittens_ui.rb

Overview

The main application class for MittensUi. Responsible for bootstrapping the GTK application, managing the window, layout, and providing access to shared application state like the persistent store.

Examples:

Basic application setup

MittensUi::Application.Window(name: "my_app", title: "My App", width: 400, height: 600) do
  MittensUi::Label.new("Hello World!")
  MittensUi::Button.new(title: "Click Me")
end

Accessing the persistent store

MittensUi::Application.store.set(:theme, "dark")
MittensUi::Application.store.get(:theme)  # => "dark"

Exiting the application

MittensUi::Application.exit { puts "Goodbye!" }

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.app_id ⇒ String (readonly)

The GTK application ID in reverse-domain format.

Returns:

  • (String) —

    e.g. “org.mittens_ui.my_app”



67
68
69
 
# File 'lib/mittens_ui.rb', line 67

def app_id
  @app_id
end

.gtk_app ⇒ Gtk::Application (readonly)

The underlying Gtk::Application instance.

Returns:

  • (Gtk::Application) 


55
56
57
 
# File 'lib/mittens_ui.rb', line 55

def gtk_app
  @gtk_app
end

.layout ⇒ MittensUi::LayoutManager (readonly)

The layout manager responsible for placing widgets in the window.

Returns:



59
60
61
 
# File 'lib/mittens_ui.rb', line 59

def layout
  @layout
end

.window ⇒ Gtk::ApplicationWindow (readonly)

The main application window.

Returns:

  • (Gtk::ApplicationWindow) 


63
64
65
 
# File 'lib/mittens_ui.rb', line 63

def window
  @window
end

Class Method Details

.apply_theme(theme) ⇒ void

This method returns an undefined value.

Applies the theme based on the given mode. Respects the system preference when set to :system.

Parameters:

  • theme (Symbol) —

    :dark, :light, or :system



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/mittens_ui.rb', line 115

def apply_theme(theme)
  settings = Gtk::Settings.default
  case theme
  when :dark
    settings.gtk_application_prefer_dark_theme = true
  when :light
    begin
      settings.reset_property('gtk-application-prefer-dark-theme')
      settings.gtk_application_prefer_dark_theme = false
    rescue
      settings.gtk_application_prefer_dark_theme = false
    end
  when :system
    begin
      settings.reset_property('gtk-application-prefer-dark-theme')
    rescue
      settings.gtk_application_prefer_dark_theme = false
    end
  end
  @current_theme = theme
  @window&.queue_draw
end

.current_container ⇒ MittensUi::HBox?

Returns the currently active container, or nil if no container is active. When non-nil, Core#render will add newly created widgets to this container instead of the main layout grid. Supports nested HBox instances by always returning the innermost active container.

Returns:

See Also:



106
107
108
 
# File 'lib/mittens_ui.rb', line 106

def current_container
  @container_stack&.last
end

.current_theme ⇒ Symbol

Returns the current theme.

Returns:

  • (Symbol) —

    :dark, :light, or :system



141
142
143
 
# File 'lib/mittens_ui.rb', line 141

def current_theme
  @current_theme || :system
end

.exit { ... } ⇒ void

This method returns an undefined value.

Exits the application cleanly, optionally running a block before quitting. If the block raises an error, the application exits with code 1. Always quits the GTK application loop via #gtk_app.

Examples:

MittensUi::Application.exit { puts "Saving data..." }

Yields:

  • optional block to run before exiting



187
188
189
190
191
192
193
194
195
196
 
# File 'lib/mittens_ui.rb', line 187

def exit(&block)
  begin
    block.call if block_given?
  rescue => e
    puts("Exiting with: #{e}")
    Kernel.exit(1)
  ensure
    gtk_app&.quit
  end
end

.pop_container ⇒ MittensUi::HBox?

Pops the most recently pushed container off the stack, restoring the previous container (or the main layout if the stack is empty) as the active render target. Called automatically by HBox after its block finishes evaluating.

Returns:

  • (MittensUi::HBox, nil) —

    the container that was removed, or nil if stack was empty

See Also:



92
93
94
95
 
# File 'lib/mittens_ui.rb', line 92

def pop_container
  @container_stack ||= []
  @container_stack.pop
end

.push_container(container) ⇒ Array

Pushes a container onto the container stack, making it the active container for widget rendering. Any widgets created after this call will render into this container instead of the main layout grid. Used internally by HBox to support block-style widget creation and nested HBox instances.

Parameters:

Returns:

  • (Array) —

    the updated container stack

See Also:



79
80
81
82
 
# File 'lib/mittens_ui.rb', line 79

def push_container(container)
  @container_stack ||= []
  @container_stack.push(container)
end

.store ⇒ MittensUi::Store

Returns the persistent store for this application. The store is lazily initialized on first access and scoped to the application name.

Examples:

MittensUi::Application.store.set(:last_user, "John")
MittensUi::Application.store.get(:last_user)  # => "John"

Returns:



206
207
208
 
# File 'lib/mittens_ui.rb', line 206

def store
  @store ||= Store.new(@app_id)
end

.toggle_theme ⇒ void

This method returns an undefined value.

Toggles between dark and light mode at runtime.

Examples:

btn.click { MittensUi::Application.toggle_theme }


150
151
152
153
 
# File 'lib/mittens_ui.rb', line 150

def toggle_theme
  new_theme = current_theme == :dark ? :light : :dark
  apply_theme(new_theme)
end

.Window(options = {}) {|window| ... } ⇒ void

This method returns an undefined value.

Creates and runs the main application window. This is the entry point for every MittensUi application. The block is evaluated inside the GTK activate signal, so all widget creation should happen inside it.

Examples:

MittensUi::Application.Window(name: "contacts", title: "Contacts", width: 570, height: 615) do
  MittensUi::Label.new("Welcome!")
end

Parameters:

  • options (Hash) (defaults to: {}) —

    window configuration options

Options Hash (options):

  • :name (String) — default: "mittens_ui_app" —

    the app identifier, used as the process name and store filename

  • :width (Integer) — default: 400 —

    the window width in pixels

  • :height (Integer) — default: 600 —

    the window height in pixels

  • :title (String) — default: "Mittens App" —

    the window title

  • :can_resize (Boolean) — default: true —

    whether the window is resizable

  • :icon (String) —

    path to a custom window icon file

Yields:

  • (window) —

    the GTK application window

Yield Parameters:

  • window (Gtk::ApplicationWindow) —

    the main window instance



175
176
177
 
# File 'lib/mittens_ui.rb', line 175

def Window(options = {}, &block)
  init_gtk_application(options, &block)
end