# :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 
  # 
  # 
  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, 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]
    def initialize(*args) end
    
    # Deselects an item in the list box.
    # This applies to multiple selection listboxes only.
    # @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.
    # 
    # 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.
    # @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.
    # 
    # Use this with a multiple selection listbox.
    # @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, wxMac 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
    
    # MSW-specific function for setting custom tab stop distances.
    # Tab stops are expressed in dialog unit widths, i.e. "quarters of the
    # average character width for the font that is selected into the list
    # box".
    # 
    # true if all specified tabs are set, false otherwise
    # 
    # Availability:  only available for the wxMSW port.  {Wx::msw}
    # @param tabStops [Wx::Vector< int >]  If this argument is empty, tab stops are reset to their default value (every 32 dialog units). If it contains a single element, tab stops are set at each multiple of the given value. Otherwise tab stops are set at every element of the array, which must be in ascending order.
    # @return [Boolean]
    def msw_set_tab_stops(tabStops) end
    
    # 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