class TTY::Prompt::List

A class responsible for rendering select list menu Used by {Prompt} to display interactive menu.

@api private

Constants

FILTER_KEYS_MATCHER: Allowed keys for filter, along with backspace and canc.
HELP
PAGE_HELP

Public Class Methods

new(prompt, options = {}) click to toggle source

Create instance of TTY::Prompt::List menu.

@param Hash options

the configuration options

@option options [Symbol] :default

the default active choice, defaults to 1

@option options [Symbol] :color

the color for the selected item, defualts to :green

@option options [Symbol] :marker

the marker for the selected item

@option options [String] :enum

the delimiter for the item index

@api public

# File lib/tty/prompt/list.rb, line 38
def initialize(prompt, options = {})
  check_options_consistency(options)

  @prompt       = prompt
  @prefix       = options.fetch(:prefix) { @prompt.prefix }
  @enum         = options.fetch(:enum) { nil }
  @default      = Array[options.fetch(:default) { 1 }]
  @active       = @default.first
  @choices      = Choices.new
  @active_color = options.fetch(:active_color) { @prompt.active_color }
  @help_color   = options.fetch(:help_color) { @prompt.help_color }
  @marker       = options.fetch(:marker) { symbols[:pointer] }
  @cycle        = options.fetch(:cycle) { false }
  @filter       = options.fetch(:filter) { false } ? "" : nil
  @help         = options[:help]
  @first_render = true
  @done         = false
  @per_page     = options[:per_page]
  @page_help    = options[:page_help] || PAGE_HELP
  @paginator    = Paginator.new

  @prompt.subscribe(self)
end

Public Instance Methods

call(question, possibilities, &block) click to toggle source

Call the list menu by passing question and choices

@param [String] question

@param @api public

# File lib/tty/prompt/list.rb, line 178
def call(question, possibilities, &block)
  choices(possibilities)
  @question = question
  block.call(self) if block
  setup_defaults
  render
end

choice(*value, &block) click to toggle source

Add a single choice

@api public

# File lib/tty/prompt/list.rb, line 143
def choice(*value, &block)
  if block
    @choices << (value << block)
  else
    @choices << value
  end
end

choices(values = (not_set = true)) click to toggle source

Add multiple choices, or return them.

@param [Array] values

the values to add as choices; if not passed, the current
choices are displayed.

@api public

# File lib/tty/prompt/list.rb, line 158
def choices(values = (not_set = true))
  if not_set
    if @filter.to_s.empty?
      @choices
    else
      @choices.select do |_choice|
        _choice.name.downcase.include?(@filter.downcase)
      end
    end
  else
    Array(values).each { |val| choice(*val) }
  end
end

default(*default_values) click to toggle source

Set default option selected

@api public

# File lib/tty/prompt/list.rb, line 72
def default(*default_values)
  @default = default_values
end

default_help() click to toggle source

Default help text

@api public

# File lib/tty/prompt/list.rb, line 120
def default_help
  # Note that enumeration and filter are mutually exclusive
  tokens = if enumerate?
             [" or number (1-#{choices.size})", ""]
           elsif @filter
             ["", ", and letter keys to filter"]
           else
             ["", ""]
           end

  format(self.class::HELP, *tokens)
end

enum(value) click to toggle source

Set selecting active index using number pad

@api public

# File lib/tty/prompt/list.rb, line 136
def enum(value)
  @enum = value
end

enumerate?() click to toggle source

Check if list is enumerated

@return [Boolean]

# File lib/tty/prompt/list.rb, line 189
def enumerate?
  !@enum.nil?
end

help(value = (not_set = true)) click to toggle source

Provide help information

@param [String] value

the new help text

@return [String]

@api public

# File lib/tty/prompt/list.rb, line 111
def help(value = (not_set = true))
  return @help if !@help.nil? && not_set

  @help = (@help.nil? && !not_set) ? value : default_help
end

keybackspace(*) click to toggle source

# File lib/tty/prompt/list.rb, line 239
def keybackspace(*)
  return unless @filter

  @filter.slice!(-1)
  @active = 1
end

keydelete(*) click to toggle source

# File lib/tty/prompt/list.rb, line 232
def keydelete(*)
  return unless @filter

  @filter = ""
  @active = 1
end

keydown(*) click to toggle source

# File lib/tty/prompt/list.rb, line 214
def keydown(*)
  if @active == choices.length
    @active = 1 if @cycle
  else
    @active += 1
  end
end

Also aliased as: keytab

keyenter(*) click to toggle source

# File lib/tty/prompt/list.rb, line 200
def keyenter(*)
  @done = true unless choices.empty?
end

Also aliased as: keyreturn, keyspace

keynum(event) click to toggle source

# File lib/tty/prompt/list.rb, line 193
def keynum(event)
  return unless enumerate?
  value = event.value.to_i
  return unless (1..choices.count).cover?(value)
  @active = value
end

keypress(event) click to toggle source

# File lib/tty/prompt/list.rb, line 223
def keypress(event)
  return unless @filter

  if event.value =~ FILTER_KEYS_MATCHER
    @filter += event.value
    @active = 1
  end
end

keyreturn(*)

Alias for: keyenter

keyspace(*)

Alias for: keyenter

keytab(*)

Alias for: keydown

keyup(*) click to toggle source

# File lib/tty/prompt/list.rb, line 206
def keyup(*)
  if @active == 1
    @active = choices.length if @cycle
  else
    @active -= 1
  end
end

marker(value) click to toggle source

Set marker

@api public

# File lib/tty/prompt/list.rb, line 65
def marker(value)
  @marker = value
end

page_help(text) click to toggle source

@param [String] text

the help text to display per page

@api pbulic

# File lib/tty/prompt/list.rb, line 99
def page_help(text)
  @page_help = text
end

page_size() click to toggle source

# File lib/tty/prompt/list.rb, line 83
def page_size
  (@per_page || Paginator::DEFAULT_PAGE_SIZE)
end

paginated?() click to toggle source

Check if list is paginated

@return [Boolean]

@api private

# File lib/tty/prompt/list.rb, line 92
def paginated?
  choices.size > page_size
end

per_page(value) click to toggle source

Set number of items per page

@api public

# File lib/tty/prompt/list.rb, line 79
def per_page(value)
  @per_page = value
end