avoid infinite recursion for richtooltops, (hopefully) fixes #15070

[wxWidgets.git] / interface / wx / listbox.h

diff --git a/interface/wx/listbox.h b/interface/wx/listbox.h
index 7d9ad3baaa12edfa3ca1c8068f680042bca7b293..538223e6f470b95add491b7e6f39310d3be02a85 100644 (file)
--- a/interface/wx/listbox.h
+++ b/interface/wx/listbox.h
@@ -3,78 +3,112 @@
 // Purpose:     interface of wxListBox
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxListBox
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxListBox
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxListBox

-    @wxheader{listbox.h}

 
 

-    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
+    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).
 
     (clicking an item toggles the item on or off independently of other
     selections).
 

-    List box elements are numbered from zero. Their number may be limited
-    under some platforms.
+    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 wxDataViewCtrl or
+    wxListCtrl with @c wxLC_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.

 
 

-    A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for
-    single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks.
+    Notice that currently @c TAB characters in list box items text are not
+    handled consistently under all platforms, so they should be replaced by
+    spaces to display strings properly everywhere. The list box doesn't
+    support any other control characters at all.

 
     @beginStyleTable
     @style{wxLB_SINGLE}
 
     @beginStyleTable
     @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. This is the same as wxLB_EXTENDED in wxGTK2 port.
+        Multiple-selection list: the user can toggle multiple items on and off.
+        This is the same as wxLB_EXTENDED in wxGTK2 port.

     @style{wxLB_EXTENDED}
     @style{wxLB_EXTENDED}

-           Extended-selection list: the user can extend the selection by using
-           @c SHIFT or @c CTRL keys together with the cursor movement keys or
-           the mouse.
+        Extended-selection list: the user can extend the selection by using
+        @c SHIFT or @c CTRL keys together with the cursor movement keys or
+        the mouse.

     @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_NO_SB}
+        Don't create vertical scrollbar (wxMSW only).

     @style{wxLB_SORT}
     @style{wxLB_SORT}

-           The listbox contents are sorted in alphabetical order.
+        The listbox contents are sorted in alphabetical order.

     @endStyleTable
 
     @endStyleTable
 

-    @beginEventTable{wxCommandEvent}
+    Note that @c wxLB_SINGLE, @c wxLB_MULTIPLE and @c wxLB_EXTENDED styles are
+    mutually exclusive and you can specify at most one of them (single selection
+    is the default). See also @ref overview_windowstyles.
+
+    @beginEventEmissionTable{wxCommandEvent}

     @event{EVT_LISTBOX(id, func)}
     @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 @c wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
+        list is selected or the selection changes.

     @event{EVT_LISTBOX_DCLICK(id, func)}
     @event{EVT_LISTBOX_DCLICK(id, func)}

-           Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the
-           listbox is double-clicked.
+        Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox
+        is double-clicked.

     @endEventTable
 
     @library{wxcore}
     @category{ctrl}
     @endEventTable
 
     @library{wxcore}
     @category{ctrl}

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

 
 

-    @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
+    @see wxEditableListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent

 */
 */

-class wxListBox : public wxControlWithItems
+class wxListBox : public wxControl,
+                  public wxItemContainer

 {
 public:
     /**
         Default constructor.
     */
     wxListBox();
 {
 public:
     /**
         Default constructor.
     */
     wxListBox();

-    
+

     /**
     /**

-        Constructor 
+        Constructor, creating and showing a list box.

 
 

+        @param parent
+            The parent window.
+        @param id
+            The ID of this control. A value of @c wxID_ANY indicates a default value.
+        @param pos
+            The initial position.
+            If ::wxDefaultPosition is specified then a default position is chosen.
+        @param size
+            The initial size.
+            If ::wxDefaultSize is specified then the window is sized appropriately.

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

+        @param choices
+            The strings to use to initialize the control.

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

+        @param validator
+            The validator for this control.
+        @param name
+            The name of this class.
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     */

-    
+

     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,


@@ -82,50 +116,52 @@ public:
               const wxString choices[] = NULL,
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,
               const wxString choices[] = NULL,
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,

-              const wxString& name = "listBox");
-              
+              const wxString& name = wxListBoxNameStr);
+

     /**
     /**

-        Constructor 
+        Constructor, creating and showing a list box.

 
 

-        @param choices
-            An array of strings with which to initialise the control.
-        @param style
-            Window style. See wxListBox.
+        See the other wxListBox() constructor; the only difference is that
+        this overload takes a wxArrayString instead of a pointer to an array
+        of wxString.
+
+        @beginWxPerlOnly
+        Use an array reference for the @a choices parameter.
+        @endWxPerlOnly

     */
     */

-    
+

     wxListBox(wxWindow* parent, wxWindowID id,
               const wxPoint& pos,
               const wxSize& size,
               const wxArrayString& choices,
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,
     wxListBox(wxWindow* parent, wxWindowID id,
               const wxPoint& pos,
               const wxSize& size,
               const wxArrayString& choices,
               long style = 0,
               const wxValidator& validator = wxDefaultValidator,

-              const wxString& name = "listBox");
+              const wxString& name = wxListBoxNameStr);

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

