@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
+ @note Currently disabling items is not supported by the wxOSX/Carbon
implementation.
@since 2.9.2
/**
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;
/**
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;
/**
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.
*/
bool ItemChanged(const wxDataViewItem& item);
/**
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.
*/
bool ItemsChanged(const wxDataViewItemArray& items);
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,
unsigned int col) const;
/**
- Returns the number of items (i.e. rows) in the list.
+ Returns the number of items (or rows) in the list.
*/
unsigned int GetCount() const;
*/
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.
*/
/**
Constructor.
*/
- wxDataViewItem(void* id = NULL);
+ wxDataViewItem();
wxDataViewItem(const wxDataViewItem& item);
+ explicit wxDataViewItem(void* id);
//@}
/**
};
+// ----------------------------------------------------------------------------
+// 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
@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)}
@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)}
*/
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.
*/
item may be selected or not but under OS X the current item is always
selected.
- @see SetCurrentItem()
+ @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;
*/
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;
*/
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.
*/
void SetCurrentItem(const wxDataViewItem& item);
/**
- Sets the indendation.
+ Sets the indentation.
*/
void SetIndent(int indent);
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);
};
/**
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);
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
};
*/
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
};
virtual ~wxDataViewCustomRenderer();
/**
- Override this to react to double clicks or ENTER.
- This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
+ 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 Activate( wxRect cell,
- wxDataViewModel* model,
- const wxDataViewItem & item,
- unsigned int col );
+ 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;
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);
/**
Return the attribute to be used for rendering.
}
@endcode
*/
- virtual bool GetValueFromEditorCtrl(wxControl* editor,
+ virtual bool GetValueFromEditorCtrl(wxWindow* editor,
wxVariant& value);
/**
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 );
/**
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);
/**
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 );
/**
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;
/**
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 );
/**
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;
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 );
/**
@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)
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;
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;
*/
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);
projects / wxWidgets.git / blobdiff