<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<!-- THIS FILE IS GENERATED DO NOT EDIT -->


<erlref>
<header>
  <copyright>
    <year>2020</year><year>2021</year>
    <holder>wxWidgets team.</holder></copyright>
  <legalnotice>Licensed under the wxWindows Free Documentation Licence, Version 3
  </legalnotice>
  <title>wxControlWithItems</title>
</header>
<module>wxControlWithItems</module>
<modulesummary>Functions for wxControlWithItems class</modulesummary>
<description><p>This is convenience class that derives from both <seeerl marker="wxControl"><c>wxControl</c></seeerl> and <c>wxItemContainer</c> (not implemented in wx). It is used as basis for some wxWidgets controls (<seeerl marker="wxChoice"><c>wxChoice</c></seeerl> and <seeerl marker="wxListBox"><c>wxListBox</c></seeerl>).
      </p><p>See: <c>wxItemContainer</c> (not implemented in wx), <c>wxItemContainerImmutable</c> (not implemented in wx)
      </p>
  <p>This class is derived (and can use functions) from: 
    <seeerl marker="wxControl"><c>wxControl</c></seeerl> <seeerl marker="wxWindow"><c>wxWindow</c></seeerl> <seeerl marker="wxEvtHandler"><c>wxEvtHandler</c></seeerl></p>
  
  <p>wxWidgets docs: <url href="https://docs.wxwidgets.org/3.1/classwx_control_with_items.html">wxControlWithItems</url></p>
  </description>
<datatypes><datatype><name name="wxControlWithItems"/></datatype></datatypes>

