X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/74d9b8fbd6e7bae0735fb9e059ba4a54082e693e..a8bda512079352ba81933e278d9ccdb8ef7a9866:/interface/wx/dataview.h?ds=inline diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h index c33bb6d0af..f8961f8274 100644 --- a/interface/wx/dataview.h +++ b/interface/wx/dataview.h @@ -3,7 +3,7 @@ // Purpose: interface of wxDataView* classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -20,17 +20,26 @@ wxDataViewModel::GetValue in order to define the data model which acts as an interface between your actual data and the wxDataViewCtrl. - Since you will usually also allow the wxDataViewCtrl to change your data - through its graphical interface, you will also have to override - wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change - to some data has been committed. + Note that wxDataViewModel does not define the position or index of any item + in the control because different controls might display the same data differently. + wxDataViewModel does provide a wxDataViewModel::Compare method which the + wxDataViewCtrl may use to sort the data either in conjunction with a column + header or without (see wxDataViewModel::HasDefaultCompare). wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant to store data and its type in a generic way. wxVariant can be extended to contain - almost any data without changes to the original class. + almost any data without changes to the original class. To a certain extent, + you can use (the somewhat more elegant) wxAny instead of wxVariant as there + is code to convert between the two, but it is unclear what impact this will + have on performance. + + Since you will usually allow the wxDataViewCtrl to change your data + through its graphical interface, you will also have to override + wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change + to some data has been committed. - The data that is presented through this data model is expected to change at - run-time. You need to inform the data model when a change happened. + If the data represented by the model is changed by something else than its + associated wxDataViewCtrl, the control has to be notified about the change. Depending on what happened you need to call one of the following methods: - wxDataViewModel::ValueChanged, - wxDataViewModel::ItemAdded, @@ -44,12 +53,6 @@ - wxDataViewModel::ItemsDeleted, - wxDataViewModel::ItemsChanged. - Note that wxDataViewModel does not define the position or index of any item - in the control because different controls might display the same data differently. - wxDataViewModel does provide a wxDataViewModel::Compare method which the - wxDataViewCtrl may use to sort the data either in conjunction with a column - header or without (see wxDataViewModel::HasDefaultCompare). - This class maintains a list of wxDataViewModelNotifier which link this class to the specific implementations on the supported platforms so that e.g. calling wxDataViewModel::ValueChanged on this model will just call @@ -75,6 +78,19 @@ // add columns now @endcode + A potentially better way to avoid memory leaks is to use wxObjectDataPtr + + @code + wxObjectDataPtr musicModel; + + wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY ); + musicModel = new MyMusicModel; + m_musicCtrl->AssociateModel( musicModel.get() ); + + // add columns now + @endcode + + @library{wxadv} @category{dvc} */ @@ -100,7 +116,7 @@ public: @since 2.9.1 - @param variable + @param variant The new value. @param item The item (row) to update. @@ -151,6 +167,33 @@ public: virtual bool GetAttr(const wxDataViewItem& item, unsigned int col, wxDataViewItemAttr& attr) const; + /** + Override this to indicate that the item should be disabled. + + Disabled items are displayed differently (e.g. grayed out) and cannot + be interacted with. + + The base class version always returns @true, thus making all items + enabled by default. + + @param item + The item whose enabled status is requested. + @param col + The column of the item whose enabled status is requested. + @return + @true if this item should be enabled, @false otherwise. + + @note Currently disabling items is fully implemented only for the + native control implementation in wxOSX/Cocoa and wxGTK. + This feature is only partially supported in the generic + version (used by wxMSW) and not supported by the wxOSX/Carbon + implementation. + + @since 2.9.2 + */ + virtual bool IsEnabled(const wxDataViewItem &item, + unsigned int col) const; + /** Override this so the control can query the child items of an item. Returns the number of items. @@ -227,41 +270,41 @@ public: /** Call this to inform the model that an item has been added to the data. */ - virtual bool ItemAdded(const wxDataViewItem& parent, + bool ItemAdded(const wxDataViewItem& parent, const wxDataViewItem& item); /** Call this to inform the model that an item has changed. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event (in which the column fields will not be set) to the user. */ - virtual bool ItemChanged(const wxDataViewItem& item); + bool ItemChanged(const wxDataViewItem& item); /** Call this to inform the model that an item has been deleted from the data. */ - virtual bool ItemDeleted(const wxDataViewItem& parent, + bool ItemDeleted(const wxDataViewItem& parent, const wxDataViewItem& item); /** Call this to inform the model that several items have been added to the data. */ - virtual bool ItemsAdded(const wxDataViewItem& parent, + bool ItemsAdded(const wxDataViewItem& parent, const wxDataViewItemArray& items); /** Call this to inform the model that several items have changed. - This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + This will eventually emit @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED events (in which the column fields will not be set) to the user. */ - virtual bool ItemsChanged(const wxDataViewItemArray& items); + bool ItemsChanged(const wxDataViewItemArray& items); /** Call this to inform the model that several items have been deleted. */ - virtual bool ItemsDeleted(const wxDataViewItem& parent, + bool ItemsDeleted(const wxDataViewItem& parent, const wxDataViewItemArray& items); /** @@ -294,7 +337,7 @@ public: This is also called from wxDataViewCtrl's internal editing code, e.g. when editing a text field in the control. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event to the user. */ virtual bool ValueChanged(const wxDataViewItem& item, @@ -311,28 +354,17 @@ protected: /** - @class wxDataViewIndexListModel + @class wxDataViewListModel - wxDataViewIndexListModel is a specialized data model which lets you address - an item by its position (row) rather than its wxDataViewItem (which you can - obtain from this class). - This model also provides its own wxDataViewIndexListModel::Compare - method which sorts the model's data by the index. - - This model is not a virtual model since the control stores each wxDataViewItem. - Use wxDataViewVirtualListModel if you need to display millions of items or - have other reason to use a virtual control. + Base class with abstract API for wxDataViewIndexListModel and + wxDataViewVirtualListModel. @library{wxadv} @category{dvc} */ -class wxDataViewIndexListModel : public wxDataViewModel +class wxDataViewListModel : public wxDataViewModel { public: - /** - Constructor. - */ - wxDataViewIndexListModel(unsigned int initial_size = 0); /** Destructor. @@ -366,6 +398,28 @@ public: virtual bool GetAttrByRow(unsigned int row, unsigned int col, wxDataViewItemAttr& attr) const; + /** + Override this if you want to disable specific items. + + The base class version always returns @true, thus making all items + enabled by default. + + @param row + The row of the item whose enabled status is requested. + @param col + The column of the item whose enabled status is requested. + @return + @true if the item at this row and column should be enabled, + @false otherwise. + + @note See wxDataViewModel::IsEnabled() for the current status of + support for disabling the items under different platforms. + + @since 2.9.2 + */ + virtual bool IsEnabledByRow(unsigned int row, + unsigned int col) const; + /** Returns the number of items (i.e. rows) in the list. */ @@ -439,6 +493,34 @@ public: }; +/** + @class wxDataViewIndexListModel + + wxDataViewIndexListModel is a specialized data model which lets you address + an item by its position (row) rather than its wxDataViewItem (which you can + obtain from this class). + This model also provides its own wxDataViewIndexListModel::Compare + method which sorts the model's data by the index. + + This model is not a virtual model since the control stores each wxDataViewItem. + Use wxDataViewVirtualListModel if you need to display millions of items or + have other reason to use a virtual control. + + @see wxDataViewListModel for the API. + + @library{wxadv} + @category{dvc} +*/ + +class wxDataViewIndexListModel : public wxDataViewListModel +{ +public: + /** + Constructor. + */ + wxDataViewIndexListModel(unsigned int initial_size = 0); + +}; /** @class wxDataViewVirtualListModel @@ -448,15 +530,15 @@ public: the exact same interface as wxDataViewIndexListModel. The important difference is that under platforms other than OS X, using this model will result in a truly virtual control able to handle millions of items - as the control doesn't store any item (a feature not supported by the - Carbon API under OS X). + as the control doesn't store any item (a feature not supported by OS X). - @see wxDataViewIndexListModel for the API. + @see wxDataViewListModel for the API. @library{wxadv} @category{dvc} */ -class wxDataViewVirtualListModel : public wxDataViewModel + +class wxDataViewVirtualListModel : public wxDataViewListModel { public: /** @@ -464,10 +546,6 @@ public: */ wxDataViewVirtualListModel(unsigned int initial_size = 0); - /** - Returns the number of virtual items (i.e. rows) in the list. - */ - unsigned int GetCount() const; }; @@ -514,7 +592,7 @@ public: @class wxDataViewItem wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl - in a persistent way, i.e. indepent of the position of the item in the control + in a persistent way, i.e. independent of the position of the item in the control or changes to its contents. It must hold a unique ID of type @e void* in its only field and can be converted @@ -589,6 +667,8 @@ public: Multiple selection mode. @style{wxDV_ROW_LINES} Use alternating colours for rows if supported by platform and theme. + Currently only supported by the native GTK and OS X implementations + but not by the generic one. @style{wxDV_HORIZ_RULES} Display fine rules between row if supported. @style{wxDV_VERT_RULES} @@ -596,6 +676,8 @@ public: @style{wxDV_VARIABLE_LINE_HEIGHT} Allow variable line heights. This can be inefficient when displaying large number of items. + @style{wxDV_NO_HEADER} + Do not show column headers (which are shown by default). @endStyleTable @beginEventEmissionTable{wxDataViewEvent} @@ -658,7 +740,8 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = 0, - const wxValidator& validator = wxDefaultValidator); + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxDataViewCtrlNameStr); /** Destructor. @@ -839,7 +922,8 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = 0, - const wxValidator& validator = wxDefaultValidator); + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxDataViewCtrlNameStr); /** Deletes given column. @@ -895,6 +979,26 @@ public: */ wxDataViewColumn* GetExpanderColumn() const; + /** + Returns the currently focused item. + + This is the item that the keyboard commands apply to. It may be invalid + if there is no focus currently. + + This method is mostly useful for the controls with @c wxDV_MULTIPLE + style as in the case of single selection it returns the same thing as + GetSelection(). + + Notice that under all platforms except Mac OS X the currently focused + item may be selected or not but under OS X the current item is always + selected. + + @see SetCurrentItem() + + @since 2.9.2 + */ + wxDataViewItem GetCurrentItem() const; + /** Returns indentation. */ @@ -945,6 +1049,10 @@ public: /** Select the given item. + + In single selection mode this changes the (unique) currently selected + item. In multi selection mode, the @a item is selected and the + previously selected items remain selected. */ virtual void Select(const wxDataViewItem& item); @@ -958,6 +1066,25 @@ public: */ void SetExpanderColumn(wxDataViewColumn* col); + /** + Changes the currently focused item. + + The @a item parameter must be valid, there is no way to remove the + current item from the control. + + In single selection mode, calling this method is the same as calling + Select() and is thus not very useful. In multiple selection mode this + method only moves the current item however without changing the + selection except under OS X where the current item is always selected, + so calling SetCurrentItem() selects @a item if it hadn't been selected + before. + + @see GetCurrentItem() + + @since 2.9.2 + */ + void SetCurrentItem(const wxDataViewItem& item); + /** Sets the indendation. */ @@ -1112,6 +1239,7 @@ enum wxDataViewCellRenderState - wxDataViewBitmapRenderer, - wxDataViewDateRenderer, - wxDataViewSpinRenderer. + - wxDataViewChoiceRenderer. Additionally, the user can write own renderers by deriving from wxDataViewCustomRenderer. @@ -1266,8 +1394,8 @@ public: a small icon next to it as it is typically done in a file manager. This classes uses the wxDataViewIconText helper class to store its data. - wxDataViewIonText can be converted to and from a wxVariant using the left shift - operator. + wxDataViewIconText can be converted to and from a wxVariant using the left + shift operator. @library{wxadv} @category{dvc} @@ -1351,6 +1479,38 @@ public: }; +/** + @class wxDataViewChoiceRenderer + + This class is used by wxDataViewCtrl to render choice controls. + It stores a string so that SetValue() and GetValue() operate + on a variant holding a string. + + @library{wxadv} + @category{dvc} +*/ + +class wxDataViewChoiceRenderer: public wxDataViewRenderer +{ +public: + /** + The ctor. + */ + wxDataViewChoiceRenderer( const wxArrayString &choices, + wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, + int alignment = wxDVR_DEFAULT_ALIGNMENT ); + + /** + Returns the choice referred to by index. + */ + wxString GetChoice(size_t index) const; + + /** + Returns all choices. + */ + const wxArrayString& GetChoices() const; +}; + /** @class wxDataViewDateRenderer @@ -1435,9 +1595,20 @@ public: const wxVariant& value); /** - Create DC on request. Internal. - */ - virtual wxDC* GetDC(); + Return the attribute to be used for rendering. + + This function may be called from Render() implementation to use the + attributes defined for the item if the renderer supports them. + + Notice that when Render() is called, the wxDC object passed to it is + already set up to use the correct attributes (e.g. its font is set to + bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic() + returns true) so it may not be necessary to call it explicitly if you + only want to render text using the items attributes. + + @since 2.9.1 + */ + const wxDataViewItemAttr& GetAttr() const; /** Return size required to show content. @@ -1445,7 +1616,7 @@ public: virtual wxSize GetSize() const = 0; /** - Overrride this so that the renderer can get the value from the editor + Override this so that the renderer can get the value from the editor control (pointed to by @a editor): @code { @@ -1466,7 +1637,7 @@ public: virtual bool HasEditorCtrl() const; /** - Overrride this to react to a left click. + Override this to react to a left click. This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode. */ virtual bool LeftClick( wxPoint cursor, @@ -1492,7 +1663,7 @@ public: wxDC* dc, int state); /** - Overrride this to start a drag operation. Not yet supported. + Override this to start a drag operation. Not yet supported. */ virtual bool StartDrag(wxPoint cursor, wxRect cell, wxDataViewModel* model, @@ -1692,6 +1863,64 @@ public: const wxDataViewListStore *GetStore() const; //@} + /** + Returns the position of given @e item or wxNOT_FOUND if it's + not a valid item. + + @since 2.9.2 + */ + int ItemToRow(const wxDataViewItem &item) const; + + /** + Returns the wxDataViewItem at the given @e row. + + @since 2.9.2 + */ + wxDataViewItem RowToItem(int row) const; + + //@{ + /** + @name Selection handling functions + */ + + /** + Returns index of the selected row or wxNOT_FOUND. + + @see wxDataViewCtrl::GetSelection() + + @since 2.9.2 + */ + int GetSelectedRow() const; + + /** + Selects given row. + + @see wxDataViewCtrl::Select() + + @since 2.9.2 + */ + void SelectRow(unsigned row); + + /** + Unselects given row. + + @see wxDataViewCtrl::Unselect() + + @since 2.9.2 + */ + void UnselectRow(unsigned row); + + /** + Returns true if @a row is selected. + + @see wxDataViewCtrl::IsSelected() + + @since 2.9.2 + */ + bool IsRowSelected(unsigned row) const; + + //@} + /** @name Column management functions */ @@ -2012,6 +2241,11 @@ public: int icon = -1, wxClientData* data = NULL); + /** + Returns true if item is a container. + */ + bool IsContainer( const wxDataViewItem& item ); + /** Calls the same method from wxDataViewTreeStore but uses an index position in the image list instead of a wxIcon. @@ -2458,7 +2692,7 @@ public: void SetColumn(int col); /** - For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. + For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. */ void SetDataViewColumn(wxDataViewColumn* col);