// Name: manager.h
// Purpose: interface of wxPropertyGridManager
// Author: wxWidgets team
-// RCS-ID: $Id:
+// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
manipulation functions found in wxPropertyGridManager. Please use
parent manager (m_manager member variable) when needed.
- Please note that most member functions are inherited and as such not documented on
- this page. This means you will probably also want to read wxPropertyGridInterface
- class reference.
+ Please note that most member functions are inherited and as such not
+ documented on this page. This means you will probably also want to read
+ wxPropertyGridInterface class reference.
@section propgridpage_event_handling Event Handling
wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but
- only those events that are specific to that page. If wxPropertyGridPage::IsHandlingAllEvents
- returns false, then unhandled events are sent to the manager's parent, as usual.
+ only those events that are specific to that page. If wxPropertyGridPage::
+ IsHandlingAllEvents returns false, then unhandled events are sent to the
+ manager's parent, as usual.
See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
for more information.
wxPropertyGridPage();
virtual ~wxPropertyGridPage();
- /** Deletes all properties on page.
+ /**
+ Deletes all properties on page.
*/
virtual void Clear();
- /** Reduces column sizes to minimum possible that contents are still visibly (naturally
- some margin space will be applied as well).
+ /**
+ Reduces column sizes to minimum possible that contents are still visibly
+ (naturally some margin space will be applied as well).
- @retval
- Minimum size for the page to still display everything.
+ @return Returns minimum size for the page to still display everything.
- @remarks
- This function only works properly if size of containing grid was already fairly large.
+ @remarks This function only works properly if size of containing grid was
+ already fairly large.
- Note that you can also get calculated column widths by calling GetColumnWidth()
- immediately after this function returns.
+ Note that you can also get calculated column widths by calling
+ GetColumnWidth() immediately after this function returns.
*/
wxSize FitColumns();
- /** Returns page index in manager;
+ /**
+ Returns page index in manager;
*/
inline int GetIndex() const;
- /** Returns x-coordinate position of splitter on a page.
+ /**
+ Returns "root property". It does not have name, etc. and it is not
+ visible. It is only useful for accessing its children.
*/
- int GetSplitterPosition( int col = 0 ) const { return GetStatePtr()->DoGetSplitterPosition(col); }
+ wxPGProperty* GetRoot() const;
- /** Returns "root property". It does not have name, etc. and it is not
- visible. It is only useful for accessing its children.
+ /**
+ Returns x-coordinate position of splitter on a page.
*/
- wxPGProperty* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
+ int GetSplitterPosition( int col = 0 ) const;
- /** Returns id of the tool bar item that represents this page on wxPropertyGridManager's wxToolBar.
+ /**
+ Returns id of the tool bar item that represents this page on
+ wxPropertyGridManager's wxToolBar.
*/
int GetToolId() const
{
return m_id;
}
- /** Do any member initialization in this method.
- @remarks
- - Called every time the page is added into a manager.
- - You can add properties to the page here.
+ /**
+ Do any member initialization in this method.
+
+ @remarks - Called every time the page is added into a manager.
+ - You can add properties to the page here.
*/
virtual void Init() {}
- /** Return false here to indicate unhandled events should be
+ /**
+ Return false here to indicate unhandled events should be
propagated to manager's parent, as normal.
*/
virtual bool IsHandlingAllEvents() const { return true; }
- /** Called every time page is about to be shown.
+ /**
+ Called every time page is about to be shown.
Useful, for instance, creating properties just-in-time.
*/
virtual void OnShow();
+ /**
+ Refreshes given property on page.
+ */
virtual void RefreshProperty( wxPGProperty* p );
/** Sets splitter position on page.
@remarks
- Splitter position cannot exceed grid size, and therefore setting it during
- form creation may fail as initial grid size is often smaller than desired
- splitter position, especially when sizers are being used.
+ Splitter position cannot exceed grid size, and therefore setting it
+ during form creation may fail as initial grid size is often smaller than
+ desired splitter position, especially when sizers are being used.
*/
void SetSplitterPosition( int splitterPos, int col = 0 );
};
properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some
(eg. Append()) only apply to the currently selected page.
- To operate explicitly on properties on specific page, use wxPropertyGridManager::GetPage()
- to obtain pointer to page's wxPropertyGridPage object.
+ To operate explicitly on properties on specific page, use
+ wxPropertyGridManager::GetPage() to obtain pointer to page's
+ wxPropertyGridPage object.
Visual methods, such as SetCellBackgroundColour() are only available in
wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain pointer to it.
wxPropertyGridPage* page;
- // Adding a page sets target page to the one added, so
- // we don't have to call SetTargetPage if we are filling
- // it right after adding.
- pgMan->AddPage(wxT("First Page"));
- page = pgMan->GetLastPage();
+ page = pgMan->AddPage(wxT("First Page"));
page->Append( new wxPropertyCategory(wxT("Category A1")) );
page->Append( new wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
- pgMan->AddPage(wxT("Second Page"));
- page = pgMan->GetLastPage();
+ page = pgMan->AddPage(wxT("Second Page"));
page->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
class wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
{
public:
- /** Creates new property page. Note that the first page is not created
+ /**
+ Creates new property page. Note that the first page is not created
automatically.
+
@param label
- A label for the page. This may be shown as a toolbar tooltip etc.
+ A label for the page. This may be shown as a toolbar tooltip etc.
+
@param bmp
- Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
- default image is used.
+ Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
+ default image is used.
+
@param pageObj
- wxPropertyGridPage instance. Manager will take ownership of this object.
- NULL indicates that a default page instance should be created.
- @retval
- Returns index to the page created.
- @remarks
- If toolbar is used, it is highly recommended that the pages are
- added when the toolbar is not turned off using window style flag
- switching.
- */
- int AddPage( const wxString& label = wxEmptyString,
- const wxBitmap& bmp = wxPG_NULL_BITMAP,
- wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL )
- {
- return InsertPage(-1,label,bmp,pageObj);
- }
+ wxPropertyGridPage instance. Manager will take ownership of this
+ object. NULL indicates that a default page instance should be created.
- void ClearModifiedStatus ( wxPGPropArg id );
+ @return Returns pointer to created property grid page.
- void ClearModifiedStatus ()
- {
- m_pPropGrid->ClearModifiedStatus();
- }
+ @remarks If toolbar is used, it is highly recommended that the pages are
+ added when the toolbar is not turned off using window style flag
+ switching. Otherwise toolbar buttons might not be added properly.
+ */
+ wxPropertyGridPage* AddPage( const wxString& label = wxEmptyString,
+ const wxBitmap& bmp = wxPG_NULL_BITMAP,
+ wxPropertyGridPage* pageObj = NULL );
- /** Deletes all all properties and all pages.
+ /**
+ Deletes all properties and all pages.
*/
virtual void Clear();
- /** Deletes all properties on given page.
+ /**
+ Deletes all properties on given page.
*/
void ClearPage( int page );
- /** Forces updating the value of property from the editor control.
- Returns true if DoPropertyChanged was actually called.
+ /**
+ Forces updating the value of property from the editor control.
+
+ @return Returns @true if value was actually updated.
*/
bool CommitChangesFromEditor( wxUint32 flags = 0 )
{
return m_pPropGrid->CommitChangesFromEditor(flags);
}
- /** Two step creation. Whenever the control is created without any parameters,
+ /**
+ Two step creation. Whenever the control is created without any parameters,
use Create to actually create it. Don't access the control's public methods
before this is called.
- @sa @link wndflags Additional Window Styles@endlink
+
+ @see @ref propgrid_window_styles
*/
bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition,
long style = wxPGMAN_DEFAULT_STYLE,
const wxChar* name = wxPropertyGridManagerNameStr );
- /** Enables or disables (shows/hides) categories according to parameter enable.
- WARNING: Not tested properly, use at your own risk.
+ /**
+ Enables or disables (shows/hides) categories according to parameter enable.
+
+ @remarks
+ Calling his may not properly update toolbar buttons.
*/
bool EnableCategories( bool enable )
{
return true;
}
- /** Selects page, scrolls and/or expands items to ensure that the
- given item is visible. Returns true if something was actually done.
+ /**
+ Selects page, scrolls and/or expands items to ensure that the
+ given item is visible.
+
+ @return Returns @true if something was actually done.
*/
bool EnsureVisible( wxPGPropArg id );
- /** Returns number of children of the root property of the selected page. */
- size_t GetChildrenCount()
- {
- return GetChildrenCount( m_pPropGrid->m_pState->m_properties );
- }
-
- /** Returns number of children of the root property of given page. */
- size_t GetChildrenCount( int pageIndex );
-
- /** Returns number of children for the property.
-
- NB: Cannot be in container methods class due to name hiding.
+ /**
+ Returns number of columns on given page. By the default,
+ returns number of columns on current page.
*/
- size_t GetChildrenCount( wxPGPropArg id ) const
- {
- wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
- return p->GetChildCount();
- }
-
- /** Returns number of columns on given page. By the default,
- returns number of columns on current page. */
int GetColumnCount( int page = -1 ) const;
- /** Returns height of the description text box. */
+ /**
+ Returns height of the description text box.
+ */
int GetDescBoxHeight() const;
- /** Returns pointer to the contained wxPropertyGrid. This does not change
+ /**
+ Returns pointer to the contained wxPropertyGrid. This does not change
after wxPropertyGridManager has been created, so you can safely obtain
- pointer once and use it for the entire lifetime of the instance.
+ pointer once and use it for the entire lifetime of the manager
+ instance.
*/
- wxPropertyGrid* GetGrid()
- {
- wxASSERT(m_pPropGrid);
- return m_pPropGrid;
- };
+ wxPropertyGrid* GetGrid();
- const wxPropertyGrid* GetGrid() const
- {
- wxASSERT(m_pPropGrid);
- return (const wxPropertyGrid*)m_pPropGrid;
- };
-
- /** Returns iterator class instance.
- @remarks
- Calling this method in wxPropertyGridManager causes run-time assertion failure.
- Please only iterate through individual pages or use CreateVIterator().
- */
- wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL )
- {
- wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
- return wxPropertyGridInterface::GetIterator( flags, firstProp );
- }
-
- wxPropertyGridConstIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL ) const
- {
- wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
- return wxPropertyGridInterface::GetIterator( flags, firstProp );
- }
-
- /** Returns iterator class instance.
- @remarks
- Calling this method in wxPropertyGridManager causes run-time assertion failure.
- Please only iterate through individual pages or use CreateVIterator().
- */
- wxPropertyGridIterator GetIterator( int flags, int startPos )
- {
- wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
- return wxPropertyGridInterface::GetIterator( flags, startPos );
- }
-
- wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
- {
- wxFAIL_MSG(wxT("Please only iterate through individual pages or use CreateVIterator()"));
- return wxPropertyGridInterface::GetIterator( flags, startPos );
- }
-
- /** Similar to GetIterator, but instead returns wxPGVIterator instance,
+ /**
+ Similar to GetIterator, but instead returns wxPGVIterator instance,
which can be useful for forward-iterating through arbitrary property
containers.
*/
virtual wxPGVIterator GetVIterator( int flags ) const;
- /** Returns currently selected page.
+ /**
+ Returns currently selected page.
*/
- wxPropertyGridPage* GetCurrentPage() const
- {
- return GetPage(m_selPage);
- }
+ wxPropertyGridPage* GetCurrentPage() const;
- /** Returns last page.
- */
- wxPropertyGridPage* GetLastPage() const
- {
- return GetPage(m_arrPages.size()-1);
- }
-
- /** Returns page object for given page index.
+ /**
+ Returns page object for given page index.
*/
wxPropertyGridPage* GetPage( unsigned int ind ) const
{
return (wxPropertyGridPage*)m_arrPages.Item(ind);
}
- /** Returns page object for given page name.
+ /**
+ Returns page object for given page name.
*/
wxPropertyGridPage* GetPage( const wxString& name ) const
{
return GetPage(GetPageByName(name));
}
- /** Returns index for a page name. If no match is found, wxNOT_FOUND is returned. */
+ /**
+ Returns index for a page name. If no match is found, wxNOT_FOUND is
+ returned.
+ */
int GetPageByName( const wxString& name ) const;
- /** Returns number of managed pages. */
+ /**
+ Returns number of managed pages.
+ */
size_t GetPageCount() const;
/** Returns name of given page. */
const wxString& GetPageName( int index ) const;
- /** Returns "root property" of the given page. It does not have name, etc.
+ /**
+ Returns "root property" of the given page. It does not have name, etc.
and it is not visible. It is only useful for accessing its children.
*/
wxPGProperty* GetPageRoot( int index ) const;
/** Synonyme for GetSelectedPage. */
int GetSelection() const { return m_selPage; }
- /** Returns a pointer to the toolbar currently associated with the
- wxPropertyGridManager (if any). */
+ /**
+ Returns a pointer to the toolbar currently associated with the
+ wxPropertyGridManager (if any).
+ */
wxToolBar* GetToolBar() const { return m_pToolbar; }
/** Creates new property page. Note that the first page is not created
automatically.
+
@param index
- Add to this position. -1 will add as the last item.
+ Add to this position. -1 will add as the last item.
+
@param label
- A label for the page. This may be shown as a toolbar tooltip etc.
+ A label for the page. This may be shown as a toolbar tooltip etc.
+
@param bmp
- Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
- default image is used.
+ Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
+ default image is used.
+
@param pageObj
- wxPropertyGridPage instance. Manager will take ownership of this object.
- If NULL, default page object is constructed.
- @retval
- Returns index to the page created.
+ wxPropertyGridPage instance. Manager will take ownership of this
+ object. If NULL, default page object is constructed.
+
+ @return Returns pointer to created page.
*/
- virtual int InsertPage( int index, const wxString& label, const wxBitmap& bmp = wxNullBitmap,
- wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL );
+ virtual wxPropertyGridPage* InsertPage( int index, const wxString& label,
+ const wxBitmap& bmp = wxNullBitmap,
+ wxPropertyGridPage* pageObj = NULL );
- /** Returns true if any property on any page has been modified by the user. */
+ /**
+ Returns @true if any property on any page has been modified by the user.
+ */
bool IsAnyModified() const;
- /** Returns true if updating is frozen (ie. Freeze() called but not yet Thaw() ). */
- bool IsFrozen() const { return (m_pPropGrid->m_frozen>0)?true:false; }
+ /**
+ Returns @true if updating is frozen (ie. Freeze() called but not yet
+ Thaw() ).
+ */
+ bool IsFrozen() const;
- /** Returns true if any property on given page has been modified by the user. */
+ /**
+ Returns @true if any property on given page has been modified by the user.
+ */
bool IsPageModified( size_t index ) const;
- virtual void Refresh( bool eraseBackground = true,
- const wxRect* rect = (const wxRect*) NULL );
-
/** Removes a page.
- @retval
- Returns false if it was not possible to remove page in question.
+
+ @return Returns @false if it was not possible to remove page in question.
*/
virtual bool RemovePage( int page );
- /** Select and displays a given page. Also makes it target page for
- insert operations etc.
+ /** Select and displays a given page.
+
@param index
- Index of page being seleced. Can be -1 to select nothing.
+ Index of page being seleced. Can be -1 to select nothing.
*/
void SelectPage( int index );
- /** Select and displays a given page (by label). */
- void SelectPage( const wxString& label )
- {
- int index = GetPageByName(label);
- wxCHECK_RET( index >= 0, wxT("No page with such name") );
- SelectPage( index );
- }
+ /**
+ Select and displays a given page (by label).
+ */
+ void SelectPage( const wxString& label );
/** Select and displays a given page. */
- void SelectPage( wxPropertyGridPage* ptr )
- {
- SelectPage( GetPageByState(ptr) );
- }
+ void SelectPage( wxPropertyGridPage* page );
/** Select a property. */
- bool SelectProperty( wxPGPropArg id, bool focus = false )
- {
- wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
- return p->GetParentState()->DoSelectProperty(p, focus);
- }
+ bool SelectProperty( wxPGPropArg id, bool focus = false );
- /** Sets number of columns on given page (default is current page).
+ /**
+ Sets number of columns on given page (default is current page).
*/
void SetColumnCount( int colCount, int page = -1 );
/** Sets y coordinate of the description box splitter. */
void SetDescBoxHeight( int ht, bool refresh = true );
- /** Sets property attribute for all applicapple properties.
- Be sure to use this method after all properties have been
- added to the grid.
- */
- void SetPropertyAttributeAll( const wxString& name, wxVariant value );
-
/** Moves splitter as left as possible, while still allowing all
labels to be shown in full.
+
@param subProps
- If false, will still allow sub-properties (ie. properties which
- parent is not root or category) to be cropped.
+ If @false, will still allow sub-properties (ie. properties which
+ parent is not root or category) to be cropped.
+
@param allPages
- If true, takes labels on all pages into account.
+ If @true, takes labels on all pages into account.
*/
void SetSplitterLeft( bool subProps = false, bool allPages = true );
GetPage(page)->DoSetSplitterPosition( pos, column );
}
- /** Sets splitter position for all pages.
- @remarks
- Splitter position cannot exceed grid size, and therefore setting it during
- form creation may fail as initial grid size is often smaller than desired
- splitter position, especially when sizers are being used.
+ /**
+ Sets splitter position for all pages.
+
+ @remarks Splitter position cannot exceed grid size, and therefore setting
+ it during form creation may fail as initial grid size is often
+ smaller than desired splitter position, especially when sizers
+ are being used.
*/
void SetSplitterPosition( int pos, int column = 0 );
// Subclassing helpers
//
- /** Creates property grid for the manager. Override to use subclassed
+ /**
+ Creates property grid for the manager. Override to use subclassed
wxPropertyGrid.
*/
virtual wxPropertyGrid* CreatePropertyGrid() const;
-
- virtual void RefreshProperty( wxPGProperty* p );
};
// -----------------------------------------------------------------------
projects / wxWidgets.git / blobdiff