wxruby3 1.6.1 → 1.7.0

data/lib/wx/doc/gen/list_box.rb

@@ -0,0 +1,304 @@
+# :stopdoc:
+# This file is automatically generated by the WXRuby3 documentation 
+# generator. Do not alter this file.
+# :startdoc:
+
+
+module Wx
+
+  # A listbox is used to select one or more of a list of strings.
+  # 
+  # The strings are displayed in a scrolling box, with the selected string(s) marked in reverse video. A listbox can be single selection (if an item is selected, the previous selection is removed) or multiple selection (clicking an item toggles the item on or off independently of other selections).
+  # List box elements are numbered from zero and while the maximal number of elements is unlimited, it is usually better to use a virtual control, not requiring to add all the items to it at once, such as {Wx::DataViewCtrl} or {Wx::ListCtrl} with {Wx::LC_VIRTUAL} style, once more than a few hundreds items need to be displayed because this control is not optimized, neither from performance nor from user interface point of view, for large number of items.
+  # Notice that the list box doesn't support control characters other than TAB.
+  # ### Styles
+  # 
+  # This class supports the following styles:
+  # 
+  # - {Wx::LB_SINGLE}: Single-selection list. 
+  # 
+  # - {Wx::LB_MULTIPLE}: Multiple-selection list: the user can toggle multiple items on and off. This is the same as {Wx::LB_EXTENDED} in WXGTK2 port. 
+  # 
+  # - {Wx::LB_EXTENDED}: Extended-selection list: the user can extend the selection by using SHIFT or CTRL keys together with the cursor movement keys or the mouse. 
+  # 
+  # - {Wx::LB_HSCROLL}: Create horizontal scrollbar if contents are too wide (Windows only). 
+  # 
+  # - {Wx::LB_ALWAYS_SB}: Always show a vertical scrollbar. 
+  # 
+  # - {Wx::LB_NEEDED_SB}: Only create a vertical scrollbar if needed. 
+  # 
+  # - {Wx::LB_NO_SB}: Don't create vertical scrollbar (WXMSW and WXGTK only). 
+  # 
+  # - {Wx::LB_SORT}: The listbox contents are sorted in alphabetical order. 
+  # 
+  # Note that {Wx::LB_SINGLE}, {Wx::LB_MULTIPLE} and {Wx::LB_EXTENDED} styles are mutually exclusive and you can specify at most one of them (single selection is the default). See also Window Styles.
+  # ### Events emitted by this class
+  # 
+  # The following event-handler methods redirect the events to member method or handler blocks for {Wx::CommandEvent} events.
+  # Event handler methods for events emitted by this class:
+  # 
+  # - {Wx::EvtHandler#evt_listbox}(id, meth = nil, &block): Process a {Wx::EVT_LISTBOX} event, when an item on the list is selected or the selection changes. 
+  # 
+  # - {Wx::EvtHandler#evt_listbox_dclick}(id, meth = nil, &block): Process a {Wx::EVT_LISTBOX_DCLICK} event, when the listbox is double-clicked. On some platforms (notably WXGTK2) pressing the enter key is handled as an equivalent of a double-click. 
+  # 
+  # Category:  {Wx::Controls}  <div class='appearance'><span class='appearance'>Appearance:</span><table><tr><td> WXMSW Appearance
+  #   </td><td> WXGTK Appearance
+  #   </td><td> WXOSX Appearance
+  #   </td></tr></table></div>
+  # @see Wx::EditableListBox
+  # @see  Wx::Choice
+  # @see  Wx::ComboBox
+  # @see  Wx::ListCtrl
+  # @see  Wx::CommandEvent 
+  # 
+  # 
+  # @wxrb_require USE_LISTBOX
+  class ListBox < ControlWithItems
+  
+    # @overload create(parent, id, pos=Wx::DEFAULT_POSITION, size=Wx::DEFAULT_SIZE, choices=nil, style=0, validator=Wx::DEFAULT_VALIDATOR, name=Wx::LIST_BOX_NAME_STR)
+    #   Creates the listbox for two-step construction.
+    #   
+    #   See {Wx::ListBox#initialize} for further details.
+    #   @param parent [Wx::Window] 
+    #   @param id [Integer] 
+    #   @param pos [Array(Integer, Integer), Wx::Point] 
+    #   @param size [Array(Integer, Integer), Wx::Size] 
+    #   @param choices [Array<String>] 
+    #   @param style [Integer] 
+    #   @param validator [Wx::Validator] 
+    #   @param name [String] 
+    #   @return [Boolean]
+    # @overload create(parent, id, pos, size, choices, style=0, validator=Wx::DEFAULT_VALIDATOR, name=Wx::LIST_BOX_NAME_STR)
+    #   Creates the listbox for two-step construction.
+    #   
+    #   See {Wx::ListBox#initialize} for further details.
+    #   @param parent [Wx::Window] 
+    #   @param id [Integer] 
+    #   @param pos [Array(Integer, Integer), Wx::Point] 
+    #   @param size [Array(Integer, Integer), Wx::Size] 
+    #   @param choices [Array<String>] 
+    #   @param style [Integer] 
+    #   @param validator [Wx::Validator] 
+    #   @param name [String] 
+    #   @return [Boolean]
+    def create(*args) end
+    
+    # @overload initialize()
+    #   Default constructor.
+    #   @return [Wx::ListBox]
+    # @overload initialize(parent, id, pos=Wx::DEFAULT_POSITION, size=Wx::DEFAULT_SIZE, choices=nil, style=0, validator=Wx::DEFAULT_VALIDATOR, name=Wx::LIST_BOX_NAME_STR)
+    #   Constructor, creating and showing a list box.
+    #   @param parent [Wx::Window]  The parent window.
+    #   @param id [Integer]  The ID of this control. A value of {Wx::StandardID::ID_ANY} indicates a default value.
+    #   @param pos [Array(Integer, Integer), Wx::Point]  The initial position. If {Wx::DEFAULT_POSITION} is specified then a default position is chosen.
+    #   @param size [Array(Integer, Integer), Wx::Size]  The initial size. If {Wx::DEFAULT_SIZE} is specified then the window is sized appropriately.
+    #   @param choices [Array<String>]  The strings to use to initialize the control.
+    #   @param style [Integer]  Window style. See {Wx::ListBox}.
+    #   @param validator [Wx::Validator]  The validator for this control.
+    #   @param name [String]  The name of this class.
+    #   @return [Wx::ListBox]
+    # @overload initialize(parent, id, pos=Wx::DEFAULT_POSITION, size=Wx::DEFAULT_SIZE, choices=nil, style=0, validator=Wx::DEFAULT_VALIDATOR, name=Wx::LIST_BOX_NAME_STR, &block)
+    #   Constructor, creating and showing a list box.
+    #   @param parent [Wx::Window]  The parent window.
+    #   @param id [Integer]  The ID of this control. A value of {Wx::StandardID::ID_ANY} indicates a default value.
+    #   @param pos [Array(Integer, Integer), Wx::Point]  The initial position. If {Wx::DEFAULT_POSITION} is specified then a default position is chosen.
+    #   @param size [Array(Integer, Integer), Wx::Size]  The initial size. If {Wx::DEFAULT_SIZE} is specified then the window is sized appropriately.
+    #   @param choices [Array<String>]  The strings to use to initialize the control.
+    #   @param style [Integer]  Window style. See {Wx::ListBox}.
+    #   @param validator [Wx::Validator]  The validator for this control.
+    #   @param name [String]  The name of this class.
+    #   @yieldparam [Wx::ListBox] win new instance
+    #   @return [Wx::ListBox]
+    # @overload initialize(parent, id, pos, size, choices, style=0, validator=Wx::DEFAULT_VALIDATOR, name=Wx::LIST_BOX_NAME_STR)
+    #   Constructor, creating and showing a list box.
+    #   
+    #   See the other {Wx::ListBox#initialize} constructor; the only difference is that this overload takes a {Wx::ArrayString} instead of a pointer to an array of {Wx::String}.
+    #   @param parent [Wx::Window] 
+    #   @param id [Integer] 
+    #   @param pos [Array(Integer, Integer), Wx::Point] 
+    #   @param size [Array(Integer, Integer), Wx::Size] 
+    #   @param choices [Array<String>] 
+    #   @param style [Integer] 
+    #   @param validator [Wx::Validator] 
+    #   @param name [String] 
+    #   @return [Wx::ListBox]
+    # @overload initialize(parent, id, pos, size, choices, style=0, validator=Wx::DEFAULT_VALIDATOR, name=Wx::LIST_BOX_NAME_STR, &block)
+    #   Constructor, creating and showing a list box.
+    #   
+    #   See the other {Wx::ListBox#initialize} constructor; the only difference is that this overload takes a {Wx::ArrayString} instead of a pointer to an array of {Wx::String}.
+    #   @param parent [Wx::Window] 
+    #   @param id [Integer] 
+    #   @param pos [Array(Integer, Integer), Wx::Point] 
+    #   @param size [Array(Integer, Integer), Wx::Size] 
+    #   @param choices [Array<String>] 
+    #   @param style [Integer] 
+    #   @param validator [Wx::Validator] 
+    #   @param name [String] 
+    #   @yieldparam [Wx::ListBox] win new instance
+    #   @return [Wx::ListBox]
+    def initialize(*args) end
+    
+    # return true if the listbox allows multiple selection
+    # @return [Boolean]
+    def has_multiple_selection; end
+    alias_method :has_multiple_selection?, :has_multiple_selection
+    
+    # Deselects an item in the list box.
+    # 
+    # <div class="wxrb-remark">
+    # <b>Remark:</b>
+    # <p>This applies to multiple selection listboxes only. 
+    # </p>
+    # </div>
+    # @param n [Integer]  The zero-based item to deselect.
+    # @return [void]
+    def deselect(n) end
+    
+    # Sets the selection to the given item n or removes the selection entirely if n == {Wx::NOT_FOUND}.
+    # 
+    # Note that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections.
+    # @see Wx::ListBox#set_string
+    # @see  Wx::ListBox#set_string_selection 
+    # @param n [Integer]  The string position to select, starting from zero.
+    # @return [void]
+    def set_selection(n) end
+    alias_method :selection=, :set_selection
+    
+    # Returns the index of the selected item or {Wx::NOT_FOUND} if no item is selected.
+    # 
+    # The position of the current selection.
+    # 
+    # <div class="wxrb-remark">
+    # <b>Remark:</b>
+    # <p>This method can be used with single selection list boxes only, you must use {Wx::ListBox#get_selections} for the list boxes with {Wx::LB_MULTIPLE} style.
+    # </p>
+    # </div>
+    # @see Wx::ListBox#set_selection
+    # @see  Wx::ListBox#get_string_selection 
+    # @return [Integer]
+    def get_selection; end
+    alias_method :selection, :get_selection
+    
+    # @overload set_string_selection(s, select)
+    #   @param s [String] 
+    #   @param select [Boolean] 
+    #   @return [Boolean]
+    # @overload set_string_selection(s)
+    #   @param s [String] 
+    #   @return [Boolean]
+    def set_string_selection(*args) end
+    alias_method :string_selection=, :set_string_selection
+    
+    # Fill an array of ints with the positions of the currently selected items.
+    # 
+    # The number of selections.
+    # 
+    # <div class="wxrb-remark">
+    # <b>Remark:</b>
+    # <p>Use this with a multiple selection listbox.
+    # </p>
+    # </div>
+    # @see Wx::ControlWithItems::GetSelection
+    # @see  Wx::ControlWithItems::GetStringSelection
+    # @see  Wx::ControlWithItems::SetSelection 
+    # @return [Array<Integer>]
+    def get_selections; end
+    alias_method :selections, :get_selections
+    
+    # @overload hit_test(point)
+    #   Returns the item located at point, or {Wx::NOT_FOUND} if there is no item located at point.
+    #   
+    #   It is currently implemented for WXMSW, WXOSX and WXGTK2 ports.
+    #   
+    #   Item located at point, or {Wx::NOT_FOUND} if unimplemented or the item does not exist.
+    #   @param point [Array(Integer, Integer), Wx::Point]  Point of item (in client coordinates) to obtain
+    #   @return [Integer]
+    # @overload hit_test(x, y)
+    #   This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
+    #   @param x [Integer] 
+    #   @param y [Integer] 
+    #   @return [Integer]
+    def hit_test(*args) end
+    
+    # Insert the given number of strings before the specified position.
+    # @param items [Array<String>]  Labels of items to be inserted
+    # @param pos [Integer]  Position before which to insert the items: if pos is 0 the items will be inserted in the beginning of the listbox
+    # @return [void]
+    def insert_items(items, pos) end
+    
+    # Determines whether an item is selected.
+    # 
+    # true if the given item is selected, false otherwise.
+    # @param n [Integer]  The zero-based item index.
+    # @return [Boolean]
+    def is_selected(n) end
+    alias_method :selected?, :is_selected
+    
+    # @overload set_first_item(n)
+    #   Set the specified item to be the first visible item.
+    #   @param n [Integer]  The zero-based item index that should be visible.
+    #   @return [void]
+    # @overload set_first_item(string)
+    #   Set the specified item to be the first visible item.
+    #   @param string [String]  The string that should be visible.
+    #   @return [void]
+    def set_first_item(*args) end
+    alias_method :first_item=, :set_first_item
+    
+    # Ensure that the item with the given index is currently shown.
+    # 
+    # This method scrolls the listbox only if necessary and doesn't do anything if this item is already shown, unlike {Wx::ListBox#set_first_item}.
+    # @param n [Integer] 
+    # @return [void]
+    def ensure_visible(n) end
+    
+    # Return the number of items that can fit vertically in the visible area of the listbox.
+    # 
+    # Returns -1 if the number of items per page couldn't be determined. On WXGTK this method can only determine the number of items per page if there is at least one item in the listbox.
+    # @return [Integer]
+    def get_count_per_page; end
+    alias_method :count_per_page, :get_count_per_page
+    
+    # Return the index of the topmost visible item.
+    # 
+    # Returns {Wx::NOT_FOUND} if the method is not implemented for the current platform.
+    # @return [Integer]
+    def get_top_item; end
+    alias_method :top_item, :get_top_item
+    
+    # Returns the number of items in the control.
+    # 
+    # 
+    # @see Wx::ListBox#is_empty 
+    # @return [Integer]
+    def get_count; end
+    alias_method :count, :get_count
+    
+    # Returns the label of the item with the given index.
+    # 
+    # The index must be valid, i.e. less than the value returned by {Wx::ListBox#get_count}, otherwise an assert is triggered. Notably, this function can't be called if the control is empty.
+    # 
+    # The label of the item.
+    # @param n [Integer]  The zero-based index.
+    # @return [String]
+    def get_string(n) end
+    alias_method :string, :get_string
+    
+    # Sets the label for the given item.
+    # @param n [Integer]  The zero-based item index.
+    # @param string [String]  The label to set.
+    # @return [void]
+    def set_string(n, string) end
+    
+    # Finds an item whose label matches the given string.
+    # 
+    # The zero-based position of the item, or {Wx::NOT_FOUND} if the string was not found.
+    # @param string [String]  String to find.
+    # @param caseSensitive [Boolean]  Whether search is case sensitive (default is not).
+    # @return [Integer]
+    def find_string(string, caseSensitive=false) end
+    
+  end # ListBox
+  
+
+end