X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e4e83d3ad627c4a7fb96fb98ff947c1365129a7c..b8737371e220ef1920e6a3d2aed88c4bc2b04daf:/interface/wx/dataview.h diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h index fcdd636a19..4947ed44ed 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. - 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. + 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. + + 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,21 @@ 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 so the control can query the child items of an item. @@ -171,6 +220,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,7 +243,7 @@ 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); /** @@ -189,18 +252,18 @@ public: This will eventually emit a 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); /** @@ -209,12 +272,12 @@ public: This will eventually emit 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 +292,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; /** @@ -298,10 +366,26 @@ 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; + + /** + Returns the number of items (i.e. rows) in the list. + */ + unsigned int GetCount() const; /** Returns the wxDataViewItem at the given @e row. @@ -395,6 +479,11 @@ public: Constructor. */ wxDataViewVirtualListModel(unsigned int initial_size = 0); + + /** + Returns the number of virtual items (i.e. rows) in the list. + */ + unsigned int GetCount() const; }; @@ -441,7 +530,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 @@ -523,6 +612,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} @@ -585,7 +676,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,7 +858,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. @@ -822,6 +915,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. */ @@ -872,6 +985,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); @@ -885,6 +1002,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. */ @@ -1033,13 +1169,13 @@ enum wxDataViewCellRenderState One instance of a renderer class is owned by a wxDataViewColumn. There is a number of ready-to-use renderers provided: - wxDataViewTextRenderer, - - wxDataViewTextRendererAttr, - wxDataViewIconTextRenderer, - wxDataViewToggleRenderer, - wxDataViewProgressRenderer, - wxDataViewBitmapRenderer, - wxDataViewDateRenderer, - wxDataViewSpinRenderer. + - wxDataViewChoiceRenderer. Additionally, the user can write own renderers by deriving from wxDataViewCustomRenderer. @@ -1061,11 +1197,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. */ @@ -1156,8 +1330,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} @@ -1241,48 +1415,56 @@ public: }; - /** - @class wxDataViewDateRenderer + @class wxDataViewChoiceRenderer - This class is used by wxDataViewCtrl to render calendar controls. + 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 wxDataViewDateRenderer : public wxDataViewRenderer + +class wxDataViewChoiceRenderer: public wxDataViewRenderer { public: /** The ctor. */ - wxDataViewDateRenderer(const wxString& varianttype = "datetime", - wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, - int align = wxDVR_DEFAULT_ALIGNMENT); -}; + 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 wxDataViewTextRendererAttr - - The same as wxDataViewTextRenderer but with support for font attributes. - Font attributes are currently only supported under GTK+ and MSW. + @class wxDataViewDateRenderer - @see wxDataViewModel::GetAttr and wxDataViewItemAttr. + This class is used by wxDataViewCtrl to render calendar controls. @library{wxadv} @category{dvc} */ -class wxDataViewTextRendererAttr : public wxDataViewTextRenderer +class wxDataViewDateRenderer : public wxDataViewRenderer { public: /** The ctor. */ - wxDataViewTextRendererAttr(const wxString& varianttype = "string", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT); + wxDataViewDateRenderer(const wxString& varianttype = "datetime", + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int align = wxDVR_DEFAULT_ALIGNMENT); }; @@ -1349,9 +1531,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. @@ -1359,7 +1552,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 { @@ -1380,7 +1573,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, @@ -1406,7 +1599,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, @@ -1557,11 +1750,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 @@ -1606,11 +1799,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. @@ -1625,24 +1876,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 ); /** @@ -1653,7 +1904,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 ); /** @@ -1664,7 +1915,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 ); /** @@ -1677,7 +1928,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 ); /** @@ -1693,13 +1944,13 @@ public: void PrependColumn( wxDataViewColumn *column, const wxString &varianttype ); //@} - - + + /** @name Item management functions */ //@{ - + /** Appends an item (=row) to the control and store. */ @@ -1766,7 +2017,7 @@ public: respective column. */ bool GetToggleValue( unsigned int row, unsigned int col ) const; - + //@} }; @@ -1778,13 +2029,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 @@ -1802,12 +2053,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); /** @@ -1834,11 +2087,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); /** @@ -1921,6 +2177,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. @@ -2318,8 +2579,10 @@ public: Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event. @event{EVT_DATAVIEW_ITEM_DROP(id, func)} Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event. + @event{EVT_DATAVIEW_CACHE_HINT(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event. @endEventTable - + @library{wxadv} @category{events,dvc} */ @@ -2419,5 +2682,15 @@ public: Gets the data buffer for a drop data transfer. */ void *GetDataBuffer() const; + + /** + Return the first row that will be displayed. + */ + int GetCacheFrom() const; + + /** + Return the last row that will be displayed. + */ + int GetCacheTo() const; };