Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document revisioning (including more wx-like formatting and internal function removal)

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55822 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Jaakko Salli
2008-09-23 17:37:27 +00:00
parent 24588cd306
commit bb6720bb9e
3 changed files with 730 additions and 765 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
include/wx/propgrid/property.h
View File

@@ -1565,7 +1565,9 @@ public:
/** /**
Determines, recursively, if all children are not unspecified. Determines, recursively, if all children are not unspecified.
Takes values in given list into account. @param pendingList
Assumes members in this wxVariant list as pending
replacement values.
*/ */
bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const; bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
@@ -1579,9 +1581,9 @@ public:
/** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES. /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
*/ */
FlagType UsesAutoUnspecified() const bool UsesAutoUnspecified() const
{ {
return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED); return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED)?true:false;
} }
wxBitmap* GetValueImage() const wxBitmap* GetValueImage() const

362
interface/wx/propgrid/manager.h
View File

@@ -19,15 +19,16 @@
manipulation functions found in wxPropertyGridManager. Please use manipulation functions found in wxPropertyGridManager. Please use
parent manager (m_manager member variable) when needed. parent manager (m_manager member variable) when needed.
Please note that most member functions are inherited and as such not documented on Please note that most member functions are inherited and as such not
this page. This means you will probably also want to read wxPropertyGridInterface documented on this page. This means you will probably also want to read
class reference. wxPropertyGridInterface class reference.
@section propgridpage_event_handling Event Handling @section propgridpage_event_handling Event Handling
wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but wxPropertyGridPage receives events emitted by its wxPropertyGridManager, but
only those events that are specific to that page. If wxPropertyGridPage::IsHandlingAllEvents only those events that are specific to that page. If wxPropertyGridPage::
returns false, then unhandled events are sent to the manager's parent, as usual. IsHandlingAllEvents returns false, then unhandled events are sent to the
manager's parent, as usual.
See @ref propgrid_event_handling "wxPropertyGrid Event Handling" See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
for more information. for more information.
@@ -44,68 +45,80 @@ public:
wxPropertyGridPage(); wxPropertyGridPage();
virtual ~wxPropertyGridPage(); virtual ~wxPropertyGridPage();
/** Deletes all properties on page. /**
Deletes all properties on page.
*/ */
virtual void Clear(); 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 @return Returns minimum size for the page to still display everything.
Minimum size for the page to still display everything.
@remarks @remarks This function only works properly if size of containing grid was
This function only works properly if size of containing grid was already fairly large. already fairly large.
Note that you can also get calculated column widths by calling GetColumnWidth() Note that you can also get calculated column widths by calling
immediately after this function returns. GetColumnWidth() immediately after this function returns.
*/ */
wxSize FitColumns(); wxSize FitColumns();
/** Returns page index in manager; /**
Returns page index in manager;
*/ */
inline int GetIndex() const; 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
int GetSplitterPosition( int col = 0 ) const { return GetStatePtr()->DoGetSplitterPosition(col); }
/** Returns "root property". It does not have name, etc. and it is not
visible. It is only useful for accessing its children. visible. It is only useful for accessing its children.
*/ */
wxPGProperty* GetRoot() const { return GetStatePtr()->DoGetRoot(); } wxPGProperty* GetRoot() const;
/** Returns id of the tool bar item that represents this page on wxPropertyGridManager's wxToolBar. /**
Returns x-coordinate position of splitter on a page.
*/
int GetSplitterPosition( int col = 0 ) const;
/**
Returns id of the tool bar item that represents this page on
wxPropertyGridManager's wxToolBar.
*/ */
int GetToolId() const int GetToolId() const
{ {
return m_id; return m_id;
} }
/** Do any member initialization in this method. /**
@remarks Do any member initialization in this method.
- Called every time the page is added into a manager.
- You can add properties to the page here. @remarks - Called every time the page is added into a manager.
- You can add properties to the page here.
*/ */
virtual void Init() {} 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. propagated to manager's parent, as normal.
*/ */
virtual bool IsHandlingAllEvents() const { return true; } 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. Useful, for instance, creating properties just-in-time.
*/ */
virtual void OnShow(); virtual void OnShow();
/**
Refreshes given property on page.
*/
virtual void RefreshProperty( wxPGProperty* p ); virtual void RefreshProperty( wxPGProperty* p );
/** Sets splitter position on page. /** Sets splitter position on page.
@remarks @remarks
Splitter position cannot exceed grid size, and therefore setting it during Splitter position cannot exceed grid size, and therefore setting it
form creation may fail as initial grid size is often smaller than desired during form creation may fail as initial grid size is often smaller than
splitter position, especially when sizers are being used. desired splitter position, especially when sizers are being used.
*/ */
void SetSplitterPosition( int splitterPos, int col = 0 ); void SetSplitterPosition( int splitterPos, int col = 0 );
}; };
@@ -123,8 +136,9 @@ public:
properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some
(eg. Append()) only apply to the currently selected page. (eg. Append()) only apply to the currently selected page.
To operate explicitly on properties on specific page, use wxPropertyGridManager::GetPage() To operate explicitly on properties on specific page, use
to obtain pointer to page's wxPropertyGridPage object. wxPropertyGridManager::GetPage() to obtain pointer to page's
wxPropertyGridPage object.
Visual methods, such as SetCellBackgroundColour() are only available in Visual methods, such as SetCellBackgroundColour() are only available in
wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain pointer to it. wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain pointer to it.
@@ -191,22 +205,26 @@ public:
class wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface class wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
{ {
public: 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. automatically.
@param label @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 @param bmp
Bitmap image for toolbar. If wxNullBitmap is used, then a built-in Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
default image is used. default image is used.
@param pageObj @param pageObj
wxPropertyGridPage instance. Manager will take ownership of this object. wxPropertyGridPage instance. Manager will take ownership of this
NULL indicates that a default page instance should be created. object. NULL indicates that a default page instance should be created.
@retval
Returns index to the page created. @return Returns index to the page created.
@remarks
If toolbar is used, it is highly recommended that the pages are @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 added when the toolbar is not turned off using window style flag
switching. switching. Otherwise toolbar buttons might not be added properly.
*/ */
int AddPage( const wxString& label = wxEmptyString, int AddPage( const wxString& label = wxEmptyString,
const wxBitmap& bmp = wxPG_NULL_BITMAP, const wxBitmap& bmp = wxPG_NULL_BITMAP,
@@ -215,33 +233,39 @@ public:
return InsertPage(-1,label,bmp,pageObj); return InsertPage(-1,label,bmp,pageObj);
} }
void ClearModifiedStatus ( wxPGPropArg id ); void ClearModifiedStatus( wxPGPropArg id );
void ClearModifiedStatus () void ClearModifiedStatus()
{ {
m_pPropGrid->ClearModifiedStatus(); m_pPropGrid->ClearModifiedStatus();
} }
/** Deletes all all properties and all pages. /**
Deletes all properties and all pages.
*/ */
virtual void Clear(); virtual void Clear();
/** Deletes all properties on given page. /**
Deletes all properties on given page.
*/ */
void ClearPage( int 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 ) bool CommitChangesFromEditor( wxUint32 flags = 0 )
{ {
return m_pPropGrid->CommitChangesFromEditor(flags); 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 use Create to actually create it. Don't access the control's public methods
before this is called. before this is called.
@sa @link wndflags Additional Window Styles@endlink
@see @ref propgrid_window_styles
*/ */
bool Create( wxWindow *parent, wxWindowID id = wxID_ANY, bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition, const wxPoint& pos = wxDefaultPosition,
@@ -249,8 +273,11 @@ public:
long style = wxPGMAN_DEFAULT_STYLE, long style = wxPGMAN_DEFAULT_STYLE,
const wxChar* name = wxPropertyGridManagerNameStr ); 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 ) bool EnableCategories( bool enable )
{ {
@@ -260,21 +287,29 @@ public:
return true; 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 ); bool EnsureVisible( wxPGPropArg id );
/** Returns number of children of the root property of the selected page. */ /**
Returns number of children of the root property of the selected page.
*/
size_t GetChildrenCount() size_t GetChildrenCount()
{ {
return GetChildrenCount( m_pPropGrid->m_pState->m_properties ); return GetChildrenCount( m_pPropGrid->m_pState->m_properties );
} }
/** Returns number of children of the root property of given page. */ /**
Returns number of children of the root property of given page.
*/
size_t GetChildrenCount( int pageIndex ); size_t GetChildrenCount( int pageIndex );
/** Returns number of children for the property. /**
Returns number of children for the property.
NB: Cannot be in container methods class due to name hiding. NB: Cannot be in container methods class due to name hiding.
*/ */
@@ -284,107 +319,77 @@ public:
return p->GetChildCount(); return p->GetChildCount();
} }
/** Returns number of columns on given page. By the default, /**
returns number of columns on current page. */ Returns number of columns on given page. By the default,
returns number of columns on current page.
*/
int GetColumnCount( int page = -1 ) const; int GetColumnCount( int page = -1 ) const;
/** Returns height of the description text box. */ /**
Returns height of the description text box.
*/
int GetDescBoxHeight() const; 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 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() wxPropertyGrid* GetGrid();
{
wxASSERT(m_pPropGrid);
return m_pPropGrid;
};
const wxPropertyGrid* GetGrid() const /**
{ Similar to GetIterator, but instead returns wxPGVIterator instance,
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,
which can be useful for forward-iterating through arbitrary property which can be useful for forward-iterating through arbitrary property
containers. containers.
*/ */
virtual wxPGVIterator GetVIterator( int flags ) const; virtual wxPGVIterator GetVIterator( int flags ) const;
/** Returns currently selected page. /**
Returns currently selected page.
*/ */
wxPropertyGridPage* GetCurrentPage() const wxPropertyGridPage* GetCurrentPage() const;
{
return GetPage(m_selPage);
}
/** Returns last page. /**
Returns last page.
*/ */
wxPropertyGridPage* GetLastPage() const wxPropertyGridPage* GetLastPage() const
{ {
return GetPage(m_arrPages.size()-1); 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 wxPropertyGridPage* GetPage( unsigned int ind ) const
{ {
return (wxPropertyGridPage*)m_arrPages.Item(ind); 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 wxPropertyGridPage* GetPage( const wxString& name ) const
{ {
return GetPage(GetPageByName(name)); 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; int GetPageByName( const wxString& name ) const;
/** Returns number of managed pages. */ /**
Returns number of managed pages.
*/
size_t GetPageCount() const; size_t GetPageCount() const;
/** Returns name of given page. */ /** Returns name of given page. */
const wxString& GetPageName( int index ) const; 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. and it is not visible. It is only useful for accessing its children.
*/ */
wxPGProperty* GetPageRoot( int index ) const; wxPGProperty* GetPageRoot( int index ) const;
@@ -401,43 +406,54 @@ public:
/** Synonyme for GetSelectedPage. */ /** Synonyme for GetSelectedPage. */
int GetSelection() const { return m_selPage; } 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; } wxToolBar* GetToolBar() const { return m_pToolbar; }
/** 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. automatically.
@param index
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.
@param bmp
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.
*/
virtual int InsertPage( int index, const wxString& label, const wxBitmap& bmp = wxNullBitmap,
wxPropertyGridPage* pageObj = (wxPropertyGridPage*) NULL );
/** Returns true if any property on any page has been modified by the user. */ @param index
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.
@param bmp
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.
@return Returns index to the page created.
*/
virtual int 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.
*/
bool IsAnyModified() const; 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; bool IsPageModified( size_t index ) const;
virtual void Refresh( bool eraseBackground = true,
const wxRect* rect = (const wxRect*) NULL );
/** Removes a page. /** 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 ); virtual bool RemovePage( int page );
@@ -448,28 +464,19 @@ public:
*/ */
void SelectPage( int index ); void SelectPage( int index );
/** Select and displays a given page (by label). */ /**
void SelectPage( const wxString& label ) Select and displays a given page (by label).
{ */
int index = GetPageByName(label); void SelectPage( const wxString& label );
wxCHECK_RET( index >= 0, wxT("No page with such name") );
SelectPage( index );
}
/** Select and displays a given page. */ /** Select and displays a given page. */
void SelectPage( wxPropertyGridPage* ptr ) void SelectPage( wxPropertyGridPage* page );
{
SelectPage( GetPageByState(ptr) );
}
/** Select a property. */ /** Select a property. */
bool SelectProperty( wxPGPropArg id, bool focus = false ) bool SelectProperty( wxPGPropArg id, bool focus = false );
{
wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
return p->GetParentState()->DoSelectProperty(p, focus);
}
/** 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 ); void SetColumnCount( int colCount, int page = -1 );
@@ -482,11 +489,13 @@ public:
/** Moves splitter as left as possible, while still allowing all /** Moves splitter as left as possible, while still allowing all
labels to be shown in full. labels to be shown in full.
@param subProps @param subProps
If false, will still allow sub-properties (ie. properties which If @false, will still allow sub-properties (ie. properties which
parent is not root or category) to be cropped. parent is not root or category) to be cropped.
@param allPages @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 ); void SetSplitterLeft( bool subProps = false, bool allPages = true );
@@ -496,11 +505,13 @@ public:
GetPage(page)->DoSetSplitterPosition( pos, column ); GetPage(page)->DoSetSplitterPosition( pos, column );
} }
/** Sets splitter position for all pages. /**
@remarks Sets splitter position for all pages.
Splitter position cannot exceed grid size, and therefore setting it during
form creation may fail as initial grid size is often smaller than desired @remarks Splitter position cannot exceed grid size, and therefore setting
splitter position, especially when sizers are being used. 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 ); void SetSplitterPosition( int pos, int column = 0 );
@@ -516,12 +527,11 @@ protected:
// Subclassing helpers // Subclassing helpers
// //
/** Creates property grid for the manager. Override to use subclassed /**
Creates property grid for the manager. Override to use subclassed
wxPropertyGrid. wxPropertyGrid.
*/ */
virtual wxPropertyGrid* CreatePropertyGrid() const; virtual wxPropertyGrid* CreatePropertyGrid() const;
virtual void RefreshProperty( wxPGProperty* p );
}; };
// ----------------------------------------------------------------------- // -----------------------------------------------------------------------

1125
interface/wx/propgrid/property.h
View File

File diff suppressed because it is too large Load Diff