X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3051a44a73502c2b03d1618d0a8e94274ee67e16..fe94d0d06a2305845f0cb0c0b8fc0edbde2e2b68:/interface/wx/listbox.h diff --git a/interface/wx/listbox.h b/interface/wx/listbox.h index 0877c5b746..e16f32abde 100644 --- a/interface/wx/listbox.h +++ b/interface/wx/listbox.h @@ -2,8 +2,7 @@ // Name: listbox.h // Purpose: interface of wxListBox // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -17,11 +16,18 @@ (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 @c wxEVT_COMMAND_LISTBOX_SELECTED for - single clicks, and @c 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} @@ -39,6 +45,8 @@ Always show a vertical scrollbar. @style{wxLB_NEEDED_SB} Only create a vertical scrollbar if needed. + @style{wxLB_NO_SB} + Don't create vertical scrollbar (wxMSW only). @style{wxLB_SORT} The listbox contents are sorted in alphabetical order. @endStyleTable @@ -49,20 +57,21 @@ @beginEventEmissionTable{wxCommandEvent} @event{EVT_LISTBOX(id, func)} - Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the + Process a @c wxEVT_LISTBOX event, when an item on the list is selected or the selection changes. @event{EVT_LISTBOX_DCLICK(id, func)} - Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the listbox + Process a @c wxEVT_LISTBOX_DCLICK event, when the listbox is double-clicked. @endEventTable @library{wxcore} @category{ctrl} - @appearance{listbox.png} + @appearance{listbox} @see wxEditableListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent */ -class wxListBox : public wxControlWithItems +class wxListBox : public wxControl, + public wxItemContainer { public: /** @@ -79,9 +88,10 @@ public: 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. + If ::wxDefaultSize is specified then the window is sized appropriately. @param n Number of strings with which to initialise the control. @param choices @@ -92,6 +102,10 @@ public: The validator for this control. @param name The name of this class. + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ wxListBox(wxWindow* parent, wxWindowID id, @@ -109,6 +123,10 @@ public: 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, @@ -155,6 +173,13 @@ public: */ 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. @@ -166,6 +191,11 @@ public: @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 */ @@ -202,6 +232,10 @@ 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 + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void InsertItems(unsigned int nItems, const wxString *items, unsigned int pos); @@ -214,6 +248,10 @@ public: @param pos Position before which to insert the items: if pos is @c 0 the 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); @@ -228,30 +266,6 @@ public: */ virtual 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(unsigned int n, const wxString* choices, void *clientData); - - /** - 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); - /** Set the specified item to be the first visible item. @@ -267,5 +281,32 @@ public: 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; };