include wx/crt.h to get wxUSE_WXVSNPRINTF

[wxWidgets.git] / interface / listbox.h

diff --git a/interface/listbox.h b/interface/listbox.h
index 497bac585c4dff4acd3cc237bbe46dbb3e10ef22..eaf1d8e1a4abdce6a008d77ec6ce9016adf628ed 100644 (file)
--- a/interface/listbox.h
+++ b/interface/listbox.h
@@ -20,75 +20,60 @@
     List box elements are numbered from zero. Their number may be limited
     under some platforms.
 
     List box elements are numbered from zero. Their number may be limited
     under some platforms.
 

-    A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for single
-    clicks, and
-    wxEVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks.
+    A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for
+    single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks.

 
     @beginStyleTable
 
     @beginStyleTable

-    @style{wxLB_SINGLE}:
+    @style{wxLB_SINGLE}

            Single-selection list.
            Single-selection list.

-    @style{wxLB_MULTIPLE}:
+    @style{wxLB_MULTIPLE}

            Multiple-selection list: the user can toggle multiple items on and
            off.
            Multiple-selection list: the user can toggle multiple items on and
            off.

-    @style{wxLB_EXTENDED}:
+    @style{wxLB_EXTENDED}

            Extended-selection list: the user can select multiple items using
            the SHIFT key and the mouse or special key combinations.
            Extended-selection list: the user can select multiple items using
            the SHIFT key and the mouse or special key combinations.

-    @style{wxLB_HSCROLL}:
+    @style{wxLB_HSCROLL}

            Create horizontal scrollbar if contents are too wide (Windows only).
            Create horizontal scrollbar if contents are too wide (Windows only).

-    @style{wxLB_ALWAYS_SB}:
+    @style{wxLB_ALWAYS_SB}

            Always show a vertical scrollbar.
            Always show a vertical scrollbar.

-    @style{wxLB_NEEDED_SB}:
+    @style{wxLB_NEEDED_SB}

            Only create a vertical scrollbar if needed.
            Only create a vertical scrollbar if needed.

-    @style{wxLB_SORT}:
+    @style{wxLB_SORT}

            The listbox contents are sorted in alphabetical order.
     @endStyleTable
 
            The listbox contents are sorted in alphabetical order.
     @endStyleTable
 

-    @beginEventTable
-    @event{EVT_LISTBOX(id, func)}:
+    @beginEventTable{wxCommandEvent}
+    @event{EVT_LISTBOX(id, func)}

            Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
            list is selected or the selection changes.
            Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
            list is selected or the selection changes.

-    @event{EVT_LISTBOX_DCLICK(id, func)}:
-           Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the
+    @event{EVT_LISTBOX_DCLICK(id, func)}
+           Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the

            listbox is double-clicked.
     @endEventTable
 
     @library{wxcore}
     @category{ctrl}
            listbox is double-clicked.
     @endEventTable
 
     @library{wxcore}
     @category{ctrl}

