# :stopdoc:
# This file is automatically generated by the WXRuby3 documentation 
# generator. Do not alter this file.
# :startdoc:


module Wx

  # This is convenience class that derives from both {Wx::Control} and {Wx::ItemContainer}.
  # It is used as basis for some wxWidgets controls ({Wx::Choice} and {Wx::ListBox}).
  # === 
  # 
  # Category:  {Wx::Controls}
  # @see Wx::ItemContainer
  # @see  Wx::ItemContainerImmutable 
  # 
  # 
  class ControlWithItems < Control
  
    # @overload append(item)
    #   Appends item into the control.
    #   The return value is the index of the newly inserted item. Note that this may be different from the last one if the control is sorted (e.g. has {Wx::LB_SORT} or {Wx::CB_SORT} style).
    #   @param item [String]  String to add.
    #   @return [Integer]
    # @overload append(item, clientData)
    #   Appends item into the control.
    #   The return value is the index of the newly inserted item. Note that this may be different from the last one if the control is sorted (e.g. has {Wx::LB_SORT} or {Wx::CB_SORT} style).
    #   @param item [String]  String to add.
    #   @param clientData [Object]  Pointer to client data to associate with the new item.
    #   @return [Integer]
    # @overload append(items)
    #   Appends several items at once into the control.
    #   Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.
    #   @param items [Array<String>]  Array of strings to insert.
    #   @return [Integer]
    # @overload append(items, clientData)
    #   Appends several items at once into the control.
    #   Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.
    #   @param items [Array<String>]  Array of strings to insert.
    #   @param clientData [Array]  Array of client data pointers of the same size as items to associate with the new items.
    #   @return [Integer]
    def append(*args) end
    
    # Returns a pointer to the client data associated with the given item (if any).
    # It is an error to call this function for a control which doesn't have untyped client data at all although it is OK to call it even if the given item doesn't have any client data associated with it (but other items do).
    # 
    # A pointer to the client data, or NULL if not present.
    # @param n [Integer]  The zero-based position of the item.
    # @return [Object]
    def get_client_data(n) end
    alias_method :client_data, :get_client_data
    
    # Associates the given untyped client data pointer with the given item.
    # Note that it is an error to call this function if any typed client data pointers had been associated with the control items before.
    # @param n [Integer]  The zero-based item index.
    # @param data [Object]  The client data to associate with the item.
    # @return [void]
    def set_client_data(n, data) end
    
    # @overload insert(item, pos)
    #   Inserts item into the control.
    #   The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.
    #   @param item [String]  String to add.
    #   @param pos [Integer]  Position to insert item before, zero based.
    #   @return [Integer]
    # @overload insert(item, pos, clientData)
    #   Inserts item into the control.
    #   The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.
    #   @param item [String]  String to add.
    #   @param pos [Integer]  Position to insert item before, zero based.
    #   @param clientData [Object]  Pointer to client data to associate with the new item.
    #   @return [Integer]
    # @overload insert(items, pos)
    #   Inserts several items at once into the control.
    #   Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.
    #   
    #   The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.
    #   @param items [Array<String>]  Array of strings to insert.
    #   @param pos [Integer]  Position to insert the items before, zero based.
    #   @return [Integer]
    # @overload insert(items, pos, clientData)
    #   Inserts several items at once into the control.
    #   Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.
    #   
    #   The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.
    #   @param items [Array<String>]  Array of strings to insert.
    #   @param pos [Integer]  Position to insert the items before, zero based.
    #   @param clientData [Array]  Array of client data pointers of the same size as items to associate with the new items.
    #   @return [Integer]
    def insert(*args) end
    
    # @overload set(items)
    #   Replaces the current control contents with the given items.
    #   Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.
    #   @param items [Array<String>]  Array of strings to insert.
    #   @return [void]
    # @overload set(items, clientData)
    #   Replaces the current control contents with the given items.
    #   Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.
    #   @param items [Array<String>]  Array of strings to insert.
    #   @param clientData [Array]  Array of client data pointers of the same size as items to associate with the new items.
    #   @return [void]
    def set(*args) end
    
    # Removes all items from the control.
    # {Wx::ControlWithItems#clear} also deletes the client data of the existing items if it is owned by the control.
    # @return [void]
    def clear; end
    
    # Deletes an item from the control.
    # The client data associated with the item will be also deleted if it is owned by the control. Note that it is an error (signalled by an assert failure in debug builds) to remove an item with the index negative or greater or equal than the number of items in the control.
    # If there is a currently selected item below the item being deleted, i.e. if {Wx::ControlWithItems#get_selection} returns a valid index greater than or equal to n, the selection is invalidated when this function is called. However if the selected item appears before the item being deleted, the selection is preserved unchanged.
    # @see Wx::ControlWithItems#clear 
    # @param n [Integer]  The zero-based item index.
    # @return [void]
    def delete(n) end
    
    # Returns true, if either untyped data (<code>void*</code>) or object data ({Wx::ClientData}*) is associated with the items of the control.
    # @return [true,false]
    def has_client_data; end
    alias_method :has_client_data?, :has_client_data
    
    # Returns true, if untyped data (<code>void*</code>) is associated with the items of the control.
    # @return [true,false]
    def has_client_untyped_data; end
    alias_method :has_client_untyped_data?, :has_client_untyped_data
    
    # Returns the number of items in the control.
    # 
    # @see Wx::ControlWithItems#is_empty 
    # @return [Integer]
    def get_count; end
    alias_method :count, :get_count
    
    # Returns true if the control is empty or false if it has some items.
    # 
    # @see Wx::ControlWithItems#get_count 
    # @return [true,false]
    def is_empty; end
    alias_method :empty?, :is_empty
    
    # Returns the label of the item with the given index.
    # The index must be valid, i.e. less than the value returned by {Wx::ControlWithItems#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
    
    # Returns the array of the labels of all items in the control.
    # @return [Array<String>]
    def get_strings; end
    alias_method :strings, :get_strings
    
    # 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 [true,false]  Whether search is case sensitive (default is not).
    # @return [Integer]
    def find_string(string, caseSensitive=false) 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::ControlWithItems#set_string
    # @see  Wx::ControlWithItems#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.
    # @see Wx::ControlWithItems#set_selection
    # @see  Wx::ControlWithItems#get_string_selection 
    # @return [Integer]
    def get_selection; end
    alias_method :selection, :get_selection
    
    # Selects the item with the specified string in the control.
    # This method doesn't cause any command events to be emitted.
    # Notice that this method is case-insensitive, i.e. the string is compared with all the elements of the control case-insensitively and the first matching entry is selected, even if it doesn't have exactly the same case as this string and there is an exact match afterwards.
    # 
    # true if the specified string has been selected, false if it wasn't found in the control.
    # @param string [String]  The string to select.
    # @return [true,false]
    def set_string_selection(string) end
    alias_method :string_selection=, :set_string_selection
    
    # Returns the label of the selected item or an empty string if no item is selected.
    # 
    # @see Wx::ControlWithItems#get_selection 
    # @return [String]
    def get_string_selection; end
    alias_method :string_selection, :get_string_selection
    
    # This is the same as {Wx::ControlWithItems#set_selection} and exists only because it is slightly more natural for controls which support multiple selection.
    # @param n [Integer] 
    # @return [void]
    def select(n) end
    
  end # ControlWithItems
  

end