<funcs>
  <func>
    <name name="append" arity="2" clause_i="1" since=""/>
    <fsummary>Appends item into the control. </fsummary>
    <desc><p>Appends item into the control. 
      </p><p>Return: 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 <c>wxLB_SORT</c> or <c>wxCB_SORT</c> style). 
      </p></desc>
  </func>
  
  <func>
    <name name="append" arity="3" clause_i="1" since=""/>
    <fsummary>Appends item into the control. </fsummary>
    <desc><p>Appends item into the control. 
      </p><p>Return: 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 <c>wxLB_SORT</c> or <c>wxCB_SORT</c> style). 
      </p></desc>
  </func>
  
  <func>
    <name name="appendStrings" arity="2" clause_i="1" since=""/>
    <fsummary>Appends several items at once into the control. </fsummary>
    <desc><p>Appends several items at once into the control. 
      </p><p>Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.
      </p></desc>
  </func>
  
  <func>
    <name name="appendStrings" arity="3" clause_i="1" since=""/>
    <fsummary>Appends several items at once into the control. </fsummary>
    <desc><p>Appends several items at once into the control. 
      </p><p>Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.
      </p></desc>
  </func>
  
  <func>
    <name name="clear" arity="1" clause_i="1" since=""/>
    <fsummary>Removes all items from the control. </fsummary>
    <desc><p>Removes all items from the control. 
      </p><p><seemfa marker="#clear/1"><c>clear/1</c></seemfa> also deletes the client data of the existing items if it is owned by the control. 
      </p></desc>
  </func>
  
  <func>
    <name name="delete" arity="2" clause_i="1" since=""/>
    <fsummary>Deletes an item from the control. </fsummary>
    <desc><p>Deletes an item from the control. 
      </p><p>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.
      </p><p>If there is a currently selected item below the item being deleted, i.e. if <seemfa marker="#getSelection/1"><c>getSelection/1</c></seemfa> returns a valid index greater than or equal to <c>n</c>, 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.
      </p><p>See: <seemfa marker="#clear/1"><c>clear/1</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="findString" arity="2" clause_i="1" since=""/>
    <fsummary>See: <c>findString/3</c></fsummary>
  </func>
  
  <func>
    <name name="findString" arity="3" clause_i="1" since=""/>
    <fsummary>Finds an item whose label matches the given string. </fsummary>
    <desc><p>Finds an item whose label matches the given string. 
      </p><p>Return: The zero-based position of the item, or wxNOT_FOUND if the string was not found. 
      </p></desc>
  </func>
  
  <func>
    <name name="getClientData" arity="2" clause_i="1" since=""/>
    <fsummary>Returns a pointer to the client data associated with the given item (if any). </fsummary>
    <desc><p>Returns a pointer to the client data associated with the given item (if any). 
      </p><p>It is an error to call this function for a control which doesn't have typed 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).
      </p><p>Notice that the returned pointer is still owned by the control and will be deleted by it, use <c>DetachClientObject()</c> (not implemented in wx) if you want to remove the pointer from the control.
      </p><p>Return: A pointer to the client data, or NULL if not present. 
      </p></desc>
  </func>
  
  <func>
    <name name="setClientData" arity="3" clause_i="1" since=""/>
    <fsummary>Associates the given typed client data pointer with the given item: the <c>data</c> object will be deleted when the item is deleted (either explicitly by using <c>delete/2</c> or implicitly when the control itself is destroyed). </fsummary>
    <desc><p>Associates the given typed client data pointer with the given item: the <c>data</c> object will be deleted when the item is deleted (either explicitly by using <seemfa marker="#delete/2"><c>delete/2</c></seemfa> or implicitly when the control itself is destroyed). 
      </p><p>Note that it is an error to call this function if any untyped client data pointers had been associated with the control items before.
      </p></desc>
  </func>
  
  <func>
    <name name="getCount" arity="1" clause_i="1" since=""/>
    <fsummary>Returns the number of items in the control. </fsummary>
    <desc><p>Returns the number of items in the control. 
      </p><p>See: <seemfa marker="#isEmpty/1"><c>isEmpty/1</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="getSelection" arity="1" clause_i="1" since=""/>
    <fsummary>Returns the index of the selected item or <c>wxNOT_FOUND</c> if no item is selected. </fsummary>
    <desc><p>Returns the index of the selected item or <c>wxNOT_FOUND</c> if no item is selected. 
      </p><p>Return: The position of the current selection.
      </p><p>Remark: This method can be used with single selection list boxes only, you should use <seemfa marker="wxListBox#getSelections/1"><c>wxListBox:getSelections/1</c></seemfa> for the list boxes with wxLB_MULTIPLE style.
      </p><p>See: <seemfa marker="#setSelection/2"><c>setSelection/2</c></seemfa>, <seemfa marker="#getStringSelection/1"><c>getStringSelection/1</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="getString" arity="2" clause_i="1" since=""/>
    <fsummary>Returns the label of the item with the given index. </fsummary>
    <desc><p>Returns the label of the item with the given index. 
      </p><p>Return: The label of the item or an empty string if the position was invalid. 
      </p></desc>
  </func>
  
  <func>
    <name name="getStringSelection" arity="1" clause_i="1" since=""/>
    <fsummary>Returns the label of the selected item or an empty string if no item is selected. </fsummary>
    <desc><p>Returns the label of the selected item or an empty string if no item is selected. 
      </p><p>See: <seemfa marker="#getSelection/1"><c>getSelection/1</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="insert" arity="3" clause_i="1" since=""/>
    <fsummary>Inserts item into the control. </fsummary>
    <desc><p>Inserts item into the control. 
      </p><p>Return: The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned. 
      </p></desc>
  </func>
  
  <func>
    <name name="insert" arity="4" clause_i="1" since=""/>
    <fsummary>Inserts item into the control. </fsummary>
    <desc><p>Inserts item into the control. 
      </p><p>Return: The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned. 
      </p></desc>
  </func>
  
  <func>
    <name name="insertStrings" arity="3" clause_i="1" since=""/>
    <fsummary>Inserts several items at once into the control. </fsummary>
    <desc><p>Inserts several items at once into the control. 
      </p><p>Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.
      </p><p>Return: The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned. 
      </p></desc>
  </func>
  
  <func>
    <name name="insertStrings" arity="4" clause_i="1" since=""/>
    <fsummary>Inserts several items at once into the control. </fsummary>
    <desc><p>Inserts several items at once into the control. 
      </p><p>Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.
      </p><p>Return: The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned. 
      </p></desc>
  </func>
  
  <func>
    <name name="isEmpty" arity="1" clause_i="1" since=""/>
    <fsummary>Returns true if the control is empty or false if it has some items. </fsummary>
    <desc><p>Returns true if the control is empty or false if it has some items. 
      </p><p>See: <seemfa marker="#getCount/1"><c>getCount/1</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="select" arity="2" clause_i="1" since=""/>
    <fsummary>This is the same as <c>setSelection/2</c> and exists only because it is slightly more natural for controls which support multiple selection. </fsummary>
    <desc><p>This is the same as <seemfa marker="#setSelection/2"><c>setSelection/2</c></seemfa> and exists only because it is slightly more natural for controls which support multiple selection. 
      </p></desc>
  </func>
  
  <func>
    <name name="setSelection" arity="2" clause_i="1" since=""/>
    <fsummary>Sets the selection to the given item <c>n</c> or removes the selection entirely if <c>n</c> == <c>wxNOT_FOUND</c>. </fsummary>
    <desc><p>Sets the selection to the given item <c>n</c> or removes the selection entirely if <c>n</c> == <c>wxNOT_FOUND</c>. 
      </p><p>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.
      </p><p>See: <seemfa marker="#setString/3"><c>setString/3</c></seemfa>, <seemfa marker="#setStringSelection/2"><c>setStringSelection/2</c></seemfa>
      </p></desc>
  </func>
  
  <func>
    <name name="setString" arity="3" clause_i="1" since=""/>
    <fsummary>Sets the label for the given item. </fsummary>
    <desc><p>Sets the label for the given item. 
      </p></desc>
  </func>
  
  <func>
    <name name="setStringSelection" arity="2" clause_i="1" since=""/>
    <fsummary>Selects the item with the specified string in the control. </fsummary>
    <desc><p>Selects the item with the specified string in the control. 
      </p><p>This method doesn't cause any command events to be emitted.
      </p><p>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.
      </p><p>Return: true if the specified string has been selected, false if it wasn't found in the control. 
      </p></desc>
  </func>
  </funcs>
</erlref>