-    ~wxListBox();
+    virtual ~wxListBox();

 
     //@{
     /**
 
     //@{
     /**

-        Creates the listbox for two-step construction. See wxListBox()
-        for further details.
+        Creates the listbox for two-step construction.
+        See wxListBox() for further details.

     */
     */

-    bool Create(wxWindow* parent, wxWindowID id,
+    bool Create(wxWindow *parent, wxWindowID id,

                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,

-                int n,
-                const wxString choices[] = NULL,
+                int n = 0, const wxString choices[] = NULL,

                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,
                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "listBox");
-    bool Create(wxWindow* parent, wxWindowID id,
+                const wxString& name = wxListBoxNameStr);
+    bool Create(wxWindow *parent, wxWindowID id,

                 const wxPoint& pos,
                 const wxSize& size,
                 const wxArrayString& choices,
                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxPoint& pos,
                 const wxSize& size,
                 const wxArrayString& choices,
                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "listBox");
+                const wxString& name = wxListBoxNameStr);

     //@}
 
     /**
     //@}
 
     /**


@@ -138,25 +174,37 @@ public:
     */
     void Deselect(int n);
 
     */
     void Deselect(int n);
 

+    virtual void SetSelection(int n);
+    
+    virtual int GetSelection() const;
+    
+    virtual bool SetStringSelection(const wxString& s, bool select);
+    virtual bool SetStringSelection(const wxString& s);
+

     /**
         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
     /**
         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.
+            the query.

 
         @return The number of selections.
 
         @remarks Use this with a multiple selection listbox.
 
 
         @return The number of selections.
 
         @remarks Use this with a multiple selection listbox.
 

+        @beginWxPerlOnly
+        In wxPerl this method takes no parameters and return the
+        selected items as a list.
+        @endWxPerlOnly
+

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

-    int GetSelections(wxArrayInt& selections) const;
+    virtual int GetSelections(wxArrayInt& selections) const;

 
     /**
 
     /**

-        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 @a point, or @c wxNOT_FOUND if there
+        is no item located at @a point.

 
         It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
 
 
         It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
 


@@ -164,11 +212,16 @@ public:
             Point of item (in client coordinates) to obtain
 
         @return Item located at point, or wxNOT_FOUND if unimplemented or the
             Point of item (in client coordinates) to obtain
 
         @return Item located at point, or wxNOT_FOUND if unimplemented or the

-                 item does not exist.
+                item does not exist.

 
         @since 2.7.0
     */
 
         @since 2.7.0
     */

-    int HitTest(const wxPoint point) const;
+    int HitTest(const wxPoint& point) const;
+
+    /**
+        @overload
+    */
+    int HitTest(int x, int y) const;

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


@@ -180,8 +233,12 @@ public:
         @param pos
             Position before which to insert the items: if pos is 0 the
             items will be inserted in the beginning of the listbox
         @param pos
             Position before which to insert the items: if pos is 0 the
             items will be inserted in the beginning of the listbox

+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     */

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

                      unsigned int pos);
 
     /**
                      unsigned int pos);
 
     /**


@@ -190,8 +247,12 @@ public:
         @param items
             Labels of items to be inserted
         @param pos
         @param items
             Labels of items to be inserted
         @param pos

-            Position before which to insert the items: if pos is 0 the
+            Position before which to insert the items: if pos is @c 0 the

             items will be inserted in the beginning of the listbox
             items will be inserted in the beginning of the listbox

+
+        @beginWxPerlOnly
+        Use an array reference for the @a items parameter.
+        @endWxPerlOnly

     */
     void InsertItems(const wxArrayString& items,
                      unsigned int pos);
     */
     void InsertItems(const wxArrayString& items,
                      unsigned int pos);


@@ -204,32 +265,7 @@ public:
 
         @return @true if the given item is selected, @false otherwise.
     */
 
         @return @true if the given item is selected, @false otherwise.
     */

-    bool IsSelected(int n) const;
-
-    /**
-        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
-    */
-    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 **clientData = NULL);
+    virtual bool IsSelected(int n) const;

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


@@ -246,5 +282,32 @@ public:
             The string that should be visible.
     */
     void SetFirstItem(const wxString& string);
             The string that should be visible.
     */
     void SetFirstItem(const wxString& string);

+
+    /**
+        Ensure that the item with the given index is currently shown.
+
+        Scroll the listbox if necessary.
+
+        This method is currently only implemented in wxGTK and wxOSX and does
+        nothing in other ports.
+
+        @see SetFirstItem()
+     */
+    virtual void EnsureVisible(int n);
+
+    /**
+        Return true if the listbox has ::wxLB_SORT style.
+
+        This method is mostly meant for internal use only.
+     */
+    virtual bool IsSorted() const;
+
+
+    // NOTE: Phoenix needs to see the implementation of pure virtuals so it
+    // knows that this class is not abstract.
+    virtual unsigned int GetCount() const; 
+    virtual wxString GetString(unsigned int n) const; 
+    virtual void SetString(unsigned int n, const wxString& s); 
+    virtual int FindString(const wxString& s, bool bCase = false) const;     

 };
 
 };