X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1c959a62ce1aea3b65fd1d642bc3b2de7c5f2111..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/dataview.h diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h index 1acce35939..e45d0fced1 100644 --- a/interface/wx/dataview.h +++ b/interface/wx/dataview.h @@ -183,10 +183,7 @@ public: @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 @@ -376,7 +373,7 @@ public: */ int Compare(const wxDataViewItem& item1, const wxDataViewItem& item2, - unsigned int column, bool ascending); + unsigned int column, bool ascending) const; /** Override this to indicate that the row has special font attributes. @@ -750,7 +747,9 @@ wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP; @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event. @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)} - Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. This event + is triggered by double clicking an item or pressing some special key + (usually "Enter") when it is focused. @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)} 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 @@ -776,7 +775,7 @@ wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP; 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. + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event. @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event. @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)} @@ -791,6 +790,11 @@ wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP; Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event. @endEventTable + Notice that this control doesn't allow to process generic mouse events such + as @c wxEVT_LEFT_DOWN in all ports (notably it doesn't work in wxGTK). If + you need to handle any mouse events not covered by the ones above, consider + using a custom renderer for the cells that must handle them. + @library{wxadv} @category{ctrl,dvc} @appearance{dataviewctrl.png} @@ -1000,6 +1004,17 @@ public: */ 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. */ @@ -1063,19 +1078,45 @@ public: 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; @@ -1201,14 +1242,6 @@ public: */ virtual void SetSelections(const wxDataViewItemArray& sel); - /** - Programmatically starts editing the given item on the given column. - Currently not implemented on wxOSX Carbon. - @since 2.9.2 - */ - - virtual void StartEditor(const wxDataViewItem & item, unsigned int column); - /** Unselect the given item. */ @@ -1664,12 +1697,15 @@ public: /** - @class wxDataViewChoiceRenderer + A wxDataViewCtrl renderer using wxChoice control and values of strings in + it. 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. + @see wxDataViewChoiceByIndexRenderer + @library{wxadv} @category{dvc} */ @@ -1688,7 +1724,7 @@ public: Returns the choice referred to by index. */ wxString GetChoice(size_t index) const; - + /** Returns all choices. */ @@ -1696,6 +1732,28 @@ public: }; +/** + A wxDataViewCtrl renderer using wxChoice control and indexes into it. + + Unlike its base wxDataViewChoiceRenderer class, this one stores the choice + index, i.e. an @c int, in the variant used by its SetValue() and + GetValue(). + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewChoiceByIndexRenderer : public wxDataViewChoiceRenderer +{ +public: + /** + The ctor. + */ + wxDataViewChoiceByIndexRenderer( const wxArrayString &choices, + wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, + int alignment = wxDVR_DEFAULT_ALIGNMENT ); +}; + + /** @class wxDataViewDateRenderer @@ -2169,7 +2227,7 @@ public: Appends a column to the control and additionally appends a column to the store with the type string. */ - virtual void AppendColumn( wxDataViewColumn *column ); + virtual bool AppendColumn( wxDataViewColumn *column ); /** Appends a column to the control and additionally appends a @@ -2225,7 +2283,7 @@ public: Inserts a column to the control and additionally inserts a column to the store with the type string. */ - virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column ); + virtual bool InsertColumn( unsigned int pos, wxDataViewColumn *column ); /** Inserts a column to the control and additionally inserts a @@ -2238,7 +2296,7 @@ public: Prepends a column to the control and additionally prepends a column to the store with the type string. */ - virtual void PrependColumn( wxDataViewColumn *column ); + virtual bool PrependColumn( wxDataViewColumn *column ); /** Prepends a column to the control and additionally prepends a @@ -2257,17 +2315,17 @@ public: /** Appends an item (=row) to the control and store. */ - void AppendItem( const wxVector &values, wxClientData *data = NULL ); + void AppendItem( const wxVector &values, wxUIntPtr data = NULL ); /** Prepends an item (=row) to the control and store. */ - void PrependItem( const wxVector &values, wxClientData *data = NULL ); + void PrependItem( const wxVector &values, wxUIntPtr data = NULL ); /** Inserts an item (=row) to the control and store. */ - void InsertItem( unsigned int row, const wxVector &values, wxClientData *data = NULL ); + void InsertItem( unsigned int row, const wxVector &values, wxUIntPtr data = NULL ); /** Delete the row at position @a row. @@ -2279,6 +2337,22 @@ public: */ void DeleteAllItems(); + /** + Returns the number of items (=rows) in the control + + @since 2.9.4 + */ + unsigned int GetItemCount() const; + + /** + Returns the client data associated with the item. + + @see SetItemData() + + @since 2.9.4 + */ + wxUIntPtr GetItemData(const wxDataViewItem& item) const; + /** Sets the value in the store and update the control. */ @@ -2321,6 +2395,19 @@ public: */ bool GetToggleValue( unsigned int row, unsigned int col ) const; + /** + Associates a client data pointer with the given item. + + Notice that the control does @e not take ownership of the pointer for + compatibility with wxListCtrl. I.e. it will @e not delete the pointer + (if it is a pointer and not a number) itself, it is up to you to do it. + + @see GetItemData() + + @since 2.9.4 + */ + void SetItemData(const wxDataViewItem& item, wxUIntPtr data); + //@} }; @@ -2600,7 +2687,7 @@ public: in number and type. No (default) values are filled in automatically. */ - void AppendItem( const wxVector &values, wxClientData *data = NULL ); + void AppendItem( const wxVector &values, wxUIntPtr data = NULL ); /** Prepends an item (=row) and fills it with @a values. @@ -2609,7 +2696,7 @@ public: in number and type. No (default) values are filled in automatically. */ - void PrependItem( const wxVector &values, wxClientData *data = NULL ); + void PrependItem( const wxVector &values, wxUIntPtr data = NULL ); /** Inserts an item (=row) and fills it with @a values. @@ -2618,7 +2705,7 @@ public: in number and type. No (default) values are filled in automatically. */ - void InsertItem( unsigned int row, const wxVector &values, wxClientData *data = NULL ); + void InsertItem( unsigned int row, const wxVector &values, wxUIntPtr data = NULL ); /** Delete the item (=row) at position @a pos. @@ -2630,6 +2717,22 @@ public: */ void DeleteAllItems(); + /** + Returns the number of items (=rows) in the control + + @since 2.9.4 + */ + unsigned int GetItemCount() const; + + /** + Returns the client data associated with the item. + + @see SetItemData() + + @since 2.9.4 + */ + wxUIntPtr GetItemData(const wxDataViewItem& item) const; + /** Overridden from wxDataViewModel */ @@ -2640,6 +2743,18 @@ public: */ virtual wxString GetColumnType( unsigned int col ) const; + /** + Sets the client data associated with the item. + + Notice that this class does @e not take ownership of the passed in + pointer and will not delete it. + + @see GetItemData() + + @since 2.9.4 + */ + void SetItemData(const wxDataViewItem& item, wxUIntPtr data); + /** Overridden from wxDataViewIndexListModel */ @@ -2869,13 +2984,15 @@ public: @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event. @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)} - Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event. + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event. @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event. @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event. @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event. + Currently this even is only generated when using the native OSX + version. @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event. @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)} @@ -2951,7 +3068,7 @@ public: void SetColumn(int col); /** - For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. + For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK only. */ void SetDataViewColumn(wxDataViewColumn* col); @@ -2970,41 +3087,55 @@ public: */ void SetDataObject( wxDataObject *obj ); - /** - Used internally. Gets associated wxDataObject for data transfer - within a drag operation. - */ - wxDataObject *GetDataObject() const; - - /** - Used internally. Sets the wxDataFormat during a drop operation. - */ - void SetDataFormat( const wxDataFormat &format ); - /** Gets the wxDataFormat during a drop operation. */ wxDataFormat GetDataFormat() const; /** - Used internally. Sets the data size for a drop data transfer. + Gets the data size for a drop data transfer. */ - void SetDataSize( size_t size ); + size_t GetDataSize() const; /** - Gets the data size for a drop data transfer. + Gets the data buffer for a drop data transfer. */ - size_t GetDataSize() const; + void *GetDataBuffer() const; /** - Used internally. Sets the data buffer for a drop data transfer. + Specify the kind of the drag operation to perform. + + This method can be used inside a wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG + handler in order to configure the drag operation. Valid values are + ::wxDrag_CopyOnly (default), ::wxDrag_AllowMove (allow the data to be + moved) and ::wxDrag_DefaultMove. + + Currently it is only honoured by the generic version of wxDataViewCtrl + (used e.g. under MSW) and not supported by the native GTK and OS X + versions. + + @see GetDropEffect() + + @since 2.9.4 */ - void SetDataBuffer( void* buf ); + void SetDragFlags(int flags); /** - Gets the data buffer for a drop data transfer. + Returns the effect the user requested to happen to the dropped data. + + This function can be used inside + wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE and + wxEVT_COMMAND_DATAVIEW_ITEM_DROP handlers and returns whether the user + is trying to copy (the return value is ::wxDragCopy) or move (if the + return value is ::wxDragMove) the data. + + Currently this is only available when using the generic version of + wxDataViewCtrl (used e.g. under MSW) and always returns ::wxDragNone in + the GTK and OS X native versions. + + @since 2.9.4 */ - void *GetDataBuffer() const; + wxDragResult GetDropEffect() const; /** Return the first row that will be displayed.