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

Updated documentation for some wxPropertyGrid classes.

Browse Source 
Updated documentation for wxPGEditor, wxPropertyGridPage, wxPropertyGridManager, wx*Property classes.
Removed doxygen-style comments from header files.
This commit is contained in:
Artur Wieczorek
2016-07-23 23:38:39 +02:00
parent b3d4c870da
commit cd96c664dd
10 changed files with 579 additions and 771 deletions
Download Patch File Download Diff File Expand all files Collapse all files

493
include/wx/propgrid/manager.h
View File

@@ -32,36 +32,25 @@
extern WXDLLIMPEXP_DATA_PROPGRID(const char) wxPropertyGridManagerNameStr[];
#endif
/** @class wxPropertyGridPage
Holder of property grid page information. You can subclass this and
give instance in wxPropertyGridManager::AddPage. It inherits from
wxEvtHandler and can be used to process events specific to this
page (id of events will still be same as manager's). If you don't
want to use it to process all events of the page, you need to
return false in the derived wxPropertyGridPage::IsHandlingAllEvents.
Please note that wxPropertyGridPage lacks many non-const property
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.
@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.
See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
for more information.
@library{wxpropgrid}
@category{propgrid}
*/
// Holder of property grid page information. You can subclass this and
// give instance in wxPropertyGridManager::AddPage. It inherits from
// wxEvtHandler and can be used to process events specific to this
// page (id of events will still be same as manager's). If you don't
// want to use it to process all events of the page, you need to
// return false in the derived wxPropertyGridPage::IsHandlingAllEvents.
//
// Please note that wxPropertyGridPage lacks many non-const property
// 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.
//
// 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.
class WXDLLIMPEXP_PROPGRID wxPropertyGridPage : public wxEvtHandler,
public wxPropertyGridInterface,
public wxPropertyGridPageState
@@ -73,88 +62,69 @@ public:
wxPropertyGridPage();
virtual ~wxPropertyGridPage();
/** Deletes all properties on page.
*/
// Deletes all properties on page.
virtual void Clear() wxOVERRIDE;
/**
Reduces column sizes to minimum possible that contents are still
visibly (naturally some margin space will be applied as well).
@return
Minimum size for the page to still display everything.
@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.
*/
// Reduces column sizes to minimum possible that contents are still
// visibly (naturally some margin space will be applied as well).
// Returns minimum size for the page to still display everything.
// 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.
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 x-coordinate position of splitter on a page.
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.
*/
// Returns "root property". It does not have name, etc. and it is not
// visible. It is only useful for accessing its children.
wxPGProperty* GetRoot() const { return GetStatePtr()->DoGetRoot(); }
/** Return pointer to contained property grid state.
*/
// Returns pointer to contained property grid state.
wxPropertyGridPageState* GetStatePtr()
{
return this;
}
/** Return pointer to contained property grid state.
*/
// Returns pointer to contained property grid state.
const wxPropertyGridPageState* GetStatePtr() const
{
return this;
}
/**
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_toolId;
}
/** 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.
// Notes:
// - 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
propagated to manager's parent, as normal.
*/
// 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.
Useful, for instance, creating properties just-in-time.
*/
// 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 ) wxOVERRIDE;
/** 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.
*/
// Sets splitter position on page.
// 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 );
#if WXWIN_COMPATIBILITY_3_0
@@ -165,16 +135,14 @@ public:
protected:
/** Propagate to other pages.
*/
// Propagate to other pages.
virtual void DoSetSplitterPosition( int pos,
int splitterColumn = 0,
int flags = wxPG_SPLITTER_REFRESH ) wxOVERRIDE;
/** Page label (may be referred as name in some parts of documentation).
Can be set in constructor, or passed in
wxPropertyGridManager::AddPage(), but *not* in both.
*/
// Page label (may be referred as name in some parts of documentation).
// Can be set in constructor, or passed in
// wxPropertyGridManager::AddPage(), but *not* in both.
wxString m_label;
//virtual bool ProcessEvent( wxEvent& event );
@@ -198,25 +166,10 @@ class wxPGHeaderCtrl;
#endif
/** @class wxPropertyGridManager
wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
which can optionally have toolbar for mode and page selection, and help
text box.
Use window flags to select components to include.
@section propgridmanager_window_styles_ Window Styles
See @ref propgrid_window_styles.
@section propgridmanager_event_handling Event Handling
See @ref propgrid_event_handling "wxPropertyGrid Event Handling"
for more information.
@library{wxpropgrid}
@category{propgrid}
*/
// wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
// which can optionally have toolbar for mode and page selection, and help
// text box.
// Use window flags to select components to include.
class WXDLLIMPEXP_PROPGRID
wxPropertyGridManager : public wxPanel, public wxPropertyGridInterface
{
@@ -225,46 +178,34 @@ class WXDLLIMPEXP_PROPGRID
public:
#ifndef SWIG
/**
Two step constructor.
Call Create when this constructor is called to build up the
wxPropertyGridManager.
*/
// Two step constructor.
// Call Create when this constructor is called to build up the
// wxPropertyGridManager.
wxPropertyGridManager();
#endif
/** The default constructor. The styles to be used are styles valid for
the wxWindow.
@see @link wndflags Additional Window Styles@endlink
*/
// The default constructor. The styles to be used are styles valid for
// the wxWindow.
wxPropertyGridManager( wxWindow *parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxPGMAN_DEFAULT_STYLE,
const wxString& name = wxPropertyGridManagerNameStr );
/** Destructor */
// Destructor.
virtual ~wxPropertyGridManager();
/** 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.
@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.
NULL indicates that a default page instance should be created.
@return
Returns pointer to created page.
@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.
*/
// Creates new property page. Note that the first page is not created
// automatically.
// label - A label for the page. This may be shown as a toolbar tooltip etc.
// bmp - Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
// default image is used.
// pageObj - wxPropertyGridPage instance. Manager will take ownership of this object.
// NULL indicates that a default page instance should be created.
// Returns pointer to created page.
// 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.
wxPropertyGridPage* AddPage( const wxString& label = wxEmptyString,
const wxBitmap& bmp = wxNullBitmap,
wxPropertyGridPage* pageObj = NULL )
@@ -272,41 +213,32 @@ public:
return InsertPage(-1, label, bmp, pageObj);
}
/** Deletes all all properties and all pages.
*/
// Deletes all all properties and all pages.
virtual void Clear() wxOVERRIDE;
/** 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.
// Returns true if DoPropertyChanged was actually called.
bool CommitChangesFromEditor( wxUint32 flags = 0 )
{
return m_pPropGrid->CommitChangesFromEditor(flags);
}
/**
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.
@see @link wndflags Additional Window Styles@endlink
*/
// 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.
bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxPGMAN_DEFAULT_STYLE,
const wxString& 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.
// Calling this may not properly update toolbar buttons.
bool EnableCategories( bool enable )
{
long fl = m_windowStyle | wxPG_HIDE_CATEGORIES;
@@ -315,22 +247,20 @@ public:
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. Returns true if something was actually done.
bool EnsureVisible( wxPGPropArg id );
/** 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;
/** 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
after wxPropertyGridManager has been created, so you can safely obtain
pointer once and use it for the entire lifetime of the instance.
*/
// 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 manager instance.
wxPropertyGrid* GetGrid()
{
wxASSERT(m_pPropGrid);
@@ -343,12 +273,10 @@ public:
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().
*/
// Returns iterator class instance.
// 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 )
{
@@ -366,12 +294,10 @@ public:
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().
*/
// Returns iterator class instance.
// 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( wxS("Please only iterate through individual pages ")
@@ -387,139 +313,110 @@ public:
return wxPropertyGridInterface::GetIterator( flags, startPos );
}
/** Similar to GetIterator, but instead returns wxPGVIterator instance,
which can be useful for forward-iterating through arbitrary property
containers.
*/
// 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 wxOVERRIDE;
/** Returns currently selected page.
*/
// Returns currently selected page.
wxPropertyGridPage* GetCurrentPage() const
{
return GetPage(m_selPage);
}
/** Returns page object for given page index.
*/
// Returns page object for given page index.
wxPropertyGridPage* GetPage( unsigned int ind ) const
{
return m_arrPages[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 index for a relevant propertygrid state.
If no match is found, wxNOT_FOUND is returned.
*/
// Returns index for a relevant propertygrid state.
// If no match is found, wxNOT_FOUND is returned.
int GetPageByState( const wxPropertyGridPageState* pstate ) const;
protected:
/** Returns wxPropertyGridPageState of given page, current page's for -1.
*/
// Returns wxPropertyGridPageState of given page, current page's for -1.
virtual wxPropertyGridPageState* GetPageState( int page ) const wxOVERRIDE;
public:
/** Returns number of managed pages. */
// Returns number of managed pages.
size_t GetPageCount() const;
/** Returns name of given page. */
// Returns name of given page.
const wxString& GetPageName( int index ) const;
/** 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.
*/
// 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;
/** Returns index to currently selected page. */
// Returns index to currently selected page.
int GetSelectedPage() const { return m_selPage; }
/** Alias for GetSelection(). */
// Alias for GetSelection().
wxPGProperty* GetSelectedProperty() const
{
return GetSelection();
}
/** Shortcut for GetGrid()->GetSelection(). */
// Shortcut for GetGrid()->GetSelection().
wxPGProperty* GetSelection() const
{
return m_pPropGrid->GetSelection();
}
#if wxUSE_TOOLBAR
/** 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; }
#endif // wxUSE_TOOLBAR
/** 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.
@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 pointer to created page.
*/
// Creates new property page. Note that the first page is not created
// automatically.
// index - Add to this position. -1 will add as the last item.
// label - A label for the page. This may be shown as a toolbar tooltip etc.
// bmp - Bitmap image for toolbar. If wxNullBitmap is used, then a built-in
// default image is used.
// pageObj - wxPropertyGridPage instance. Manager will take ownership of this object.
// If NULL, default page object is constructed.
// Returns pointer to created page.
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 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;
/**
Returns true if property is selected. Since selection is page
based, this function checks every page in the manager.
*/
// Returns true if property is selected. Since selection is page
// based, this function checks every page in the manager.
virtual bool IsPropertySelected( wxPGPropArg id ) const;
virtual void Refresh( bool eraseBackground = true,
const wxRect* rect = (const wxRect*) NULL ) wxOVERRIDE;
/** Removes a page.
@return
Returns false if it was not possible to remove page in question.
*/
// Removes a page.
// Returns false if it was not possible to remove page in question.
virtual bool RemovePage( int page );
/** Select and displays a given page.
@param index
Index of page being selected. Can be -1 to select nothing.
*/
// Select and displays a given page.
// index - Index of page being selected. Can be -1 to select nothing.
void SelectPage( int index );
/** Select and displays a given page (by label). */
// Select and displays a given page (by label).
void SelectPage( const wxString& label )
{
int index = GetPageByName(label);
@@ -527,13 +424,13 @@ public:
SelectPage( index );
}
/** Select and displays a given page. */
// Select and displays a given page.
void SelectPage( wxPropertyGridPage* ptr )
{
SelectPage( GetPageByState(ptr) );
}
/** Select a property. */
// Select a property.
bool SelectProperty( wxPGPropArg id, bool focus = false )
{
wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
@@ -545,78 +442,57 @@ public:
}
#if wxUSE_HEADERCTRL
/**
Sets a column title. Default title for column 0 is "Property",
and "Value" for column 1.
@remarks If header is not shown yet, then calling this
member function will make it visible.
*/
// Sets a column title. Default title for column 0 is "Property",
// and "Value" for column 1.
// If header is not shown yet, then calling this
// member function will make it visible.
void SetColumnTitle( int idx, const wxString& title );
#endif // wxUSE_HEADERCTRL
/**
Sets number of columns on given page (default is current page).
@remarks If you use header, then you should always use this
member function to set the column count, instead of
ones present in wxPropertyGrid or wxPropertyGridPage.
*/
// Sets number of columns on given page (default is current page).
// If you use header, then you should always use this
// member function to set the column count, instead of
// ones present in wxPropertyGrid or wxPropertyGridPage.
void SetColumnCount( int colCount, int page = -1 );
/** Sets label and text in description box.
*/
// Sets label and text in description box.
void SetDescription( const wxString& label, const wxString& content );
/** Sets y coordinate of the description box splitter. */
// Sets y coordinate of the description box splitter.
void SetDescBoxHeight( int ht, bool refresh = true );
/** 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.
@param allPages
If true, takes labels on all pages into account.
*/
// Moves splitter as left as possible, while still allowing all
// labels to be shown in full.
// subProps - If false, will still allow sub-properties (ie. properties which
// parent is not root or category) to be cropped.
// allPages - If true, takes labels on all pages into account.
void SetSplitterLeft( bool subProps = false, bool allPages = true );
/** Moves splitter as left as possible on an individual page, while still allowing all
labels to be shown in full.
*/
// Moves splitter as left as possible on an individual page, while still allowing all
// labels to be shown in full.
void SetPageSplitterLeft(int page, bool subProps = false);
/**
Sets splitter position on individual page.
@remarks If you use header, then you should always use this
member function to set the splitter position, instead of
ones present in wxPropertyGrid or wxPropertyGridPage.
*/
// Sets splitter position on individual page.
// If you use header, then you should always use this
// member function to set the splitter position, instead of
// ones present in wxPropertyGrid or wxPropertyGridPage.
void SetPageSplitterPosition( int page, int pos, int column = 0 );
/**
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.
If you use header, then you should always use this
member function to set the splitter position, instead of
ones present in wxPropertyGrid or wxPropertyGridPage.
*/
// 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 splitter position,
// especially when sizers are being used.
// If you use header, then you should always use this
// member function to set the splitter position, instead of
// ones present in wxPropertyGrid or wxPropertyGridPage.
void SetSplitterPosition( int pos, int column = 0 );
#if wxUSE_HEADERCTRL
/**
Show or hide the property grid header control. It is hidden
by the default.
@remarks Grid may look better if you use wxPG_NO_INTERNAL_BORDER
window style when showing a header.
*/
// Show or hide the property grid header control. It is hidden
// by the default.
// Grid may look better if you use wxPG_NO_INTERNAL_BORDER
// window style when showing a header.
void ShowHeader(bool show = true);
#endif
@@ -626,13 +502,11 @@ protected:
// Subclassing helpers
//
/**
Creates property grid for the manager. Reimplement in derived class to
use subclassed wxPropertyGrid. However, if you do this then you
must also use the two-step construction (i.e. default constructor and
Create() instead of constructor with arguments) when creating the
manager.
*/
// Creates property grid for the manager. Reimplement in derived class to
// use subclassed wxPropertyGrid. However, if you do this then you
// must also use the two-step construction (i.e. default constructor and
// Create() instead of constructor with arguments) when creating the
// manager.
virtual wxPropertyGrid* CreatePropertyGrid() const;
public:
@@ -722,7 +596,7 @@ protected:
virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const wxOVERRIDE;
/** Select and displays a given page. */
// Select and displays a given page.
virtual bool DoSelectPage( int index ) wxOVERRIDE;
// Sets some members to defaults.
@@ -737,12 +611,11 @@ protected:
virtual bool ProcessEvent( wxEvent& event ) wxOVERRIDE;
/** Recalculates new positions for components, according to the
given size.
*/
// Recalculates new positions for components, according to the
// given size.
void RecalculatePositions( int width, int height );
/** (Re)creates/destroys controls, according to the window style bits. */
// (Re)creates/destroys controls, according to the window style bits.
void RecreateControls();
void UpdateDescriptionBox( int new_splittery, int new_width, int new_height );