Class: MittensUi::Listbox

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

Overview

A dropdown list widget with optional search/filter functionality. Wraps Gtk::DropDown backed by Gtk::StringList. In searchable mode, a search entry is displayed above the dropdown and filters the list as the user types.

Examples:

Basic listbox

lb = MittensUi::Listbox.new(items: ['Ruby', 'Python', 'Elixir'])
puts lb.selected_value

Searchable listbox

lb = MittensUi::Listbox.new(items: ['Ruby', 'Python', 'Elixir'], searchable: true)
puts lb.selected_value

Instance Attribute Summary collapse

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 = {}) ⇒ Listbox

Creates a new Listbox widget.

Parameters:

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

    configuration options

Options Hash (options):

  • :items (Array<String>) — default: [] —

    the list of items to display

  • :searchable (Boolean) — default: false —

    when true, a search entry is shown above the dropdown that filters items as the user types

  • :search_placeholder_text (String) — default: "Search..." —

    placeholder text shown in the search entry

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

    column width in the layout grid

  • :defer_render (Boolean) — default: false —

    skip auto-rendering into layout



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/mittens_ui/listbox.rb', line 35

def initialize(options = {})
  @items                   = options[:items]                    || []
  @searchable              = options[:searchable]               || false
  @search_placeholder_text = options[:search_placeholder_text] || 'Search...'
  @selected_value          = nil
  @search_term             = ''
  @filtered_items          = @items.dup

  init_store
  init_dropdown

  if @searchable
    init_search_entry
    @gtk_widget = build_container
  else
    @gtk_widget = @dropdown
  end

  super(@gtk_widget, options)
end

Instance Attribute Details

#items ⇒ Array<String> (readonly)

The original unfiltered list of items.

Returns:

  • (Array<String>) 


23
24
25
 
# File 'lib/mittens_ui/listbox.rb', line 23

def items
  @items
end

Instance Method Details

#clear_search ⇒ void

This method returns an undefined value.

Resets the search filter and restores the full item list. Only has effect when :searchable is true.



83
84
85
86
87
88
89
 
# File 'lib/mittens_ui/listbox.rb', line 83

def clear_search
  return unless @searchable

  @search_entry.text = ''
  @search_term = ''
  rebuild_store(@items)
end

#selected_value ⇒ String?

Returns the currently selected value.

Examples:

lb.selected_value  # => "Ruby"

Returns:

  • (String, nil) —

    the selected item or nil if nothing is selected



61
62
63
64
65
66
 
# File 'lib/mittens_ui/listbox.rb', line 61

def selected_value
  pos = @dropdown.selected
  return nil if pos == Gtk::INVALID_LIST_POSITION

  @filtered_items[pos]
end

#set_selected_value(value) ⇒ String? Also known as: set_value

Sets the selected value manually.

Parameters:

  • value (String) —

    the value to select

Returns:

  • (String, nil) —

    the value that was set, or nil if not found



72
73
74
75
76
 
# File 'lib/mittens_ui/listbox.rb', line 72

def set_selected_value(value)
  idx = @filtered_items.index(value)
  @dropdown.selected = idx if idx
  value
end

#update_items(new_items) ⇒ void

This method returns an undefined value.

Replaces the current items with a new list and resets the selection.

Examples:

lb.update_items(['Go', 'Rust', 'Zig'])

Parameters:

  • new_items (Array<String>) —

    the new list of items



97
98
99
100
 
# File 'lib/mittens_ui/listbox.rb', line 97

def update_items(new_items)
  @items = new_items
  rebuild_store(@items)
end