Class: RubyCurses::Bottomline::Menu

Inherits:
Question show all
Defined in:
lib/rbcurse/core/util/bottomline.rb

Overview

Menu objects encapsulate all the details of a call to HighLine.choose(). Using the accessors and Menu.choice() and Menu.choices(), the block passed to HighLine.choose() can detail all aspects of menu display and control.

Instance Attribute Summary collapse

Attributes inherited from Question

#_case, #above, #answer_type, #below, #change_proc, #character, #color_pair, #completion_proc, #confirm, #default, #directory, #echo, #first_answer, #gather, #glob, #help_text, #history, #in, #key_handler_proc, #limit, #overwrite, #question, #readline, #responses, #validate, #whitespace

Instance Method Summary collapse

Methods inherited from Question

#answer_or_default, #build_responses, #change_case, #convert, #expected_range, #first_answer?, #in_range?, #remove_whitespace, #selection, #valid_answer?

Constructor Details

#initialize {|_self| ... } ⇒ Menu

Create an instance of HighLine::Menu. All customization is done through the passed block, which should call accessors and choice() and choices() as needed to define the Menu. Note that Menus are also Questions, so all that functionality is available to the block as well.

Yields:

  • (_self)

Yield Parameters:



601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 601

def initialize(  )
  #
  # Initialize Question objects with ignored values, we'll
  # adjust ours as needed.
  # 
  super("Ignored", [ ], &nil)    # avoiding passing the block along

  @items           = [ ]
  @hidden_items    = [ ]
  @help            = Hash.new("There's no help for that topic.")

  @index           = :number
  @index_suffix    = ". "
  @select_by       = :index_or_name
  @flow            = :rows
  @list_option     = nil
  @header          = nil
  @prompt          = "?  "
  @layout          = :list
  @shell           = false
  @nil_on_handled  = false

  # Override Questions responses, we'll set our own.
  @responses       = { }
  # Context for action code.
  @highline        = nil

  yield self if block_given?

  init_help if @shell and not @help.empty?
end

Instance Attribute Details

#flow ⇒ Object

This attribute is passed directly on as the mode to HighLine.list() by all the preset layouts. See that method for appropriate settings.



661
662
663
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 661

def flow
  @flow
end

#header ⇒ Object

Used by all the preset layouts to display title and/or introductory information, when set. Defaults to nil.



672
673
674
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 672

def header
  @header
end

#index ⇒ Object

An index to append to each menu item in display. See Menu.index=() for details.



637
638
639
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 637

def index
  @index
end

#index_suffix ⇒ Object

The String placed between an index and a menu item. Defaults to “. ”. Switches to “ ”, when index is set to a String (like “-”).



642
643
644
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 642

def index_suffix
  @index_suffix
end

#layout ⇒ Object

An ERb layout to use when displaying this Menu object. See Menu.layout=() for details.



682
683
684
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 682

def layout
  @layout
end

#list_option ⇒ Object

This setting is passed on as the third parameter to HighLine.list() by all the preset layouts. See that method for details of its effects. Defaults to nil.



667
668
669
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 667

def list_option
  @list_option
end

#nil_on_handled ⇒ Object

When true, any selected item handled by provided action code, will return nil, instead of the results to the action code. This may prove handy when dealing with mixed menus where only the names of items without any code (and nil, of course) will be returned. Defaults to false.



698
699
700
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 698

def nil_on_handled
  @nil_on_handled
end

#prompt ⇒ Object

Used by all the preset layouts to ask the actual question to fetch a menu selection from the user. Defaults to “? ”.



677
678
679
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 677

def prompt
  @prompt
end

#select_by ⇒ Object

The select_by attribute controls how the user is allowed to pick a menu item. The available choices are:

:index

The user is allowed to type the numerical or alphetical index for their selection.

:index_or_name

Allows both methods from the :index option and the :name option.

:name

Menu items are selected by typing a portion of the item name that will be auto-completed.



656
657
658
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 656

def select_by
  @select_by
end

#shell ⇒ Object

When set to true, responses are allowed to be an entire line of input, including details beyond the command itself. Only the first “word” of input will be matched against the menu choices, but both the command selected and the rest of the line will be passed to provided action blocks. Defaults to false.



690
691
692
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 690

def shell
  @shell
end

Instance Method Details

#choice(name, help = nil, &action) ⇒ Object

Adds name to the list of available menu items. Menu items will be displayed in the order they are added.

An optional action can be associated with this name and if provided, it will be called if the item is selected. The result of the method will be returned, unless nil_on_handled is set (when you would get nil instead). In shell mode, a provided block will be passed the command chosen and any details that followed the command. Otherwise, just the command is passed. The @highline variable is set to the current HighLine context before the action code is called and can thus be used for adding output and the like.



713
714
715
716
717
718
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 713

def choice( name, help = nil, &action )
  @items << [name, action]

  @help[name.to_s.downcase] = help unless help.nil?
  update_responses  # rebuild responses based on our settings
end

#choices(*names, &action) ⇒ Object

A shortcut for multiple calls to the sister method choice(). Be warned: An action set here will apply to all provided names. This is considered to be a feature, so you can easily hand-off interface processing to a different chunk of code.



726
727
728
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 726

def choices( *names, &action )
  names.each { |n| choice(n, &action) }
end

#help(topic, help) ⇒ Object

Used to set help for arbitrary topics. Use the topic "help" to override the default message.