-    @appearance{listbox.png}
+    <!-- @appearance{listbox.png} -->

 
     @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
 */
 class wxListBox : public wxControlWithItems
 {
 public:
 
     @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
 */
 class wxListBox : public wxControlWithItems
 {
 public:

-    //@{

     /**
     /**

-        Constructor, creating and showing a list box.
-        
-        @param parent
-            Parent window. Must not be @NULL.
-        @param id
-            Window identifier. The value wxID_ANY indicates a default value.
-        @param pos
-            Window position.
-        @param size
-            Window size. If wxDefaultSize is specified then the window is
-        sized
-            appropriately.
+        Default constructor.
+    */
+    wxListBox();
+    
+    /**
+        Constructor 
+

         @param n
             Number of strings with which to initialise the control.
         @param n
             Number of strings with which to initialise the control.

-        @param choices
-            An array of strings with which to initialise the control.

         @param style
             Window style. See wxListBox.
         @param style
             Window style. See wxListBox.

-        @param validator
-            Window validator.
-        @param name
-            Window name.
-        
-        @see Create(), wxValidator

     */
     */

-    wxListBox();
+    

     wxListBox(wxWindow* parent, wxWindowID id,
               const wxPoint& pos = wxDefaultPosition,
               const wxSize& size = wxDefaultSize,
     wxListBox(wxWindow* parent, wxWindowID id,
               const wxPoint& pos = wxDefaultPosition,
               const wxSize& size = wxDefaultSize,


@@ -97,6 +82,16 @@ public:
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,
               const wxString& name = "listBox");
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,
               const wxString& name = "listBox");

+              
+    /**
+        Constructor 
+
+        @param choices
+            An array of strings with which to initialise the control.
+        @param style
+            Window style. See wxListBox.
+    */
+    

     wxListBox(wxWindow* parent, wxWindowID id,
               const wxPoint& pos,
               const wxSize& size,
     wxListBox(wxWindow* parent, wxWindowID id,
               const wxPoint& pos,
               const wxSize& size,


@@ -104,7 +99,6 @@ public:
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,
               const wxString& name = "listBox");
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,
               const wxString& name = "listBox");

-    //@}

 
     /**
         Destructor, destroying the list box.
 
     /**
         Destructor, destroying the list box.


@@ -135,25 +129,25 @@ public:
 
     /**
         Deselects an item in the list box.
 
     /**
         Deselects an item in the list box.

-        
+

         @param n
             The zero-based item to deselect.
         @param n
             The zero-based item to deselect.

-        
+

         @remarks This applies to multiple selection listboxes only.
     */
     void Deselect(int n);
 
     /**
         Fill an array of ints with the positions of the currently selected items.
         @remarks This applies to multiple selection listboxes only.
     */
     void Deselect(int n);
 
     /**
         Fill an array of ints with the positions of the currently selected items.

-        
+

         @param selections
             A reference to an wxArrayInt instance that is used to store the result of
         the query.
         @param selections
             A reference to an wxArrayInt instance that is used to store the result of
         the query.

-        
-        @returns The number of selections.
-        
+
+        @return The number of selections.
+

         @remarks Use this with a multiple selection listbox.
         @remarks Use this with a multiple selection listbox.

-        
+

         @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
              wxControlWithItems::SetSelection
     */
         @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
              wxControlWithItems::SetSelection
     */


@@ -162,78 +156,94 @@ public:
     /**
         Returns the item located at @e point, or @c wxNOT_FOUND if there
         is no item located at @e point.
     /**
         Returns the item located at @e point, or @c wxNOT_FOUND if there
         is no item located at @e point.

-        
-        @wxsince{2.7.0}. It is currently implemented
-        for wxMSW, wxMac and wxGTK2
-        ports.
-        
+
+        It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
+

         @param point
             Point of item (in client coordinates) to obtain
         @param point
             Point of item (in client coordinates) to obtain

-        
-        @returns Item located at point, or wxNOT_FOUND if unimplemented or the
+
+        @return Item located at point, or wxNOT_FOUND if unimplemented or the

                  item does not exist.
                  item does not exist.

+
+        @since 2.7.0

     */
     int HitTest(const wxPoint point) const;
 
     */
     int HitTest(const wxPoint point) const;
 

-    //@{

     /**
         Insert the given number of strings before the specified position.
     /**
         Insert the given number of strings before the specified position.

-        
+

         @param nItems
             Number of items in the array items
         @param items
             Labels of items to be inserted
         @param pos
         @param nItems
             Number of items in the array items
         @param items
             Labels of items to be inserted
         @param pos

-            Position before which to insert the items: for example, if pos is 0 the
-        items
-            will be inserted in the beginning of the listbox
+            Position before which to insert the items: if pos is 0 the
+            items will be inserted in the beginning of the listbox

     */
     */

-    void InsertItems(int nItems, const wxString items,
+    void InsertItems(int nItems, const wxString *items,

                      unsigned int pos);
                      unsigned int pos);

-    void InsertItems(const wxArrayString& nItems,
+
+    /**
+        Insert the given number of strings before the specified position.
+
+        @param items
+            Labels of items to be inserted
+        @param pos
+            Position before which to insert the items: if pos is 0 the
+            items will be inserted in the beginning of the listbox
+    */
+    void InsertItems(const wxArrayString& items,

                      unsigned int pos);
                      unsigned int pos);

-    //@}

 
     /**
         Determines whether an item is selected.
 
     /**
         Determines whether an item is selected.

-        
+

         @param n
             The zero-based item index.
         @param n
             The zero-based item index.

-        
-        @returns @true if the given item is selected, @false otherwise.
+
+        @return @true if the given item is selected, @false otherwise.

     */
     bool IsSelected(int n) const;
 
     */
     bool IsSelected(int n) const;
 

-    //@{

     /**
         Clears the list box and adds the given strings to it.
     /**
         Clears the list box and adds the given strings to it.

-        
+

         @param n
             The number of strings to set.
         @param choices
             An array of strings to set.
         @param clientData
             Options array of client data pointers
         @param n
             The number of strings to set.
         @param choices
             An array of strings to set.
         @param clientData
             Options array of client data pointers

-        
-        @remarks You may free the array from the calling program after this
-                 function has been called.

     */
     */

-    void Set(int n, const wxString* choices, void clientData = NULL);
+    void Set(int n, const wxString* choices, void **clientData = NULL);
+
+    /**
+        Clears the list box and adds the given strings to it. You may
+        free the array from the calling program after this method
+        has been called.
+
+        @param choices
+            An array of strings to set.
+        @param clientData
+            Options array of client data pointers
+    */

     void Set(const wxArrayString& choices,
     void Set(const wxArrayString& choices,

-             void clientData = NULL);
-    //@}
+             void **clientData = NULL);

 
 

-    //@{

     /**
         Set the specified item to be the first visible item.
     /**
         Set the specified item to be the first visible item.

-        
+

         @param n
         @param n

-            The zero-based item index.
+            The zero-based item index that should be visible.
+    */
+    void SetFirstItem(int n);
+
+    /**
+        Set the specified item to be the first visible item.
+

         @param string
             The string that should be visible.
     */
         @param string
             The string that should be visible.
     */

-    void SetFirstItem(int n);

     void SetFirstItem(const wxString& string);
     void SetFirstItem(const wxString& string);

-    //@}

 };
 
 };