X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2d0d78133612ffdcc4ac498db54813fc38c64a90..9e610e1caf91dee9e074551149e3ae5e08df9c09:/interface/wx/dataview.h diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h index 4e6639b172..bcd05e3cac 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 commited. + 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 @@ -71,10 +74,23 @@ wxDataViewModel *musicModel = new MyMusicModel; m_musicCtrl->AssociateModel( musicModel ); musicModel->DecRef(); // avoid memory leak !! + + // 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} */ @@ -91,6 +107,28 @@ public: */ void AddNotifier(wxDataViewModelNotifier* notifier); + /** + Change the value of the given item and update the control to reflect + it. + + This function simply calls SetValue() and, if it succeeded, + ValueChanged(). + + @since 2.9.1 + + @param variant + The new value. + @param item + The item (row) to update. + @param col + The column to update. + @return + @true if both SetValue() and ValueChanged() returned @true. + */ + bool ChangeValue(const wxVariant& variant, + const wxDataViewItem& item, + unsigned int col); + /** Called to inform the model that all data has been cleared. The control will reread the data from the model again. @@ -113,10 +151,45 @@ public: Override this to indicate that the item has special font attributes. This only affects the wxDataViewTextRendererText renderer. + The base class version always simply returns @false. + @see wxDataViewItemAttr. + + @param item + The item for which the attribute is requested. + @param col + The column of the item for which the attribute is requested. + @param attr + The attribute to be filled in if the function returns @true. + @return + @true if this item has an attribute or @false otherwise. */ virtual bool GetAttr(const wxDataViewItem& item, unsigned int col, - wxDataViewItemAttr& attr); + 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 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. @@ -140,7 +213,7 @@ public: /** Override this to indicate which wxDataViewItem representing the parent - of @a item or an invalid wxDataViewItem if the the root item is + of @a item or an invalid wxDataViewItem if the root item is the parent item. */ virtual wxDataViewItem GetParent(const wxDataViewItem& item) const = 0; @@ -155,7 +228,7 @@ public: /** Override this method to indicate if a container item merely acts as a headline (or for categorisation) or if it also acts a normal item with - entries for futher columns. By default returns @false. + entries for further columns. By default returns @false. */ virtual bool HasContainerColumns(const wxDataViewItem& item) const; @@ -171,6 +244,20 @@ public: */ virtual bool HasDefaultCompare() const; + /** + Return true if there is a value in the given column of this item. + + All normal items have values in all columns but the container items + only show their label in the first column (@a col == 0) by default (but + see HasContainerColumns()). So this function always returns true for + the first column while for the other ones it returns true only if the + item is not a container or HasContainerColumns() was overridden to + return true for it. + + @since 2.9.1 + */ + bool HasValue(const wxDataViewItem& item, unsigned col) const; + /** Override this to indicate of @a item is a container, i.e. if it can have child items. @@ -180,41 +267,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); /** @@ -229,12 +316,17 @@ public: /** This gets called in order to set a value in the data model. + The most common scenario is that the wxDataViewCtrl calls this method after the user changed some data in the view. - Afterwards ValueChanged() has to be called! + This is the function you need to override in your derived class but if + you want to call it, ChangeValue() is usually more convenient as + otherwise you need to manually call ValueChanged() to update the + control itself. */ - virtual bool SetValue(const wxVariant& variant, const wxDataViewItem& item, + virtual bool SetValue(const wxVariant& variant, + const wxDataViewItem& item, unsigned int col) = 0; /** @@ -242,7 +334,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, @@ -259,28 +351,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. @@ -298,10 +379,48 @@ public: Override this to indicate that the row has special font attributes. This only affects the wxDataViewTextRendererText() renderer. + The base class version always simply returns @false. + @see wxDataViewItemAttr. + + @param row + The row for which the attribute is requested. + @param col + The column for which the attribute is requested. + @param attr + The attribute to be filled in if the function returns @true. + @return + @true if this item has an attribute or @false otherwise. */ virtual bool GetAttrByRow(unsigned int row, unsigned int col, - wxDataViewItemAttr& attr); + 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 (or rows) in the list. + */ + unsigned int GetCount() const; /** Returns the wxDataViewItem at the given @e row. @@ -371,6 +490,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 @@ -380,21 +527,22 @@ 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: /** Constructor. */ wxDataViewVirtualListModel(unsigned int initial_size = 0); + }; @@ -429,6 +577,16 @@ public: */ void SetColour(const wxColour& colour); + /** + Call this to set the background colour to use. + + Currently this attribute is only supported in the generic version of + wxDataViewCtrl and ignored by the native GTK+ and OS X implementations. + + @since 2.9.4 + */ + void SetBackgroundColour(const wxColour& colour); + /** Call this to indicate that the item shall be displayed in italic text. */ @@ -441,7 +599,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 @@ -463,8 +621,9 @@ public: /** Constructor. */ - wxDataViewItem(void* id = NULL); + wxDataViewItem(); wxDataViewItem(const wxDataViewItem& item); + explicit wxDataViewItem(void* id); //@} /** @@ -479,6 +638,61 @@ public: }; +// ---------------------------------------------------------------------------- +// wxDataViewCtrl flags +// ---------------------------------------------------------------------------- + +// size of a wxDataViewRenderer without contents: +#define wxDVC_DEFAULT_RENDERER_SIZE 20 + +// the default width of new (text) columns: +#define wxDVC_DEFAULT_WIDTH 80 + +// the default width of new toggle columns: +#define wxDVC_TOGGLE_DEFAULT_WIDTH 30 + +// the default minimal width of the columns: +#define wxDVC_DEFAULT_MINWIDTH 30 + +// The default alignment of wxDataViewRenderers is to take +// the alignment from the column it owns. +#define wxDVR_DEFAULT_ALIGNMENT -1 + +#define wxDV_SINGLE 0x0000 // for convenience +#define wxDV_MULTIPLE 0x0001 // can select multiple items + +#define wxDV_NO_HEADER 0x0002 // column titles not visible +#define wxDV_HORIZ_RULES 0x0004 // light horizontal rules between rows +#define wxDV_VERT_RULES 0x0008 // light vertical rules between columns + +#define wxDV_ROW_LINES 0x0010 // alternating colour in rows +#define wxDV_VARIABLE_LINE_HEIGHT 0x0020 // variable line height + +// events + +wxEventType wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED; + +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED; + +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU; + +wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK; +wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK; +wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED; +wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED; +wxEventType wxEVT_COMMAND_DATAVIEW_CACHE_HINT; + +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE; +wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP; /** @class wxDataViewCtrl @@ -516,6 +730,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} @@ -523,6 +739,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} @@ -531,9 +749,9 @@ public: @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)} - Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. This + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING event. This event can be vetoed in order to prevent editing on an item by item - basis. Still experimental. + basis. @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)} @@ -549,7 +767,11 @@ public: @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event. @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)} - Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event + generated when the user right clicks inside the control. Notice that + this menu is generated even if the click didn't occur on any valid + item, in this case wxDataViewEvent::GetItem() simply returns an + invalid item. @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event. @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} @@ -585,7 +807,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. @@ -766,13 +989,25 @@ 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. */ virtual bool DeleteColumn(wxDataViewColumn* column); + /** + Programmatically starts editing given cell of @a item. + + Doesn't do anything if the item or this column is not editable. + + @note Currently not implemented in wxOSX/Carbon. + + @since 2.9.4 + */ + virtual void EditItem(const wxDataViewItem& item, const wxDataViewColumn *column); + /** Enable drag operations using the given @a format. */ @@ -822,13 +1057,59 @@ 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(), GetCurrentColumn() + + @since 2.9.2 + */ + wxDataViewItem GetCurrentItem() const; + + /** + Returns the column that currently has focus. + + If the focus is set to individual cell within the currently focused + item (as opposed to being on the item as a whole), then this is the + column that the focus is on. + + Returns NULL if no column currently has focus. + + @see GetCurrentItem() + + @since 2.9.4 + */ + wxDataViewColumn *GetCurrentColumn() const; + /** Returns indentation. */ int GetIndent() const; /** - Returns item rect. + Returns item rectangle. + + This method is currently not implemented at all in wxGTK and only + implemented for non-@NULL @a col argument in wxOSX. It is fully + implemented in the generic version of the control. + + @param item + A valid item. + @param col + If non-@NULL, the rectangle returned corresponds to the + intersection of the item with the specified column. If @NULL, the + rectangle spans all the columns. */ virtual wxRect GetItemRect(const wxDataViewItem& item, const wxDataViewColumn* col = NULL) const; @@ -838,13 +1119,35 @@ public: */ wxDataViewModel* GetModel(); + /** + Returns the number of currently selected items. + + This method may be called for both the controls with single and + multiple selections and returns the number of selected item, possibly + 0, in any case. + + @since 2.9.3 + */ + virtual int GetSelectedItemsCount() const; + /** Returns first selected item or an invalid item if none is selected. + + This method may be called for both the controls with single and + multiple selections but returns an invalid item if more than one item + is selected in the latter case, use HasSelection() to determine if + there are any selected items when using multiple selection. */ virtual wxDataViewItem GetSelection() const; /** Fills @a sel with currently selected items and returns their number. + + This method may be called for both the controls with single and + multiple selections. In the single selection case it returns the array + with at most one element in it. + + @see GetSelectedItemsCount() */ virtual int GetSelections(wxDataViewItemArray& sel) const; @@ -854,6 +1157,20 @@ public: */ virtual wxDataViewColumn* GetSortingColumn() const; + /** + Returns true if any items are currently selected. + + This method may be called for both the controls with single and + multiple selections. + + Calling this method is equivalent to calling GetSelectedItemsCount() + and comparing its result with 0 but is more clear and might also be + implemented more efficiently in the future. + + @since 2.9.3 + */ + bool HasSelection() const; + /** Hittest. */ @@ -872,6 +1189,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); @@ -886,7 +1207,26 @@ public: void SetExpanderColumn(wxDataViewColumn* col); /** - Sets the indendation. + 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 indentation. */ void SetIndent(int indent); @@ -905,6 +1245,26 @@ public: This method only has effect if multiple selections are allowed. */ virtual void UnselectAll(); + + /** + Sets the row height. + + This function can only be used when all rows have the same height, i.e. + when wxDV_VARIABLE_LINE_HEIGHT flag is not used. + + Currently this is implemented in the generic and native GTK versions + only and nothing is done (and @false returned) when using OS X port. + + Also notice that this method can only be used to increase the row + height compared with the default one (as determined by the return value + of wxDataViewRenderer::GetSize()), if it is set to a too small value + then the minimum required by the renderers will be used. + + @return @true if the line height was changed or @false otherwise. + + @since 2.9.2 + */ + virtual bool SetRowHeight(int rowHeight); }; @@ -944,34 +1304,46 @@ public: /** Called by owning model. + + @return Always return @true from this function in derived classes. */ virtual bool ItemAdded(const wxDataViewItem& parent, const wxDataViewItem& item) = 0; /** Called by owning model. + + @return Always return @true from this function in derived classes. */ virtual bool ItemChanged(const wxDataViewItem& item) = 0; /** Called by owning model. + + @return Always return @true from this function in derived classes. */ virtual bool ItemDeleted(const wxDataViewItem& parent, const wxDataViewItem& item) = 0; /** Called by owning model. + + @return Always return @true from this function in derived classes. */ virtual bool ItemsAdded(const wxDataViewItem& parent, const wxDataViewItemArray& items); /** Called by owning model. + + @return Always return @true from this function in derived classes. */ virtual bool ItemsChanged(const wxDataViewItemArray& items); /** Called by owning model. + + @return Always return @true from this function in derived classes. */ virtual bool ItemsDeleted(const wxDataViewItem& parent, const wxDataViewItemArray& items); @@ -988,6 +1360,8 @@ public: /** Called by owning model. + + @return Always return @true from this function in derived classes. */ virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0; }; @@ -998,18 +1372,54 @@ public: */ enum wxDataViewCellMode { + /** + The cell only displays information and cannot be manipulated or + otherwise interacted with in any way. + + Note that this doesn't mean that the row being drawn can't be selected, + just that a particular element of it cannot be individually modified. + */ wxDATAVIEW_CELL_INERT, /** - Indicates that the user can double click the cell and something will - happen (e.g. a window for editing a date will pop up). + Indicates that the cell can be @em activated by clicking it or using + keyboard. + + Activating a cell is an alternative to showing inline editor when the + value can be edited in a simple way that doesn't warrant full editor + control. The most typical use of cell activation is toggling the + checkbox in wxDataViewToggleRenderer; others would be e.g. an embedded + volume slider or a five-star rating column. + + The exact means of activating a cell are platform-dependent, but they + are usually similar to those used for inline editing of values. + Typically, a cell would be activated by Space or Enter keys or by left + mouse click. + + @note Do not confuse this with item activation in wxDataViewCtrl + and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is + used for activating the item (or, to put it differently, the + entire row) similarly to analogous messages in wxTreeCtrl and + wxListCtrl, and the effect differs (play a song, open a file + etc.). Cell activation, on the other hand, is all about + interacting with the individual cell. + + @see wxDataViewCustomRenderer::ActivateCell() */ wxDATAVIEW_CELL_ACTIVATABLE, /** - Indicates that the user can edit the data in-place, i.e. an control - will show up after a slow click on the cell. This behaviour is best - known from changing the filename in most file managers etc. + Indicates that the user can edit the data in-place in an inline editor + control that will show up when the user wants to edit the cell. + + A typical example of this behaviour is changing the filename in a file + managers. + + Editing is typically triggered by slowly double-clicking the cell or by + a platform-dependent keyboard shortcut (F2 is typical on Windows, Space + and/or Enter is common elsewhere and supported on Windows too). + + @see wxDataViewCustomRenderer::CreateEditorCtrl() */ wxDATAVIEW_CELL_EDITABLE }; @@ -1039,6 +1449,7 @@ enum wxDataViewCellRenderState - wxDataViewBitmapRenderer, - wxDataViewDateRenderer, - wxDataViewSpinRenderer. + - wxDataViewChoiceRenderer. Additionally, the user can write own renderers by deriving from wxDataViewCustomRenderer. @@ -1060,11 +1471,49 @@ public: wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, int align = wxDVR_DEFAULT_ALIGNMENT ); + /** + Enable or disable replacing parts of the item text with ellipsis to + make it fit the column width. + + This method only makes sense for the renderers working with text, such + as wxDataViewTextRenderer or wxDataViewIconTextRenderer. + + By default wxELLIPSIZE_MIDDLE is used. + + @param mode + Ellipsization mode, use wxELLIPSIZE_NONE to disable. + + @since 2.9.1 + */ + void EnableEllipsize(wxEllipsizeMode mode = wxELLIPSIZE_MIDDLE); + + /** + Disable replacing parts of the item text with ellipsis. + + If ellipsizing is disabled, the string will be truncated if it doesn't + fit. + + This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode. + + @since 2.9.1 + */ + void DisableEllipsize(); + /** Returns the alignment. See SetAlignment() */ virtual int GetAlignment() const; + /** + Returns the ellipsize mode used by the renderer. + + If the return value is wxELLIPSIZE_NONE, the text is simply truncated + if it doesn't fit. + + @see EnableEllipsize() + */ + wxEllipsizeMode GetEllipsizeMode() const; + /** Returns the cell mode. */ @@ -1155,8 +1604,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} @@ -1240,6 +1689,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 @@ -1297,20 +1778,72 @@ public: virtual ~wxDataViewCustomRenderer(); /** - Override this to react to double clicks or ENTER. - This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode. - */ - virtual bool Activate( wxRect cell, - wxDataViewModel* model, - const wxDataViewItem & item, - unsigned int col ); + Override this to react to cell @em activation. Activating a cell is an + alternative to showing inline editor when the value can be edited in a + simple way that doesn't warrant full editor control. The most typical + use of cell activation is toggling the checkbox in + wxDataViewToggleRenderer; others would be e.g. an embedded volume + slider or a five-star rating column. + + The exact means of activating a cell are platform-dependent, but they + are usually similar to those used for inline editing of values. + Typically, a cell would be activated by Space or Enter keys or by left + mouse click. + + This method will only be called if the cell has the + wxDATAVIEW_CELL_ACTIVATABLE mode. + + @param cell + Coordinates of the activated cell's area. + @param model + The model to manipulate in response. + @param item + Activated item. + @param col + Activated column of @a item. + @param mouseEvent + If the activation was triggered by mouse click, contains the + corresponding event. Is @NULL otherwise (for keyboard activation). + Mouse coordinates are adjusted to be relative to the cell. + + @since 2.9.3 + + @note Do not confuse this method with item activation in wxDataViewCtrl + and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is + used for activating the item (or, to put it differently, the + entire row) similarly to analogous messages in wxTreeCtrl and + wxListCtrl, and the effect differs (play a song, open a file + etc.). Cell activation, on the other hand, is all about + interacting with the individual cell. + + @see CreateEditorCtrl() + */ + virtual bool ActivateCell(const wxRect& cell, + wxDataViewModel* model, + const wxDataViewItem & item, + unsigned int col, + const wxMouseEvent *mouseEvent); /** Override this to create the actual editor control once editing is about to start. - @a parent is the parent of the editor control, @a labelRect indicates the - position and size of the editor control and @a value is its initial value: + This method will only be called if the cell has the + wxDATAVIEW_CELL_EDITABLE mode. Editing is typically triggered by slowly + double-clicking the cell or by a platform-dependent keyboard shortcut + (F2 is typical on Windows, Space and/or Enter is common elsewhere and + supported on Windows too). + + @param parent + The parent of the editor control. + @param labelRect + Indicates the position and size of the editor control. The control + should be created in place of the cell and @a labelRect should be + respected as much as possible. + @param value + Initial value of the editor. + + An example: @code { long l = value; @@ -1318,15 +1851,28 @@ public: labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l ); } @endcode + + @see ActivateCell() */ - virtual wxControl* CreateEditorCtrl(wxWindow* parent, - wxRect labelRect, - const wxVariant& value); + virtual wxWindow* CreateEditorCtrl(wxWindow* parent, + wxRect labelRect, + 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. @@ -1334,7 +1880,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 { @@ -1345,7 +1891,7 @@ public: } @endcode */ - virtual bool GetValueFromEditorCtrl(wxControl* editor, + virtual bool GetValueFromEditorCtrl(wxWindow* editor, wxVariant& value); /** @@ -1355,11 +1901,11 @@ 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, - wxRect cell, + virtual bool LeftClick( const wxPoint& cursor, + const wxRect& cell, wxDataViewModel * model, const wxDataViewItem & item, unsigned int col ); @@ -1381,9 +1927,10 @@ 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, + virtual bool StartDrag(const wxPoint& cursor, + const wxRect& cell, wxDataViewModel* model, const wxDataViewItem & item, unsigned int col); @@ -1532,11 +2079,11 @@ public: data.push_back( wxVariant("row 3") ); listctrl->AppendItem( data ); @endcode - + @beginStyleTable See wxDataViewCtrl for the list of supported styles. @endStyleTable - + @beginEventEmissionTable See wxDataViewCtrl for the list of events emitted by this class. @endEventTable @@ -1581,11 +2128,69 @@ 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 */ //@{ - + /** Appends a column to the control and additionally appends a column to the store with the type string. @@ -1600,24 +2205,24 @@ public: /** Appends a text column to the control and the store. - + See wxDataViewColumn::wxDataViewColumn for more info about the parameters. */ wxDataViewColumn *AppendTextColumn( const wxString &label, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, wxAlignment align = wxALIGN_LEFT, + int width = -1, wxAlignment align = wxALIGN_LEFT, int flags = wxDATAVIEW_COL_RESIZABLE ); /** Appends a toggle column to the control and the store. - + See wxDataViewColumn::wxDataViewColumn for more info about the parameters. */ wxDataViewColumn *AppendToggleColumn( const wxString &label, wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, - int width = -1, wxAlignment align = wxALIGN_LEFT, + int width = -1, wxAlignment align = wxALIGN_LEFT, int flags = wxDATAVIEW_COL_RESIZABLE ); /** @@ -1628,7 +2233,7 @@ public: */ wxDataViewColumn *AppendProgressColumn( const wxString &label, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, wxAlignment align = wxALIGN_LEFT, + int width = -1, wxAlignment align = wxALIGN_LEFT, int flags = wxDATAVIEW_COL_RESIZABLE ); /** @@ -1639,7 +2244,7 @@ public: */ wxDataViewColumn *AppendIconTextColumn( const wxString &label, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, wxAlignment align = wxALIGN_LEFT, + int width = -1, wxAlignment align = wxALIGN_LEFT, int flags = wxDATAVIEW_COL_RESIZABLE ); /** @@ -1652,7 +2257,7 @@ public: Inserts a column to the control and additionally inserts a column to the list store with the type @a varianttype. */ - void InsertColumn( unsigned int pos, wxDataViewColumn *column, + void InsertColumn( unsigned int pos, wxDataViewColumn *column, const wxString &varianttype ); /** @@ -1668,13 +2273,13 @@ public: void PrependColumn( wxDataViewColumn *column, const wxString &varianttype ); //@} - - + + /** @name Item management functions */ //@{ - + /** Appends an item (=row) to the control and store. */ @@ -1713,7 +2318,7 @@ public: /** Sets the value in the store and update the control. - This method assumes that the a string is stored in respective + This method assumes that the string is stored in respective column. */ void SetTextValue( const wxString &value, unsigned int row, unsigned int col ); @@ -1721,7 +2326,7 @@ public: /** Returns the value from the store. - This method assumes that the a string is stored in respective + This method assumes that the string is stored in respective column. */ wxString GetTextValue( unsigned int row, unsigned int col ) const; @@ -1729,7 +2334,7 @@ public: /** Sets the value in the store and update the control. - This method assumes that the a boolean value is stored in + This method assumes that the boolean value is stored in respective column. */ void SetToggleValue( bool value, unsigned int row, unsigned int col ); @@ -1737,11 +2342,11 @@ public: /** Returns the value from the store. - This method assumes that the a boolean value is stored in + This method assumes that the boolean value is stored in respective column. */ bool GetToggleValue( unsigned int row, unsigned int col ) const; - + //@} }; @@ -1753,13 +2358,13 @@ public: and forwards most of its API to that class. Additionally, it uses a wxImageList to store a list of icons. - The main purpose of this class is to represent a possible replacement for - wxTreeCtrl. + The main purpose of this class is to provide a simple upgrade path for code + using wxTreeCtrl. @beginStyleTable See wxDataViewCtrl for the list of supported styles. @endStyleTable - + @beginEventEmissionTable See wxDataViewCtrl for the list of events emitted by this class. @endEventTable @@ -1777,12 +2382,14 @@ public: wxDataViewTreeCtrl(); /** - Constructor. Calls Create(). + Constructor. + + Calls Create(). */ wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxDV_NO_HEADER, + long style = wxDV_NO_HEADER | wxDV_ROW_LINES, const wxValidator& validator = wxDefaultValidator); /** @@ -1809,11 +2416,14 @@ public: /** Creates the control and a wxDataViewTreeStore as its internal model. + + The default tree column created by this method is an editable column + using wxDataViewIconTextRenderer as its renderer. */ bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxDV_NO_HEADER, + long style = wxDV_NO_HEADER | wxDV_ROW_LINES, const wxValidator& validator = wxDefaultValidator); /** @@ -1896,6 +2506,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. @@ -2042,23 +2657,23 @@ public: void DeleteAllItems(); /** - Overriden from wxDataViewModel + Overridden from wxDataViewModel */ virtual unsigned int GetColumnCount() const; /** - Overriden from wxDataViewModel + Overridden from wxDataViewModel */ virtual wxString GetColumnType( unsigned int col ) const; /** - Overriden from wxDataViewIndexListModel + Overridden from wxDataViewIndexListModel */ virtual void GetValueByRow( wxVariant &value, unsigned int row, unsigned int col ) const; /** - Overriden from wxDataViewIndexListModel + Overridden from wxDataViewIndexListModel */ virtual bool SetValueByRow( const wxVariant &value, unsigned int row, unsigned int col ); @@ -2068,7 +2683,7 @@ public: /** @class wxDataViewTreeStore - wxDataViewTreeStore is a specialised wxDataViewModel for stroing simple + wxDataViewTreeStore is a specialised wxDataViewModel for storing simple trees very much like wxTreeCtrl does and it offers a similar API. This class actually stores the entire tree and the values (therefore its name) @@ -2130,7 +2745,7 @@ public: int GetChildCount(const wxDataViewItem& parent) const; /** - Returns the client data asoociated with the item. + Returns the client data associated with the item. */ wxClientData* GetItemData(const wxDataViewItem& item) const; @@ -2296,7 +2911,7 @@ public: @event{EVT_DATAVIEW_CACHE_HINT(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event. @endEventTable - + @library{wxadv} @category{events,dvc} */ @@ -2327,7 +2942,7 @@ public: wxDataViewModel* GetModel() const; /** - Returns a the position of a context menu event in screen coordinates. + Returns the position of a context menu event in screen coordinates. */ wxPoint GetPosition() const; @@ -2336,13 +2951,33 @@ public: */ const wxVariant& GetValue() const; + /** + Can be used to determine whether the new value is going to be accepted + in wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE handler. + + Returns @true if editing the item was cancelled or if the user tried to + enter an invalid value (refused by wxDataViewRenderer::Validate()). If + this method returns @false, it means that the value in the model is + about to be changed to the new one. + + Notice that wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event handler can + call wxNotifyEvent::Veto() to prevent this from happening. + + Currently support for setting this field and for vetoing the change is + only available in the generic version of wxDataViewCtrl, i.e. under MSW + but not GTK nor OS X. + + @since 2.9.3 + */ + bool IsEditCancelled() const; + /** Sets the column index associated with this event. */ void SetColumn(int col); /** - For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. + For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. */ void SetDataViewColumn(wxDataViewColumn* col);