791
792
793
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 791

def help( topic, help )
  @help[topic] = help
end

#hidden(name, help = nil, &action) ⇒ Object

Identical to choice(), but the item will not be listed for the user.



731
732
733
734
735
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 731

def hidden( name, help = nil, &action )
  @hidden_items << [name, action]

  @help[name.to_s.downcase] = help unless help.nil?
end

#init_help ⇒ Object

Initializes the help system by adding a :help choice, some action code, and the default help listing.



766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 766

def init_help(  )
  return if @items.include?(:help)

  topics    = @help.keys.sort
  help_help = @help.include?("help") ? @help["help"] :
    "This command will display helpful messages about " +
    "functionality, like this one.  To see the help for " +
    "a specific topic enter:\n\thelp [TOPIC]\nTry asking " +
    "for help on any of the following:\n\n" +
    "<%= list(#{topics.inspect}, :columns_across) %>"
  choice(:help, help_help) do |command, topic|
    topic.strip!
    topic.downcase!
    if topic.empty?
      @highline.say(@help["help"])
    else
      @highline.say("= #{topic}\n\n#{@help[topic]}")
    end
  end
end

#options ⇒ Object

This method returns all possible options for auto-completion, based on the settings of index and select_by.



840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 840

def options(  )
  # add in any hidden menu commands
  @items.concat(@hidden_items)

  by_index = if @index == :letter
               l_index = "`"
               @items.map { "#{l_index.succ!}" }
             else
               (1 .. @items.size).collect { |s| String(s) }
             end
  by_name = @items.collect { |c| c.first }

  case @select_by
  when :index then
    by_index
  when :name
    by_name
  else
    by_index + by_name
  end
ensure
  # make sure the hidden items are removed, before we return
  @items.slice!(@items.size - @hidden_items.size, @hidden_items.size)
end

#select(highline_context, selection, details = nil) ⇒ Object

This method processes the auto-completed user selection, based on the rules for this Menu object. If an action was provided for the selection, it will be executed as described in Menu.choice().



870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 870

def select( highline_context, selection, details = nil )
  # add in any hidden menu commands
  @items.concat(@hidden_items)

  # Find the selected action.
  name, action = if selection =~ /^\d+$/
                   @items[selection.to_i - 1]
                 else
                   l_index = "`"
                   index = @items.map { "#{l_index.succ!}" }.index(selection)
                   $log.debug "iindex #{index},  #{@items} " if $log.debug? 
                   @items.find { |c| c.first == selection } or @items[index]
                 end

  # Run or return it.
  if not @nil_on_handled and not action.nil?
    @highline = highline_context
    if @shell
      action.call(name, details)
    else
      action.call(name)
    end
  elsif action.nil?
    name
  else
    nil
  end
ensure
  # make sure the hidden items are removed, before we return
  @items.slice!(@items.size - @hidden_items.size, @hidden_items.size)
end

#to_ary ⇒ Object

Allows Menu objects to pass as Arrays, for use with HighLine.list(). This method returns all menu items to be displayed, complete with indexes.



907
908
909
910
911
912
913
914
915
916
917
918
919
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 907

def to_ary(  )
  case @index
  when :number
    @items.map { |c| "#{@items.index(c) + 1}#{@index_suffix}#{c.first}" }
  when :letter
    l_index = "`"
    @items.map { |c| "#{l_index.succ!}#{@index_suffix}#{c.first}" }
  when :none
    @items.map { |c| "#{c.first}" }
  else
    @items.map { |c| "#{index}#{@index_suffix}#{c.first}" }
  end
end

#to_str ⇒ Object

Allows Menu to behave as a String, just like Question. Returns the layout to be rendered, which is used by HighLine.say().



925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 925

def to_str(  )
  case @layout
  when :list
    '<%= if @header.nil? then '' else "#{@header}:\n" end %>' +
      "<%= list( @menu, #{@flow.inspect},
                    #{@list_option.inspect} ) %>" +
      "<%= @prompt %>"
  when :one_line
    '<%= if @header.nil? then '' else "#{@header}:  " end %>' +
      "<%= @prompt %>" +
      "(<%= list( @menu, #{@flow.inspect},
                     #{@list_option.inspect} ) %>)" +
      "<%= @prompt[/\s*$/] %>"
  when :menu_only
    "<%= list( @menu, #{@flow.inspect},
                    #{@list_option.inspect} ) %><%= @prompt %>"
  else
    @layout
  end
end

#update_responses ⇒ Object

This method will update the intelligent responses to account for Menu specific differences. This overrides the work done by Question.build_responses().



951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
 
# File 'lib/rbcurse/core/util/bottomline.rb', line 951

def update_responses(  )
  append_default unless default.nil?
  @responses = @responses.merge(
                                :ambiguous_completion =>
                                "Ambiguous choice.  " +
                                  "Please choose one of #{options.inspect}.",
                                  :ask_on_error         =>
                                "?  ",
                                  :invalid_type         =>
                                "You must enter a valid #{options}.",
                                  :no_completion        =>
                                "You must choose one of " +
                                  "#{options.inspect}.",
                                  :not_in_range         =>
                                "Your answer isn't within the expected range " +
                                  "(#{expected_range}).",
                                  :not_valid            =>
                                  "Your answer isn't valid (must match " +
                                    "#{@validate.inspect})."
                               )
end