Class: MittensUi::Loader

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

Overview

A loading spinner widget that displays an animated indicator during asynchronous operations. Wraps Gtk::Spinner and manages a background worker thread to prevent blocking the UI during long-running tasks.

The spinner is hidden by default and automatically shown/hidden based on processing state. Only one worker thread can run at a time; subsequent calls to #start while a thread is already running are safely ignored.

Examples:

Basic usage

loader = MittensUi::Loader.new
loader.start do
  sleep 2  # Simulate long-running work
  puts "Work complete!"
end

With custom width

loader = MittensUi::Loader.new(width: :half)
loader.start { perform_database_query }

Instance Attribute Summary

Attributes inherited from Core

#core_widget

Instance Method Summary collapse

Methods inherited from Core

#hidden?, #hide, #keyboard_shortcut, #remove, #remove_keyboard_shortcut, #render, #shortcuts, #show

Methods included from Helpers

#icon_map, #list_system_icons, #set_margin_from_opts_for

Constructor Details

#initialize(options = {}) ⇒ Loader

Creates a new Loader widget with a spinner animation.

The spinner is initialized in a hidden state. Call #start to begin displaying the animation and executing a background task.

Parameters:

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

    configuration options

Options Hash (options):

  • :width (Symbol) — default: :full —

    column width in the layout grid. Accepted values are :full, :half, :third, :quarter

  • :defer_render (Boolean) — default: false —

    when true, skips auto-rendering into the layout. Use when passing to a container like HBox.



37
38
39
40
41
42
 
# File 'lib/mittens_ui/loader.rb', line 37

def initialize(options = {})
  @spinner = Gtk::Spinner.new
  @processing = false
  super(@spinner, options)
  @spinner.visible = false
end

Instance Method Details

#start(&block) ⇒ void

This method returns an undefined value.

Starts the spinner animation and executes a block in a background worker thread.

The spinner is displayed while the block executes, then automatically hidden when the block completes. If a worker thread is already running, this method safely returns without starting a new thread.

Examples:

Simple background task

loader = MittensUi::Loader.new
loader.start do
  result = expensive_calculation
  puts "Done: #{result}"
end

With error handling

loader.start do
  begin
    data = fetch_from_api
  rescue StandardError => e
    puts "Error: #{e.message}"
  end
end

Parameters:

  • block (Proc) —

    the work to execute in the background. Exceptions raised in the block will terminate the thread; consider wrapping critical code in rescue blocks if needed.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/mittens_ui/loader.rb', line 70

def start(&block)
  return if @processing

  return if @worker_thread&.alive?

  @processing = true
  @spinner.visible = true
  @spinner.start
  @worker_thread = Thread.new do
    block.call
    @processing = false
    @spinner.stop
    @spinner.visible = false
  end
end