a3ed46f2c3
git-svn-id: svn://10.65.10.50/branches/R_10_00@23289 c028cbd2-c16b-5b4b-a496-9718f37d4682
1171 lines
127 KiB
HTML
1171 lines
127 KiB
HTML
<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<title>wxPropertyGrid: wxPropertyGrid 1.4.13 Overview</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javaScript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body onload='searchBox.OnSelectItem(0);'>
|
|
<!-- Generated by Doxygen 1.6.3 -->
|
|
<script type="text/javascript"><!--
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
--></script>
|
|
<div class="navigation" id="top">
|
|
<div class="tabs">
|
|
<ul>
|
|
<li class="current"><a href="index.htm"><span>Main Page</span></a></li>
|
|
<li><a href="pages.htm"><span>Related Pages</span></a></li>
|
|
<li><a href="modules.htm"><span>Modules</span></a></li>
|
|
<li><a href="annotated.htm"><span>Classes</span></a></li>
|
|
<li>
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
|
<img id="MSearchSelect" src="search/search.png"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
alt=""/>
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="contents">
|
|
<h1><a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> 1.4.13 Overview </h1><p><a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> is a specialized for editing properties such as strings, numbers, flagsets, fonts, and colours. It allows hierarchial, collapsible properties (via so-called categories that can hold child properties), sub-properties, and has strong wxVariant support.</p>
|
|
<p><b>Documentation for wxPython bindings:</b> For a tutorial see the accompanied wxPython readme file and the test_propgrid.py sample. Otherwise, individual member functions should work very much the same as with the C++ wxWidgets, so you'll probably find <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> and <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a> class references handy.</p>
|
|
<p>Key Classes:<br/>
|
|
<a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a><br/>
|
|
<a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a><br/>
|
|
<a class="el" href="classwxPropertyGridEvent.htm" title="A propertygrid event holds information about events associated with wxPropertyGrid...">wxPropertyGridEvent</a><br/>
|
|
</p>
|
|
<p>Header files:<br/>
|
|
<b>wx/propgrid/propgrid.h:</b> Mandatory when using <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>.<br/>
|
|
<b>wx/propgrid/advprops.h:</b> For less often used property classes.<br/>
|
|
<b>wx/propgrid/manager.h:</b> Mandatory when using <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a>.<br/>
|
|
<b>wx/propgrid/propdev.h:</b> Mandatory when implementing custom property classes.<br/>
|
|
</p>
|
|
<p><a class="el" href="index.htm#whatsnew">What's new in wxPropertyGrid 1.4?</a><br/>
|
|
<a class="el" href="index.htm#basics">Creating and Populating wxPropertyGrid</a><br/>
|
|
<a class="el" href="index.htm#categories">Categories</a><br/>
|
|
<a class="el" href="index.htm#parentprops">Tree-like Property Structure</a><br/>
|
|
<a class="el" href="index.htm#enumandflags">wxEnumProperty and wxFlagsProperty</a><br/>
|
|
<a class="el" href="index.htm#advprops">Specialized Properties</a><br/>
|
|
<a class="el" href="index.htm#iterating">Iterating through a property container</a><br/>
|
|
<a class="el" href="index.htm#operations">More About Operating with Properties</a><br/>
|
|
<a class="el" href="index.htm#events">Event Handling</a><br/>
|
|
<a class="el" href="index.htm#validating">Validating Property Values</a><br/>
|
|
<a class="el" href="index.htm#populating">Populating wxPropertyGrid Automatically</a><br/>
|
|
<a class="el" href="index.htm#cellrender">Customizing Individual Cell Appearance</a><br/>
|
|
<a class="el" href="index.htm#customizing">Customizing Properties (without sub-classing)</a><br/>
|
|
<a class="el" href="index.htm#usage2">Using wxPropertyGridManager</a><br/>
|
|
<a class="el" href="index.htm#subclassing">Subclassing wxPropertyGrid and wxPropertyGridManager</a><br/>
|
|
<a class="el" href="index.htm#misc">Miscellaneous Topics</a><br/>
|
|
<a class="el" href="index.htm#proplist">Property Class Descriptions</a><br/>
|
|
<a class="el" href="index.htm#userhelp">Using wxPropertyGrid control</a><br/>
|
|
<a class="el" href="index.htm#notes">Design Notes</a><br/>
|
|
<a class="el" href="index.htm#newprops">Creating New Properties</a><br/>
|
|
<a class="el" href="index.htm#neweditors">Creating Custom Property Editor</a><br/>
|
|
</p>
|
|
<h2><a class="anchor" id="whatsnew">
|
|
What's new in wxPropertyGrid 1.4?</a></h2>
|
|
<p>For comprehensive list of changes and new features, please see the changelog.</p>
|
|
<p>For people implementing custom property classes the differences are extensive, so if you are coming from <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> 1.2.x, it is recommended that you take a look.</p>
|
|
<h2><a class="anchor" id="basics">
|
|
Creating and Populating wxPropertyGrid</a></h2>
|
|
<p>As seen here, <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> is constructed in the same way as other wxWidgets controls:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// Necessary header file</span>
|
|
<span class="preprocessor"> #include <wx/propgrid/propgrid.h></span>
|
|
|
|
...
|
|
|
|
<span class="comment">// Assumes code is in frame/dialog constructor</span>
|
|
|
|
<span class="comment">// Construct wxPropertyGrid control</span>
|
|
<a class="code" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>* pg = <span class="keyword">new</span> <a class="code" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>(
|
|
<span class="keyword">this</span>, <span class="comment">// parent</span>
|
|
PGID, <span class="comment">// id</span>
|
|
wxDefaultPosition, <span class="comment">// position</span>
|
|
wxDefaultSize, <span class="comment">// size</span>
|
|
<span class="comment">// Some specific window styles - for all additional styles,</span>
|
|
<span class="comment">// see Modules->PropertyGrid Window Styles</span>
|
|
<a class="code" href="group__wndflags.htm#gga967b646b15085e115051d83a65ffdfe8a6bc5847c59e582bb9c3910ccb54d8635" title="This will cause Sort() automatically after an item is added.">wxPG_AUTO_SORT</a> | <span class="comment">// Automatic sorting after items added</span>
|
|
<a class="code" href="group__wndflags.htm#gga967b646b15085e115051d83a65ffdfe8a998b9d55c606adb1010be7438286e3c5" title="Using this style, the column splitters move automatically based on column proportions...">wxPG_SPLITTER_AUTO_CENTER</a> | <span class="comment">// Automatically center splitter until user manually adjusts it</span>
|
|
<span class="comment">// Default style</span>
|
|
<a class="code" href="group__wndflags.htm#gacf768b936525faa42392f653a3296eb4" title="Combines various styles.">wxPG_DEFAULT_STYLE</a> );
|
|
|
|
<span class="comment">// Window style flags are at premium, so some less often needed ones are</span>
|
|
<span class="comment">// available as extra window styles (wxPG_EX_xxx) which must be set using</span>
|
|
<span class="comment">// SetExtraStyle member function. wxPG_EX_HELP_AS_TOOLTIPS, for instance,</span>
|
|
<span class="comment">// allows displaying help strings as tooltips.</span>
|
|
pg->SetExtraStyle( <a class="code" href="group__wndflags.htm#ggaeebee6f1621b080999ea22a5b76b00a6aab51ec531320af974c83f1af88dd14b1" title="Show property help strings as tool tips instead as text on the status bar.">wxPG_EX_HELP_AS_TOOLTIPS</a> );
|
|
</pre></div><p>(for complete list of new window styles: <a class="el" href="group__wndflags.htm">Additional Window Styles</a>)</p>
|
|
<p><a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> is usually populated with lines like this:</p>
|
|
<div class="fragment"><pre class="fragment"> pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>(wxT(<span class="stringliteral">"Label"</span>),wxT(<span class="stringliteral">"Name"</span>),wxT(<span class="stringliteral">"Initial Value"</span>)) );
|
|
</pre></div><p>Naturally, <a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a> is a property class. Only the first function argument (label) is mandatory. Second one, name, defaults to label and, third, the initial value, to default value. If constant wxPG_LABEL is used as the name argument, then the label is automatically used as a name as well (this is more efficient than manually defining both as the same). Use of empty name is discouraged and will sometimes result in run-time error. Note that all property class constructors have quite similar constructor argument list.</p>
|
|
<p>To demonstrate other common property classes, here's another code snippet:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// Add int property</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"IntProperty"</span>), wxPG_LABEL, 12345678) );
|
|
|
|
<span class="comment">// Add float property (value type is actually double)</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxFloatProperty.htm" title="Basic property with double-precision floating point value.">wxFloatProperty</a>(wxT(<span class="stringliteral">"FloatProperty"</span>), wxPG_LABEL, 12345.678) );
|
|
|
|
<span class="comment">// Add a bool property</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxBoolProperty.htm" title="Basic property with boolean value.">wxBoolProperty</a>(wxT(<span class="stringliteral">"BoolProperty"</span>), wxPG_LABEL, <span class="keyword">false</span>) );
|
|
|
|
<span class="comment">// A string property that can be edited in a separate editor dialog.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxLongStringProperty.htm" title="Like wxStringProperty, but has a button that triggers a small text editor dialog...">wxLongStringProperty</a>(wxT(<span class="stringliteral">"LongStringProperty"</span>),
|
|
wxPG_LABEL,
|
|
wxT(<span class="stringliteral">"This is much longer string than the "</span>)
|
|
wxT(<span class="stringliteral">"first one. Edit it by clicking the button."</span>)));
|
|
|
|
<span class="comment">// String editor with dir selector button.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxDirProperty.htm" title="Like wxLongStringProperty, but the button triggers dir selector instead.">wxDirProperty</a>(wxT(<span class="stringliteral">"DirProperty"</span>), wxPG_LABEL, ::wxGetUserHome()) );
|
|
|
|
<span class="comment">// wxArrayStringProperty embeds a wxArrayString.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxArrayStringProperty.htm" title="Property that manages a list of strings.">wxArrayStringProperty</a>(wxT(<span class="stringliteral">"Label of ArrayStringProperty"</span>),
|
|
wxT(<span class="stringliteral">"NameOfArrayStringProp"</span>)));
|
|
|
|
<span class="comment">// A file selector property.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxFileProperty.htm" title="Like wxLongStringProperty, but the button triggers file selector instead.">wxFileProperty</a>(wxT(<span class="stringliteral">"FileProperty"</span>), wxPG_LABEL, wxEmptyString) );
|
|
|
|
<span class="comment">// Extra: set wildcard for file property (format same as in wxFileDialog).</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute of a property.">SetPropertyAttribute</a>( wxT(<span class="stringliteral">"FileProperty"</span>),
|
|
<a class="code" href="group__attrids.htm#ga1817e1bea592d9cda7a330ea3a25f851" title="wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies...">wxPG_FILE_WILDCARD</a>,
|
|
wxT(<span class="stringliteral">"All files (*.*)|*.*"</span>) );
|
|
</pre></div><p>Operations on properties should be done either via wxPropertyGrid's (or wxPropertyGridManager's) methods, or by acquiring pointer to a property (Append returns a wxPGProperty* or wxPGId, which is typedef for same), and then calling its method. Note however that property's methods generally do not automatically update grid graphics.</p>
|
|
<p>Property container functions operating on properties, such as SetPropertyValue or DisableProperty, all accept a special wxPGPropArg, argument which can automatically convert name of a property to a pointer. For instance:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// A file selector property.</span>
|
|
wxPGPropety* p = pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxFileProperty.htm" title="Like wxLongStringProperty, but the button triggers file selector instead.">wxFileProperty</a>(wxT(<span class="stringliteral">"FileProperty"</span>), wxPG_LABEL, wxEmptyString) );
|
|
|
|
<span class="comment">// Valid: Set wildcard by name</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute of a property.">SetPropertyAttribute</a>( wxT(<span class="stringliteral">"FileProperty"</span>),
|
|
<a class="code" href="group__attrids.htm#ga1817e1bea592d9cda7a330ea3a25f851" title="wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies...">wxPG_FILE_WILDCARD</a>,
|
|
wxT(<span class="stringliteral">"All files (*.*)|*.*"</span>) );
|
|
|
|
<span class="comment">// Also Valid: Set wildcard by ptr</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute of a property.">SetPropertyAttribute</a>( p,
|
|
<a class="code" href="group__attrids.htm#ga1817e1bea592d9cda7a330ea3a25f851" title="wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies...">wxPG_FILE_WILDCARD</a>,
|
|
wxT(<span class="stringliteral">"All files (*.*)|*.*"</span>) );
|
|
</pre></div><p>Using pointer is faster, since it doesn't require hash map lookup. Anyway, you can allways get property pointer (wxPGProperty*) as Append/Insert return value, or by calling GetPropertyByName.</p>
|
|
<p>Below are samples for using some of the more commong operations. See <a class="el" href="classwxPropertyGridInterface.htm" title="In order to have most same base methods, both wxPropertyGrid and wxPropertyGridManager...">wxPropertyGridInterface</a> and <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> class references for complete list.</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// wxPGId is a short-hand for wxPGProperty*. Let's use it this time.</span>
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGId</a> <span class="keywordtype">id</span> = pg-><a class="code" href="classwxPropertyGridInterface.htm#ac5723b61ae48d373671343e774632ed3" title="Returns pointer to the property with given name (case-sensitive).">GetPropertyByName</a>( wxT(<span class="stringliteral">"MyProperty"</span>) );
|
|
|
|
<span class="comment">// There are many overloaded versions of this method, of which each accept</span>
|
|
<span class="comment">// different type of value.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#aa652e127ce0c9d4e80821cbdcfe4983c" title="Sets value (long integer) of a property.">SetPropertyValue</a>( wxT(<span class="stringliteral">"MyProperty"</span>), 200 );
|
|
|
|
<span class="comment">// Setting a string works for all properties - conversion is done</span>
|
|
<span class="comment">// automatically.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#aa652e127ce0c9d4e80821cbdcfe4983c" title="Sets value (long integer) of a property.">SetPropertyValue</a>( <span class="keywordtype">id</span>, wxT(<span class="stringliteral">"400"</span>) );
|
|
|
|
<span class="comment">// Getting property value as wxVariant.</span>
|
|
wxVariant value = pg-><a class="code" href="classwxPropertyGridInterface.htm#aa1164652240e4b157ce5250769af537e" title="Returns value as wxVariant.">GetPropertyValue</a>( wxT(<span class="stringliteral">"MyProperty"</span>) );
|
|
|
|
<span class="comment">// Getting property value as String (again, works for all typs).</span>
|
|
wxString value = pg->GetPropertyValueAsString( <span class="keywordtype">id</span> );
|
|
|
|
<span class="comment">// Getting property value as int. Provokes a run-time error</span>
|
|
<span class="comment">// if used with property which value type is not "long".</span>
|
|
<span class="keywordtype">long</span> value = pg->GetPropertyValueAsLong( wxT(<span class="stringliteral">"MyProperty"</span>) );
|
|
|
|
<span class="comment">// Set new name.</span>
|
|
pg-><a class="code" href="classwxPropertyGrid.htm#aee6c7e1d87b7c1a1c7d12715f43fb459" title="Sets name of a property.">SetPropertyName</a>( wxT(<span class="stringliteral">"MyProperty"</span>), wxT(<span class="stringliteral">"X"</span>) );
|
|
|
|
<span class="comment">// Set new label - we need to use the new name.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#ad7cc77546762cc92e69078d6ac161c63" title="Sets label of a property.">SetPropertyLabel</a>( wxT(<span class="stringliteral">"X"</span>), wxT(<span class="stringliteral">"New Label"</span>) );
|
|
|
|
<span class="comment">// Disable the property. It's text will appear greyed.</span>
|
|
<span class="comment">// This is probably the closest you can get if you want</span>
|
|
<span class="comment">// a "read-only" property.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#ac2b62fc91927b5b4f9e9a95eebbb26d1" title="Disables property.">DisableProperty</a>( <span class="keywordtype">id</span> );
|
|
</pre></div><h2><a class="anchor" id="categories">
|
|
Categories</a></h2>
|
|
<p><a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> has a hierarchial property storage and display model, which allows property categories to hold child properties and even other categories. Other than that, from the programmer's point of view, categories can be treated exactly the same as "other" properties. For example, despite its name, GetPropertyByName also returns a category by name, and SetPropertyLabel also sets label of a category. Note however that sometimes the label of a property category may be referred as caption (for example, there is SetCaptionForegroundColour method that sets text colour of a property category's label).</p>
|
|
<p>When category is added at the top (i.e. root) level of the hierarchy, it becomes a *current category*. This means that all other (non-category) properties after it are automatically added to it. You may add properties to specific categories by using <a class="el" href="classwxPropertyGridInterface.htm#abf342b34022630c15038c9d7679d3c57" title="Inserts property to the property container.">wxPropertyGrid::Insert</a> or wxPropertyGrid::AppendIn.</p>
|
|
<p>Category code sample:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// One way to add category (similar to how other properties are added)</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxPropertyCategory.htm" title="Category (caption) property.">wxPropertyCategory</a>(wxT(<span class="stringliteral">"Main"</span>)) );
|
|
|
|
<span class="comment">// All these are added to "Main" category</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>(wxT(<span class="stringliteral">"Name"</span>)) );
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Age"</span>),wxPG_LABEL,25) );
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Height"</span>),wxPG_LABEL,180) );
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Weight"</span>)) );
|
|
|
|
<span class="comment">// Another one</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxPropertyCategory.htm" title="Category (caption) property.">wxPropertyCategory</a>(wxT(<span class="stringliteral">"Attrikbutes"</span>)) );
|
|
|
|
<span class="comment">// All these are added to "Attributes" category</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Intelligence"</span>)) );
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Agility"</span>)) );
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Strength"</span>)) );
|
|
</pre></div><h2><a class="anchor" id="parentprops">
|
|
Tree-like Property Structure</a></h2>
|
|
<p>As a new feature in version 1.3.1, basicly any property can have children. There are few limitations, however.</p>
|
|
<dl class="remark"><dt><b>Remarks:</b></dt><dd><ul>
|
|
<li>Names of properties with non-category, non-root parents are not stored in hash map. Instead, they can be accessed with strings like "Parent.Child". For instance, in the sample below, child property named "Max. Speed (mph)" can be accessed by global name "Car.Speeds.Max Speed (mph)".</li>
|
|
<li>If you want to property's value to be a string composed based on the values of child properties, you must use <a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a> as parent and use value "<composed>".</li>
|
|
<li>Events (eg. change of value) that occur in parent do not propagate to children. Events that occur in children will propagate to parents, but only if they are wxStringProperties with "<composed>" value.</li>
|
|
<li>Old wxParentProperty class is deprecated, and remains as a typedef of <a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>. If you want old value behavior, you must specify "<composed>" as wxStringProperty's value.</li>
|
|
</ul>
|
|
</dd></dl>
|
|
<p>Sample:</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGId</a> pid = pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>(wxT(<span class="stringliteral">"Car"</span>),wxPG_LABEL,wxT(<span class="stringliteral">"<composed>"</span>)) );
|
|
|
|
pg->AppendIn( pid, <span class="keyword">new</span> <a class="code" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>(wxT(<span class="stringliteral">"Model"</span>),
|
|
wxPG_LABEL,
|
|
wxT(<span class="stringliteral">"Lamborghini Diablo SV"</span>)) );
|
|
|
|
pg->AppendIn( pid, <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Engine Size (cc)"</span>),
|
|
wxPG_LABEL,
|
|
5707) );
|
|
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGId</a> speedId = pg->AppendIn( pid, <span class="keyword">new</span> <a class="code" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>(wxT(<span class="stringliteral">"Speeds"</span>),wxPG_LABEL,wxT(<span class="stringliteral">"<composed>"</span>)) );
|
|
pg->AppendIn( speedId, <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Max. Speed (mph)"</span>),wxPG_LABEL,290) );
|
|
pg->AppendIn( speedId, <span class="keyword">new</span> <a class="code" href="classwxFloatProperty.htm" title="Basic property with double-precision floating point value.">wxFloatProperty</a>(wxT(<span class="stringliteral">"0-100 mph (sec)"</span>),wxPG_LABEL,3.9) );
|
|
pg->AppendIn( speedId, <span class="keyword">new</span> <a class="code" href="classwxFloatProperty.htm" title="Basic property with double-precision floating point value.">wxFloatProperty</a>(wxT(<span class="stringliteral">"1/4 mile (sec)"</span>),wxPG_LABEL,8.6) );
|
|
|
|
<span class="comment">// Make sure the child properties can be accessed correctly</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#aa652e127ce0c9d4e80821cbdcfe4983c" title="Sets value (long integer) of a property.">SetPropertyValue</a>( wxT(<span class="stringliteral">"Car.Speeds.Max. Speed (mph)"</span>), 300 );
|
|
|
|
pg->AppendIn( pid, <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Price ($)"</span>),
|
|
wxPG_LABEL,
|
|
300000) );
|
|
<span class="comment">// Displayed value of "Car" property is now:</span>
|
|
<span class="comment">// "Lamborghini Diablo SV; [300; 3.9; 8.6]; 300000"</span>
|
|
</pre></div><h2><a class="anchor" id="enumandflags">
|
|
wxEnumProperty and wxFlagsProperty</a></h2>
|
|
<p><a class="el" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a> is used when you want property's (integer or string) value to be selected from a popup list of choices.</p>
|
|
<p>Creating <a class="el" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a> is more complex than those described earlier. You have to provide list of constant labels, and optionally relevant values (if label indexes are not sufficient).</p>
|
|
<dl class="remark"><dt><b>Remarks:</b></dt><dd></dd></dl>
|
|
<ul>
|
|
<li>Value wxPG_INVALID_VALUE (equals 2147483647 which usually equals INT_MAX) is not allowed as value.</li>
|
|
</ul>
|
|
<p>A very simple example:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">//</span>
|
|
<span class="comment">// Using wxArrayString</span>
|
|
<span class="comment">//</span>
|
|
wxArrayString arrDiet;
|
|
arr.Add(wxT(<span class="stringliteral">"Herbivore"</span>));
|
|
arr.Add(wxT(<span class="stringliteral">"Carnivore"</span>));
|
|
arr.Add(wxT(<span class="stringliteral">"Omnivore"</span>));
|
|
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>(wxT(<span class="stringliteral">"Diet"</span>),
|
|
wxPG_LABEL,
|
|
arrDiet) );
|
|
|
|
|
|
|
|
<span class="comment">//</span>
|
|
<span class="comment">// Using wxChar* array</span>
|
|
<span class="comment">//</span>
|
|
<span class="keyword">const</span> wxChar* arrayDiet[] =
|
|
{ wxT(<span class="stringliteral">"Herbivore"</span>), wxT(<span class="stringliteral">"Carnivore"</span>), wxT(<span class="stringliteral">"Omnivore"</span>), NULL };
|
|
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>(wxT(<span class="stringliteral">"Diet"</span>),
|
|
wxPG_LABEL,
|
|
arrayDiet) );
|
|
</pre></div><p>Here's extended example using values as well:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">//</span>
|
|
<span class="comment">// Using wxArrayString and wxArrayInt</span>
|
|
<span class="comment">//</span>
|
|
wxArrayString arrDiet;
|
|
arr.Add(wxT(<span class="stringliteral">"Herbivore"</span>));
|
|
arr.Add(wxT(<span class="stringliteral">"Carnivore"</span>));
|
|
arr.Add(wxT(<span class="stringliteral">"Omnivore"</span>));
|
|
|
|
wxArrayInt arrIds;
|
|
arrIds.Add(40);
|
|
arrIds.Add(45);
|
|
arrIds.Add(50);
|
|
|
|
<span class="comment">// Note that the initial value (the last argument) is the actual value,</span>
|
|
<span class="comment">// not index or anything like that. Thus, our value selects "Omnivore".</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>(wxT(<span class="stringliteral">"Diet"</span>),
|
|
wxPG_LABEL,
|
|
arrDiet,
|
|
arrIds,
|
|
50));
|
|
|
|
|
|
<span class="comment">//</span>
|
|
<span class="comment">// Using wxChar* and long arrays</span>
|
|
<span class="comment">//</span>
|
|
<span class="keyword">const</span> wxChar* array_diet[] =
|
|
{ wxT(<span class="stringliteral">"Herbivore"</span>), wxT(<span class="stringliteral">"Carnivore"</span>), wxT(<span class="stringliteral">"Omnivore"</span>), NULL };
|
|
|
|
<span class="keywordtype">long</span> array_diet_ids[] =
|
|
{ 40, 45, 50 };
|
|
|
|
<span class="comment">// Value can be set from string as well</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>(wxT(<span class="stringliteral">"Diet"</span>),
|
|
wxPG_LABEL,
|
|
array_diet,
|
|
array_diet_ids);
|
|
</pre></div><p><a class="el" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a> is a class where <a class="el" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>, and other properties which require label storage, actually stores strings and values. It is used to facilitiate reference counting, and therefore recommended way of adding items when multiple properties share the same set.</p>
|
|
<p>You can use <a class="el" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a> directly as well, filling it and then passing it to the constructor. Infact, if you wish to display bitmaps next to labels, your best choice is to use this approach.</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a> chs;
|
|
chs.<a class="code" href="classwxPGChoices.htm#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(wxT(<span class="stringliteral">"Herbivore"</span>),40);
|
|
chs.<a class="code" href="classwxPGChoices.htm#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(wxT(<span class="stringliteral">"Carnivore"</span>),45);
|
|
chs.<a class="code" href="classwxPGChoices.htm#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(wxT(<span class="stringliteral">"Omnivore"</span>),50);
|
|
|
|
<span class="comment">// Let's add an item with bitmap, too</span>
|
|
chs.<a class="code" href="classwxPGChoices.htm#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(wxT(<span class="stringliteral">"None of the above"</span>), wxBitmap(), 60);
|
|
|
|
<span class="comment">// Note: you can add even whole arrays to wxPGChoices</span>
|
|
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>(wxT(<span class="stringliteral">"Diet"</span>),
|
|
wxPG_LABEL,
|
|
chs) );
|
|
|
|
<span class="comment">// Add same choices to another property as well - this is efficient due</span>
|
|
<span class="comment">// to reference counting</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>(wxT(<span class="stringliteral">"Diet 2"</span>),
|
|
wxPG_LABEL,
|
|
chs) );
|
|
</pre></div><p>If you later need to change choices used by a property, there is function for that as well.</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">//</span>
|
|
<span class="comment">// Example 1: Add one extra item</span>
|
|
<a class="code" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a>& choices = pg-><a class="code" href="classwxPropertyGridInterface.htm#a5ad74d7087934327a32e969691d043a3" title="Returns writable reference to property&#39;s list of choices (and relevant values)...">GetPropertyChoices</a>(wxT(<span class="stringliteral">"Diet"</span>));
|
|
choices.<a class="code" href="classwxPGChoices.htm#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(wxT(<span class="stringliteral">"Custom"</span>),55);
|
|
|
|
<span class="comment">//</span>
|
|
<span class="comment">// Example 2: Replace all the choices</span>
|
|
<a class="code" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a> chs;
|
|
chs.<a class="code" href="classwxPGChoices.htm#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(wxT(<span class="stringliteral">"<No valid items yet>"</span>),0);
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#ad5e4e10acaedf04f666937fd2a90500a" title="Set choices of a property to specified set of labels and values.">SetPropertyChoices</a>(wxT(<span class="stringliteral">"Diet"</span>),chs);
|
|
</pre></div><p>If you want to create your enum properties with simple (label,name,value) constructor, then you need to create a new property class using one of the supplied macro pairs. See <a class="el" href="index.htm#newprops">Creating New Properties</a> for details.</p>
|
|
<p><b><a class="el" href="classwxEditEnumProperty.htm" title="wxEnumProperty with wxString value and writable combo box editor.">wxEditEnumProperty</a></b> is works exactly like <a class="el" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a>, except is uses non-readonly combobox as default editor, and value is stored as string when it is not any of the choices.</p>
|
|
<p><a class="el" href="classwxFlagsProperty.htm" title="Represents a bit set that fits in a long integer.">wxFlagsProperty</a> is similar:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="keyword">const</span> wxChar* flags_prop_labels[] = { wxT(<span class="stringliteral">"wxICONIZE"</span>),
|
|
wxT(<span class="stringliteral">"wxCAPTION"</span>), wxT(<span class="stringliteral">"wxMINIMIZE_BOX"</span>), wxT(<span class="stringliteral">"wxMAXIMIZE_BOX"</span>), NULL };
|
|
|
|
<span class="comment">// this value array would be optional if values matched string indexes</span>
|
|
<span class="keywordtype">long</span> flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX,
|
|
wxMAXIMIZE_BOX };
|
|
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxFlagsProperty.htm" title="Represents a bit set that fits in a long integer.">wxFlagsProperty</a>(wxT(<span class="stringliteral">"Window Style"</span>),
|
|
wxPG_LABEL,
|
|
flags_prop_labels,
|
|
flags_prop_values,
|
|
wxDEFAULT_FRAME_STYLE) );
|
|
</pre></div><p><a class="el" href="classwxFlagsProperty.htm" title="Represents a bit set that fits in a long integer.">wxFlagsProperty</a> can use <a class="el" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a> just the same way as <a class="el" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a> (and also custom property classes can be created with similar macro pairs). <b>Note: </b> When changing "choices" (ie. flag labels) of <a class="el" href="classwxFlagsProperty.htm" title="Represents a bit set that fits in a long integer.">wxFlagsProperty</a>, you will need to use SetPropertyChoices - otherwise they will not get updated properly.</p>
|
|
<h2><a class="anchor" id="advprops">
|
|
Specialized Properties</a></h2>
|
|
<p>This section describes the use of less often needed property classes. To use them, you have to include <wx/propgrid/advprops.h>.</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// Necessary extra header file</span>
|
|
<span class="preprocessor"> #include <wx/propgrid/advprops.h></span>
|
|
|
|
...
|
|
|
|
<span class="comment">// Date property.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxDateProperty.htm" title="Property representing wxDateTime.">wxDateProperty</a>(wxT(<span class="stringliteral">"MyDateProperty"</span>),
|
|
wxPG_LABEL,
|
|
wxDateTime::Now()) );
|
|
|
|
<span class="comment">// Image file property. Wildcard is auto-generated from available</span>
|
|
<span class="comment">// image handlers, so it is not set this time.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxImageFileProperty.htm" title="Property representing image file(name).">wxImageFileProperty</a>(wxT(<span class="stringliteral">"Label of ImageFileProperty"</span>),
|
|
wxT(<span class="stringliteral">"NameOfImageFileProp"</span>)) );
|
|
|
|
<span class="comment">// Font property has sub-properties. Note that we give window's font as</span>
|
|
<span class="comment">// initial value.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxFontProperty.htm" title="Property representing wxFont.">wxFontProperty</a>(wxT(<span class="stringliteral">"Font"</span>),
|
|
wxPG_LABEL,
|
|
GetFont()) );
|
|
|
|
<span class="comment">// Colour property with arbitrary colour.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxColourProperty.htm">wxColourProperty</a>(wxT(<span class="stringliteral">"My Colour 1"</span>),
|
|
wxPG_LABEL,
|
|
wxColour(242,109,0) ) );
|
|
|
|
<span class="comment">// System colour property.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxSystemColourProperty.htm" title="Has dropdown list of wxWidgets system colours.">wxSystemColourProperty</a>(wxT(<span class="stringliteral">"My SysColour 1"</span>),
|
|
wxPG_LABEL,
|
|
wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
|
|
|
|
<span class="comment">// System colour property with custom colour.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxSystemColourProperty.htm" title="Has dropdown list of wxWidgets system colours.">wxSystemColourProperty</a>(wxT(<span class="stringliteral">"My SysColour 2"</span>),
|
|
wxPG_LABEL,
|
|
wxColour(0,200,160) ) );
|
|
|
|
<span class="comment">// Cursor property</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxCursorProperty.htm" title="Property representing wxCursor.">wxCursorProperty</a>(wxT(<span class="stringliteral">"My Cursor"</span>),
|
|
wxPG_LABEL,
|
|
wxCURSOR_ARROW));
|
|
</pre></div><h2><a class="anchor" id="iterating">
|
|
Iterating through a property container</a></h2>
|
|
<p>You can use somewhat STL'ish iterator classes to iterate through the grid. Here is a simple example of forward iterating through all individual properties (not categories or sub-propeties that are normally 'transparent' to application code):</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPropertyGridIterator.htm" title="Preferable way to iterate through contents of wxPropertyGrid, wxPropertyGridManager...">wxPropertyGridIterator</a> it;
|
|
|
|
<span class="keywordflow">for</span> ( it = pg-><a class="code" href="classwxPropertyGridInterface.htm#a41ab8661411082563c8191f614f91007" title="Returns iterator class instance.">GetIterator</a>();
|
|
!it.AtEnd();
|
|
it++ )
|
|
{
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = *it;
|
|
<span class="comment">// Do something with the property</span>
|
|
}
|
|
</pre></div><p>As expected there is also a const iterator:</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPropertyGridConstIterator.htm" title="Const version of wxPropertyGridIterator.">wxPropertyGridConstIterator</a> it;
|
|
|
|
<span class="keywordflow">for</span> ( it = pg-><a class="code" href="classwxPropertyGridInterface.htm#a41ab8661411082563c8191f614f91007" title="Returns iterator class instance.">GetIterator</a>();
|
|
!it.AtEnd();
|
|
it++ )
|
|
{
|
|
<span class="keyword">const</span> <a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = *it;
|
|
<span class="comment">// Do something with the property</span>
|
|
}
|
|
</pre></div><p>You can give some arguments to GetIterator to determine which properties get automatically filtered out. For complete list of options, see <a class="el" href="group__iteratorflags.htm">List of Property Iterator Flags</a>. GetIterator() also accepts other arguments. See <a class="el" href="classwxPropertyGridInterface.htm#a41ab8661411082563c8191f614f91007" title="Returns iterator class instance.">wxPropertyGridInterface::GetIterator()</a> for details.</p>
|
|
<p>This example reverse-iterates through all visible items:</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPropertyGridIterator.htm" title="Preferable way to iterate through contents of wxPropertyGrid, wxPropertyGridManager...">wxPropertyGridIterator</a> it;
|
|
|
|
<span class="keywordflow">for</span> ( it = pg-><a class="code" href="classwxPropertyGridInterface.htm#a41ab8661411082563c8191f614f91007" title="Returns iterator class instance.">GetIterator</a>(<a class="code" href="group__iteratorflags.htm#gga307ba26bf1eeb9d76108893f4f723b0aaafca9ed41c9420c5efb18b7e519928e5" title="Combines all flags needed to iterate through visible properties (ie.">wxPG_ITERATE_VISIBLE</a>, wxBOTTOM);
|
|
!it.AtEnd();
|
|
it-- )
|
|
{
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = *it;
|
|
<span class="comment">// Do something with the property</span>
|
|
}
|
|
</pre></div><p><b>wxPython Note:</b> Instead of ++ operator, use Next() method, and instead of operator, use GetProperty() method.</p>
|
|
<p>GetIterator() only works with <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> and the individual pages of <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a>. In order to iterate through an arbitrary property container, you need to use <a class="el" href="classwxPropertyGridInterface.htm#a96a1c13733c0a83d7b509fd7a9e9a61a" title="Similar to GetIterator, but instead returns wxPGVIterator instance, which can be...">wxPropertyGridInterface::GetVIterator()</a>. Note however that this virtual iterater is limited to forward iteration.</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPGVIterator.htm" title="Abstract implementation of a simple iterator.">wxPGVIterator</a> it;
|
|
|
|
<span class="keywordflow">for</span> ( it = manager->GetVIterator();
|
|
!it.AtEnd();
|
|
it.Next() )
|
|
{
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = it.GetProperty();
|
|
<span class="comment">// Do something with the property</span>
|
|
}
|
|
</pre></div><h2><a class="anchor" id="operations">
|
|
More About Operating with Properties</a></h2>
|
|
<p>Getting value of selected <a class="el" href="classwxSystemColourProperty.htm" title="Has dropdown list of wxWidgets system colours.">wxSystemColourProperty</a> (which value type is derived from wxObject):</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGId</a> <span class="keywordtype">id</span> = pg-><a class="code" href="classwxPropertyGridInterface.htm#a302ae0ff624d48131544f6010373e599" title="Returns currently selected property.">GetSelection</a>();
|
|
|
|
<span class="keywordflow">if</span> ( <span class="keywordtype">id</span> )
|
|
{
|
|
<span class="comment">// Get name of property</span>
|
|
<span class="keyword">const</span> wxString& name = pg-><a class="code" href="classwxPropertyGridInterface.htm#a78ee2f3686e934e76bfa20a3b8415b91" title="Returns name of a property, by which it is globally accessible.">GetPropertyName</a>( <span class="keywordtype">id</span> );
|
|
|
|
<span class="comment">// If type is not correct, GetColour() method will produce run-time error</span>
|
|
<span class="keywordflow">if</span> ( pg->GetPropertyValueType() == wxT(<span class="stringliteral">"wxColourPropertyValue"</span>) ) )
|
|
{
|
|
<a class="code" href="classwxColourPropertyValue.htm" title="Because text, background and other colours tend to differ between platforms, wxSystemColourProperty...">wxColourPropertyValue</a>* pcolval =
|
|
wxDynamicCast(pg->GetPropertyValueAsWxObjectPtr(<span class="keywordtype">id</span>),
|
|
<a class="code" href="classwxColourPropertyValue.htm" title="Because text, background and other colours tend to differ between platforms, wxSystemColourProperty...">wxColourPropertyValue</a>);
|
|
|
|
<span class="comment">// Report value</span>
|
|
wxString text;
|
|
<span class="keywordflow">if</span> ( pcolval-><a class="code" href="classwxColourPropertyValue.htm#a42fffa02f3ba7f377168a22b6e9150fe" title="An integer value relating to the colour, and which exact meaning depends on the property...">m_type</a> == wxPG_CUSTOM_COLOUR )
|
|
text.Printf( wxT(<span class="stringliteral">"It is custom colour: (%i,%i,%i)"</span>),
|
|
(<span class="keywordtype">int</span>)pcolval-><a class="code" href="classwxColourPropertyValue.htm#a40742851ba26cd29450466011e8af4bc" title="Resulting colour.">m_colour</a>.Red(),
|
|
(int)pcolval-><a class="code" href="classwxColourPropertyValue.htm#a40742851ba26cd29450466011e8af4bc" title="Resulting colour.">m_colour</a>.Green(),
|
|
(int)pcolval-><a class="code" href="classwxColourPropertyValue.htm#a40742851ba26cd29450466011e8af4bc" title="Resulting colour.">m_colour</a>.Blue());
|
|
<span class="keywordflow">else</span>
|
|
text.Printf( wxT(<span class="stringliteral">"It is wx system colour (number=%i): (%i,%i,%i)"</span>),
|
|
(<span class="keywordtype">int</span>)pcolval-><a class="code" href="classwxColourPropertyValue.htm#a42fffa02f3ba7f377168a22b6e9150fe" title="An integer value relating to the colour, and which exact meaning depends on the property...">m_type</a>,
|
|
(<span class="keywordtype">int</span>)pcolval-><a class="code" href="classwxColourPropertyValue.htm#a40742851ba26cd29450466011e8af4bc" title="Resulting colour.">m_colour</a>.Red(),
|
|
(int)pcolval-><a class="code" href="classwxColourPropertyValue.htm#a40742851ba26cd29450466011e8af4bc" title="Resulting colour.">m_colour</a>.Green(),
|
|
(int)pcolval-><a class="code" href="classwxColourPropertyValue.htm#a40742851ba26cd29450466011e8af4bc" title="Resulting colour.">m_colour</a>.Blue());
|
|
|
|
wxMessageBox( text );
|
|
}
|
|
}
|
|
</pre></div><h2><a class="anchor" id="populating">
|
|
Populating wxPropertyGrid Automatically</a></h2>
|
|
<h3><a class="anchor" id="fromvariants">
|
|
Populating from List of wxVariants</a></h3>
|
|
<p>Example of populating an empty <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> from a values stored in an arbitrary list of wxVariants.</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// This is a static method that initializes *all* builtin type handlers</span>
|
|
<span class="comment">// available, including those for wxColour and wxFont. Refers to *all*</span>
|
|
<span class="comment">// included properties, so when compiling with static library, this</span>
|
|
<span class="comment">// method may increase the executable size significantly.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a38bd0419a578467da07d01aef288848d" title="Initializes *all* property types.">InitAllTypeHandlers</a>();
|
|
|
|
<span class="comment">// Get contents of the grid as a wxVariant list</span>
|
|
wxVariant all_values = pg-><a class="code" href="classwxPropertyGridInterface.htm#a1abce6843caee96faaeeee952f970105" title="Returns a wxVariant list containing wxVariant versions of all property values.">GetPropertyValues</a>();
|
|
|
|
<span class="comment">// Populate the list with values. If a property with appropriate</span>
|
|
<span class="comment">// name is not found, it is created according to the type of variant.</span>
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#a3c3baf524979bff36ee6e3cd8ff60b3f" title="Sets property values from a list of wxVariants.">SetPropertyValues</a>( my_list_variant );
|
|
|
|
<span class="comment">// In order to get wxObject ptr from a variant value,</span>
|
|
<span class="comment">// wxGetVariantCast(VARIANT,CLASSNAME) macro has to be called.</span>
|
|
<span class="comment">// Like this:</span>
|
|
wxVariant v_txcol = pg-><a class="code" href="classwxPropertyGridInterface.htm#aa1164652240e4b157ce5250769af537e" title="Returns value as wxVariant.">GetPropertyValue</a>(wxT(<span class="stringliteral">"Text Colour"</span>));
|
|
<span class="keyword">const</span> wxColour& txcol = wxGetVariantCast(v_txcol,wxColour);
|
|
</pre></div><h3><a class="anchor" id="fromfile">
|
|
Loading Population from a Text-based Storage</a></h3>
|
|
<p>Class <a class="el" href="classwxPropertyGridPopulator.htm" title="Allows populating wxPropertyGrid from arbitrary text source.">wxPropertyGridPopulator</a> may be helpful when writing code that loads properties from a text-source. In fact, the supplied xrc handler (src/xh_propgrid.cpp) uses it. See that code for more info. NOTE: src/xh_propgrid.cpp is not included in the library by default, to avoid dependency to wxXRC. You will need to add it to your application separately.</p>
|
|
<h3><a class="anchor" id="editablestate">
|
|
Saving and Restoring User-Editable State</a></h3>
|
|
<p>You can use <a class="el" href="classwxPropertyGridInterface.htm#a09dcfdf53629918183615627957afe39" title="Used to acquire user-editable state (selected property, expanded properties, scrolled...">wxPropertyGridInterface::SaveEditableState()</a> and <a class="el" href="classwxPropertyGridInterface.htm#aceb7f1ca6c7079c075d9876b94a2cb0f" title="Restores user-editable state.">wxPropertyGridInterface::RestoreEditableState()</a> to save and restore user-editable state (selected property, expanded/collapsed properties, selected page, scrolled position, and splitter positions).</p>
|
|
<h2><a class="anchor" id="events">
|
|
Event Handling</a></h2>
|
|
<p>Probably the most important event is the Changed event which occurs when value of any property is changed by the user. Use EVT_PG_CHANGED(id,func) in your event table to use it.</p>
|
|
<p>For complete list of event types, see <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> class reference.</p>
|
|
<p>The custom event class, <a class="el" href="classwxPropertyGridEvent.htm" title="A propertygrid event holds information about events associated with wxPropertyGrid...">wxPropertyGridEvent</a>, has methods to directly access the property that triggered the event.</p>
|
|
<p>Here's a small sample:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// Portion of an imaginary event table</span>
|
|
BEGIN_EVENT_TABLE(MyForm, wxFrame)
|
|
|
|
...
|
|
|
|
<span class="comment">// This occurs when a property value changes</span>
|
|
EVT_PG_CHANGED( PGID, MyForm::OnPropertyGridChange )
|
|
|
|
...
|
|
|
|
END_EVENT_TABLE()
|
|
|
|
void MyForm::OnPropertyGridChange( <a class="code" href="classwxPropertyGridEvent.htm" title="A propertygrid event holds information about events associated with wxPropertyGrid...">wxPropertyGridEvent</a>& event )
|
|
{
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a> *<span class="keyword">property</span> = <span class="keyword">event</span>.GetProperty();
|
|
|
|
<span class="comment">// It may be NULL</span>
|
|
<span class="keywordflow">if</span> ( !property )
|
|
<span class="keywordflow">return</span>;
|
|
|
|
<span class="comment">// Get name of changed property</span>
|
|
<span class="keyword">const</span> wxString& name = <span class="keyword">property</span>->GetName();
|
|
|
|
<span class="comment">// Get resulting value</span>
|
|
wxVariant value = <span class="keyword">property</span>->GetValue();
|
|
}
|
|
</pre></div><p>Another event type you might find useful is EVT_PG_CHANGING, which occurs just prior property value is being changed by user. You can acquire pending value using <a class="el" href="classwxPropertyGridEvent.htm#afeb48e91fd83623287164096ba97e1ac" title="Returns value that is about to be set for wxEVT_PG_CHANGING.">wxPropertyGridEvent::GetValue()</a>, and if it is not acceptable, call <a class="el" href="classwxPropertyGridEvent.htm#a5e35bf2aeaad48147c0270e9b04426c8" title="Call this from your event handler to veto action that the event is signaling.">wxPropertyGridEvent::Veto()</a> to prevent the value change from taking place.</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// Portion of an imaginary event table</span>
|
|
BEGIN_EVENT_TABLE(MyForm, wxFrame)
|
|
|
|
...
|
|
|
|
<span class="comment">// This occurs when a property value changes</span>
|
|
EVT_PG_CHANGING( PGID, MyForm::OnPropertyGridChanging )
|
|
|
|
...
|
|
|
|
END_EVENT_TABLE()
|
|
|
|
void MyForm::OnPropertyGridChanging( <a class="code" href="classwxPropertyGridEvent.htm" title="A propertygrid event holds information about events associated with wxPropertyGrid...">wxPropertyGridEvent</a>& event )
|
|
{
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* <span class="keyword">property</span> = <span class="keyword">event</span>.GetProperty();
|
|
|
|
<span class="keywordflow">if</span> ( property == m_pWatchThisProperty )
|
|
{
|
|
<span class="comment">// GetValue() returns the pending value, but is only</span>
|
|
<span class="comment">// supported by wxEVT_PG_CHANGING.</span>
|
|
<span class="keywordflow">if</span> ( event.GetValue().GetString() == g_pThisTextIsNotAllowed )
|
|
{
|
|
<span class="keyword">event</span>.Veto();
|
|
<span class="keywordflow">return</span>;
|
|
}
|
|
}
|
|
}
|
|
</pre></div><dl class="remark"><dt><b>Remarks:</b></dt><dd>On Sub-property Event Handling<ul>
|
|
<li>For aggregate type properties (<a class="el" href="classwxFontProperty.htm" title="Property representing wxFont.">wxFontProperty</a>, <a class="el" href="classwxFlagsProperty.htm" title="Represents a bit set that fits in a long integer.">wxFlagsProperty</a>, etc), events occur for the main parent property only. For other properties events occur for the children themselves..</li>
|
|
</ul>
|
|
</dd></dl>
|
|
<ul>
|
|
<li>When property's child gets changed, you can use wxPropertyGridEvent::GetMainParent to obtain its topmost non-category parent (useful, if you have deeply nested properties).</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="validating">
|
|
Validating Property Values</a></h2>
|
|
<p>There are various ways to make sure user enters only correct values. First, you can use wxValidators similar to as you would with ordinary controls. Use <a class="el" href="classwxPropertyGridInterface.htm#ad83fe8ad87751101316345a14133c45f" title="Sets validator of a property.">wxPropertyGridInterface::SetPropertyValidator()</a> to assign wxValidator to property.</p>
|
|
<p>Second, you can subclass a property and override <a class="el" href="classwxPGProperty.htm#a2e0c041aa3e19a5934a02c65b53f9f7d" title="Implement this function in derived class to check the value.">wxPGProperty::ValidateValue()</a>, or handle wxEVT_PG_CHANGING for the same effect. Both of these methods do not actually prevent user from temporarily entering invalid text, but they do give you an opportunity to warn the user and block changed value from being committed in a property.</p>
|
|
<p>Various validation failure options can be controlled globally with <a class="el" href="classwxPropertyGridInterface.htm#ade72c97a047aa409dc7429010f640bb6" title="Adjusts how wxPropertyGrid behaves when invalid value is entered in a property.">wxPropertyGrid::SetValidationFailureBehavior()</a>, or on an event basis by calling wxEvent::SetValidationFailureBehavior(). Here's a code snippet of how to handle wxEVT_PG_CHANGING, and to set custom failure behaviour and message.</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="keywordtype">void</span> MyFrame::OnPropertyGridChanging(<a class="code" href="classwxPropertyGridEvent.htm" title="A propertygrid event holds information about events associated with wxPropertyGrid...">wxPropertyGridEvent</a>& event)
|
|
{
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* <span class="keyword">property</span> = <span class="keyword">event</span>.GetProperty();
|
|
|
|
<span class="comment">// You must use wxPropertyGridEvent::GetValue() to access</span>
|
|
<span class="comment">// the value to be validated.</span>
|
|
wxVariant pendingValue = <span class="keyword">event</span>.GetValue();
|
|
|
|
<span class="keywordflow">if</span> ( property->GetName() == wxT(<span class="stringliteral">"Font"</span>) )
|
|
{
|
|
<span class="comment">// Make sure value is not unspecified</span>
|
|
<span class="keywordflow">if</span> ( !pendingValue.IsNull() )
|
|
{
|
|
wxFont font << pendingValue;
|
|
|
|
<span class="comment">// Let's just allow Arial font</span>
|
|
<span class="keywordflow">if</span> ( font.GetFaceName() != wxT(<span class="stringliteral">"Arial"</span>) )
|
|
{
|
|
<span class="keyword">event</span>.Veto();
|
|
<span class="keyword">event</span>.SetValidationFailureBehavior(<a class="code" href="group__vfbflags.htm#gga509a11f37ea5e56864e257cde913035ead2d679dfb2b9d9b7b3a0bedd130599c7" title="Prevents user from leaving property unless value is valid.">wxPG_VFB_STAY_IN_PROPERTY</a> |
|
|
<a class="code" href="group__vfbflags.htm#gga509a11f37ea5e56864e257cde913035ea8a5434967b7ab365106699c8b8eb729b" title="Calls wxBell() on validation failure.">wxPG_VFB_BEEP</a> |
|
|
<a class="code" href="group__vfbflags.htm#gga509a11f37ea5e56864e257cde913035ea08faa22272068c52db70546cb7f81334" title="Display a customizable text message explaining the situation.">wxPG_VFB_SHOW_MESSAGE</a>);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</pre></div><h2><a class="anchor" id="cellrender">
|
|
Customizing Individual Cell Appearance</a></h2>
|
|
<p>You can control text colour, background colour, and attached image of each cell in the property grid. Use <a class="el" href="classwxPropertyGridInterface.htm#afd6721e817062d6c9dbb522334c029a0" title="Sets text, bitmap, and colours for given column's cell.">wxPropertyGridInterface::SetPropertyCell()</a> or <a class="el" href="classwxPGProperty.htm#a9ff7ee5a218d9e1f9a3d44c8246e4d5e" title="Sets cell information for given column.">wxPGProperty::SetCell()</a> for this purpose.</p>
|
|
<p>In addition, it is possible to control these characteristics for <a class="el" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a> list items. See wxPGChoices::Item() and <a class="el" href="classwxPGChoiceEntry.htm" title="Attributes of a single wxPGChoices choice.">wxPGChoiceEntry</a> class reference for more info.</p>
|
|
<h2><a class="anchor" id="customizing">
|
|
Customizing Properties (without sub-classing)</a></h2>
|
|
<p>In this section are presented miscellaneous ways to have custom appearance and behavior for your properties without all the necessary hassle of sub-classing a property class etc.</p>
|
|
<h3><a class="anchor" id="customimage">
|
|
Setting Value Image</a></h3>
|
|
<p>Every property can have a small value image placed in front of the actual value text. Built-in example of this can be seen with <a class="el" href="classwxColourProperty.htm">wxColourProperty</a> and <a class="el" href="classwxImageFileProperty.htm" title="Property representing image file(name).">wxImageFileProperty</a>, but for others it can be set using <a class="el" href="classwxPropertyGridInterface.htm#a88befed8aa91d5c6e62844da2166bb3c" title="Set wxBitmap in front of the value.">wxPropertyGrid::SetPropertyImage</a> method.</p>
|
|
<h3><a class="anchor" id="customvalidator">
|
|
Setting Validator</a></h3>
|
|
<p>You can set wxValidator for a property using <a class="el" href="classwxPropertyGridInterface.htm#ad83fe8ad87751101316345a14133c45f" title="Sets validator of a property.">wxPropertyGrid::SetPropertyValidator</a>.</p>
|
|
<p>Validator will work just like in wxWidgets (ie. editorControl->SetValidator(validator) is called).</p>
|
|
<h3><a class="anchor" id="customeditor">
|
|
Setting Property's Editor Control(s)</a></h3>
|
|
<p>You can set editor control (or controls, in case of a control and button), of any property using <a class="el" href="classwxPropertyGridInterface.htm#aff961af9dd2787fb97f510ea5ce46407" title="Sets editor control of a property.">wxPropertyGrid::SetPropertyEditor</a>. Editors are passed using wxPG_EDITOR(EditorName) macro, and valid built-in EditorNames are TextCtrl, Choice, ComboBox, CheckBox, TextCtrlAndButton, ChoiceAndButton, SpinCtrl, and DatePickerCtrl. Two last mentioned ones require call to static member function <a class="el" href="classwxPropertyGridInterface.htm#a330dc911b08378e967955f8a6a938612" title="Initializes additional property editors (SpinCtrl etc.">wxPropertyGrid::RegisterAdditionalEditors()</a>.</p>
|
|
<p>Following example changes wxColourProperty's editor from default Choice to TextCtrlAndButton. <a class="el" href="classwxColourProperty.htm">wxColourProperty</a> has its internal event handling set up so that button click events of the button will be used to trigger colour selection dialog.</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGId</a> colProp = pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>(<a class="code" href="classwxColourProperty.htm">wxColourProperty</a>(wxT(<span class="stringliteral">"Text Colour"</span>)));
|
|
|
|
pg-><a class="code" href="classwxPropertyGridInterface.htm#aff961af9dd2787fb97f510ea5ce46407" title="Sets editor control of a property.">SetPropertyEditor</a>(colProp,wxPG_EDITOR(TextCtrlAndButton));
|
|
</pre></div><p>Naturally, creating and setting custom editor classes is a possibility as well. For more information, see <a class="el" href="classwxPGEditor.htm" title="Base for property editor classes.">wxPGEditor</a> class reference.</p>
|
|
<h3><a class="anchor" id="editorattrs">
|
|
Property Attributes Recognized by Editors</a></h3>
|
|
<p><b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step", "Wrap" and "MotionSpin" attributes.</p>
|
|
<h3><a class="anchor" id="multiplebuttons">
|
|
Adding Multiple Buttons Next to an Editor</a></h3>
|
|
<p>See <a class="el" href="classwxPGMultiButton.htm" title="This class can be used to have multiple buttons in a property editor.">wxPGMultiButton</a> class reference.</p>
|
|
<h3><a class="anchor" id="customeventhandling">
|
|
Handling Events Passed from Properties</a></h3>
|
|
<p><b>wxEVT_COMMAND_BUTTON_CLICKED </b>(corresponds to event table macro EVT_BUTTON): Occurs when editor button click is not handled by the property itself (as is the case, for example, if you set property's editor to TextCtrlAndButton from the original TextCtrl).</p>
|
|
<h3><a class="anchor" id="attributes">
|
|
Property Attributes</a></h3>
|
|
<p>Miscellaneous values, often specific to a property type, can be set using <a class="el" href="classwxPropertyGridInterface.htm#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute of a property.">wxPropertyGrid::SetPropertyAttribute</a> and <a class="el" href="classwxPropertyGrid.htm#a8c6328a5c09549ccfe9756fafe5065da" title="Sets property attribute for all applicapple properties.">wxPropertyGrid::SetPropertyAttributeAll</a> methods.</p>
|
|
<p>Attribute names are strings and values wxVariant. Arbitrary names are allowed inorder to store user values. Constant equivalents of all attribute string names are provided. Some of them are defined as cached strings, so using constants can provide for smaller binary size.</p>
|
|
<p>For complete list of attributes, see <a class="el" href="group__attrids.htm">Property Attributes</a>.</p>
|
|
<h3><a class="anchor" id="boolcheckbox">
|
|
Setting wxBoolProperties to Use Check Box</a></h3>
|
|
<p>To have all wxBoolProperties to use CheckBox editor instead of Choice, use following (call after bool properties have been added):</p>
|
|
<div class="fragment"><pre class="fragment"> pg-><a class="code" href="classwxPropertyGrid.htm#a8c6328a5c09549ccfe9756fafe5065da" title="Sets property attribute for all applicapple properties.">SetPropertyAttributeAll</a>(<a class="code" href="group__attrids.htm#ga9e92f4867bf9fbc7c71779c74d18ccd1" title="wxBoolProperty specific, int, default 0.">wxPG_BOOL_USE_CHECKBOX</a>,<span class="keyword">true</span>);
|
|
</pre></div><h2><a class="anchor" id="usage2">
|
|
Using wxPropertyGridManager</a></h2>
|
|
<p><a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a> is an efficient multi-page version of <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>, which can optionally have toolbar for mode and page selection, and a help text box.</p>
|
|
<p><a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a> inherits from <a class="el" href="classwxPropertyGridInterface.htm" title="In order to have most same base methods, both wxPropertyGrid and wxPropertyGridManager...">wxPropertyGridInterface</a>, and as such it has most property manipulation functions. However, only some of them affect properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some (eg. Append()) only apply to the currently selected page.</p>
|
|
<p>To operate explicitly on properties on specific page, use <a class="el" href="classwxPropertyGridManager.htm#a7deaa866fbf87e6880c0564e4582f54e" title="Returns page object for given page index.">wxPropertyGridManager::GetPage()</a> to obtain pointer to page's <a class="el" href="classwxPropertyGridPage.htm" title="Holder of property grid page information.">wxPropertyGridPage</a> object.</p>
|
|
<p>Visual methods, such as SetCellBackgroundColour and GetNextVisible are only available in <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>. Use <a class="el" href="classwxPropertyGridManager.htm#aa0c62e680e94493dabdf40ab4642fef6" title="Returns pointer to the contained wxPropertyGrid.">wxPropertyGridManager::GetGrid()</a> to obtain pointer to it.</p>
|
|
<p>Iteration methods will not work in <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a>. Instead, you must acquire the internal grid (GetGrid()) or <a class="el" href="classwxPropertyGridPage.htm" title="Holder of property grid page information.">wxPropertyGridPage</a> object (GetPage()).</p>
|
|
<p><a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a> constructor has exact same format as <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> constructor, and basicly accepts same extra window style flags (albeit also has some extra ones).</p>
|
|
<p>Here's some example code for creating and populating a <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a>:</p>
|
|
<div class="fragment"><pre class="fragment"> <a class="code" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a>* pgMan = <span class="keyword">new</span> <a class="code" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a>(<span class="keyword">this</span>, PGID,
|
|
wxDefaultPosition, wxDefaultSize,
|
|
<span class="comment">// These and other similar styles are automatically</span>
|
|
<span class="comment">// passed to the embedded wxPropertyGrid.</span>
|
|
<a class="code" href="group__wndflags.htm#gga967b646b15085e115051d83a65ffdfe8a9b4250bcee1b0c651e9b76b3b88bd68a" title="Modified values are shown in bold font.">wxPG_BOLD_MODIFIED</a>|<a class="code" href="group__wndflags.htm#gga967b646b15085e115051d83a65ffdfe8a998b9d55c606adb1010be7438286e3c5" title="Using this style, the column splitters move automatically based on column proportions...">wxPG_SPLITTER_AUTO_CENTER</a>|
|
|
<span class="comment">// Include toolbar.</span>
|
|
<a class="code" href="group__wndflags.htm#gga967b646b15085e115051d83a65ffdfe8a4c708718b58d1b4b61a8bb23be022ec4" title="wxPropertyGridManager only: Show toolbar for mode and page selection.">wxPG_TOOLBAR</a> |
|
|
<span class="comment">// Include description box.</span>
|
|
<a class="code" href="group__wndflags.htm#gga967b646b15085e115051d83a65ffdfe8ae7a176f7037ce590e834bf62659a8326" title="wxPropertyGridManager only: Show adjustable text box showing description or help...">wxPG_DESCRIPTION</a> |
|
|
<span class="comment">// Include compactor.</span>
|
|
wxPG_COMPACTOR |
|
|
<span class="comment">// Plus defaults.</span>
|
|
<a class="code" href="group__wndflags.htm#ga422babdd5ce8058435ed638fd1c486b0" title="Combines various styles.">wxPGMAN_DEFAULT_STYLE</a>
|
|
);
|
|
|
|
<a class="code" href="classwxPropertyGridPage.htm" title="Holder of property grid page information.">wxPropertyGridPage</a>* page;
|
|
|
|
pgMan-><a class="code" href="classwxPropertyGridManager.htm#aed7ea6d2c2a8c4df915cc3d2525f2aa4" title="Creates new property page.">AddPage</a>(wxT(<span class="stringliteral">"First Page"</span>));
|
|
page = pgMan-><a class="code" href="classwxPropertyGridManager.htm#a684c98df6dbeb2c57951ec310581f46b" title="Returns last page.">GetLastPage</a>();
|
|
|
|
page-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxPropertyCategory.htm" title="Category (caption) property.">wxPropertyCategory</a>(wxT(<span class="stringliteral">"Category A1"</span>)) );
|
|
|
|
page-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>(wxT(<span class="stringliteral">"Number"</span>),wxPG_LABEL,1) );
|
|
|
|
page-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxColourProperty.htm">wxColourProperty</a>(wxT(<span class="stringliteral">"Colour"</span>),wxPG_LABEL,*wxWHITE) );
|
|
|
|
pgMan-><a class="code" href="classwxPropertyGridManager.htm#aed7ea6d2c2a8c4df915cc3d2525f2aa4" title="Creates new property page.">AddPage</a>(wxT(<span class="stringliteral">"Second Page"</span>));
|
|
page = pgMan-><a class="code" href="classwxPropertyGridManager.htm#a684c98df6dbeb2c57951ec310581f46b" title="Returns last page.">GetLastPage</a>();
|
|
|
|
page-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( wxT(<span class="stringliteral">"Text"</span>),wxPG_LABEL,wxT(<span class="stringliteral">"(no text)"</span>) );
|
|
|
|
page-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> <a class="code" href="classwxFontProperty.htm" title="Property representing wxFont.">wxFontProperty</a>(wxT(<span class="stringliteral">"Font"</span>),wxPG_LABEL) );
|
|
</pre></div><h3><a class="anchor" id="propgridpage">
|
|
wxPropertyGridPage</a></h3>
|
|
<p><a class="el" href="classwxPropertyGridPage.htm" title="Holder of property grid page information.">wxPropertyGridPage</a> is holder of properties for one page in manager. It is derived from wxEvtHandler, so you can subclass it to process page-specific property grid events. Hand over your page instance in <a class="el" href="classwxPropertyGridManager.htm#aed7ea6d2c2a8c4df915cc3d2525f2aa4" title="Creates new property page.">wxPropertyGridManager::AddPage</a>.</p>
|
|
<p>Please note that the <a class="el" href="classwxPropertyGridPage.htm" title="Holder of property grid page information.">wxPropertyGridPage</a> itself only sports subset of <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> API (but unlike manager, this include item iteration). Naturally it inherits from wxPropertyGridMethods and <a class="el" href="classwxPropertyGridState.htm" title="Contains information of a single wxPropertyGrid page.">wxPropertyGridState</a>.</p>
|
|
<h2><a class="anchor" id="subclassing">
|
|
Subclassing wxPropertyGrid and wxPropertyGridManager</a></h2>
|
|
<p>Few things to note:</p>
|
|
<ul>
|
|
<li>Only a small percentage of member functions are virtual. If you need more, just let me know.</li>
|
|
</ul>
|
|
<ul>
|
|
<li>Data manipulation is done in <a class="el" href="classwxPropertyGridState.htm" title="Contains information of a single wxPropertyGrid page.">wxPropertyGridState</a> class. So, instead of overriding <a class="el" href="classwxPropertyGridInterface.htm#abf342b34022630c15038c9d7679d3c57" title="Inserts property to the property container.">wxPropertyGrid::Insert</a>, you'll probably want to override <a class="el" href="classwxPropertyGridState.htm#a593a560502e02feed55e339bda89af27" title="Override this member function to add custom behavior on property insertion.">wxPropertyGridState::DoInsert</a>.</li>
|
|
</ul>
|
|
<ul>
|
|
<li>Override <a class="el" href="classwxPropertyGrid.htm#ac75d3bf6a0e32c5526af8924a657da89" title="wxPropertyGridState used by the grid is created here.">wxPropertyGrid::CreateState</a> to instantiate your derivate <a class="el" href="classwxPropertyGridState.htm" title="Contains information of a single wxPropertyGrid page.">wxPropertyGridState</a>. For <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a>, you'll need to subclass <a class="el" href="classwxPropertyGridPage.htm" title="Holder of property grid page information.">wxPropertyGridPage</a> instead (since it is derived from <a class="el" href="classwxPropertyGridState.htm" title="Contains information of a single wxPropertyGrid page.">wxPropertyGridState</a>), and hand over instances in <a class="el" href="classwxPropertyGridManager.htm#aed7ea6d2c2a8c4df915cc3d2525f2aa4" title="Creates new property page.">wxPropertyGridManager::AddPage</a> calls.</li>
|
|
</ul>
|
|
<ul>
|
|
<li>You can use a derivate <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> with manager by overriding <a class="el" href="classwxPropertyGridManager.htm#a6980326efa2bfc466aa9a5bbead7fe8c" title="Creates property grid for the manager.">wxPropertyGridManager::CreatePropertyGrid</a> member function. However, if you you do this, then you must also use two-step construction (ie. default constructor and Create() instead of just constructor with arguments) when creating the manager.</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="misc">
|
|
Miscellaneous Topics</a></h2>
|
|
<h3><a class="anchor" id="namescope">
|
|
Property Name Scope</a></h3>
|
|
<p>All properties which parent is category or root can be accessed directly by their base name (ie. name given for property in its constructor). Other properties can be accessed via "ParentsName.BaseName" notation, Naturally, all property names should be unique.</p>
|
|
<h3><a class="anchor" id="nonuniquelabels">
|
|
Non-unique Labels</a></h3>
|
|
<p>It is possible to have properties with identical label under same parent. However, care must be taken to ensure that each property still has unique (base) name.</p>
|
|
<h3><a class="anchor" id="boolproperty">
|
|
wxBoolProperty</a></h3>
|
|
<p>There are few points about <a class="el" href="classwxBoolProperty.htm" title="Basic property with boolean value.">wxBoolProperty</a> that require futher discussion:</p>
|
|
<ul>
|
|
<li><a class="el" href="classwxBoolProperty.htm" title="Basic property with boolean value.">wxBoolProperty</a> can be shown as either normal combobox or as a checkbox. Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this. For example, if you have a <a class="el" href="classwxFlagsProperty.htm" title="Represents a bit set that fits in a long integer.">wxFlagsProperty</a>, you can set its all items to use check box using the following: <div class="fragment"><pre class="fragment"> pg-><a class="code" href="classwxPropertyGridInterface.htm#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute of a property.">SetPropertyAttribute</a>(wxT(<span class="stringliteral">"MyFlagsProperty"</span>),<a class="code" href="group__attrids.htm#ga9e92f4867bf9fbc7c71779c74d18ccd1" title="wxBoolProperty specific, int, default 0.">wxPG_BOOL_USE_CHECKBOX</a>,<span class="keyword">true</span>,wxPG_RECURSE);
|
|
</pre></div></li>
|
|
</ul>
|
|
<ul>
|
|
<li>Default item names for <a class="el" href="classwxBoolProperty.htm" title="Basic property with boolean value.">wxBoolProperty</a> are [wxT("False"),wxT("True")]. This can be changed using wxPropertyGrid::SetBoolChoices(trueChoice,falseChoice).</li>
|
|
</ul>
|
|
<h3><a class="anchor" id="textctrlupdates">
|
|
Updates from wxTextCtrl Based Editor</a></h3>
|
|
<p>Changes from wxTextCtrl based property editors are committed (ie. wxEVT_PG_CHANGED is sent etc.) *only* when (1) user presser enter, (2) user moves to edit another property, or (3) when focus leaves the grid.</p>
|
|
<p>Because of this, you may find it useful, in some apps, to call <a class="el" href="classwxPropertyGrid.htm#a6e06d92a622237457fea00372df1eaae" title="Forces updating the value of property from the editor control.">wxPropertyGrid::CommitChangesFromEditor()</a> just before you need to do any computations based on property grid values. Note that CommitChangesFromEditor() will dispatch wxEVT_PG_CHANGED with ProcessEvent, so any of your event handlers will be called immediately.</p>
|
|
<h3><a class="anchor" id="splittercentering">
|
|
Centering the Splitter</a></h3>
|
|
<p>If you need to center the splitter, but only once when the program starts, then do <b>not</b> use the wxPG_SPLITTER_AUTO_CENTER window style, but the <a class="el" href="classwxPropertyGrid.htm#a6803d445ae77514558ec4ad00a25f65a" title="Centers the splitter.">wxPropertyGrid::CenterSplitter()</a> method. <b>However, be sure to call it after the sizer setup and SetSize calls!</b> (ie. usually at the end of the frame/dialog constructor)</p>
|
|
<p>Splitter centering behavior can be customized using <a class="el" href="classwxPropertyGridInterface.htm#a5df440361d9e85f3a48d79d7b45667e1" title="Set proportion of a auto-stretchable column.">wxPropertyGridInterface::SetColumnProportion()</a>. Usually it is used to set non-equal column proportions, which in essence stops the splitter(s) no longer being 'centered' as such.</p>
|
|
<h3><a class="anchor" id="splittersetting">
|
|
Setting Splitter Position When Creating Property Grid</a></h3>
|
|
<p>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.</p>
|
|
<h3><a class="anchor" id="Making">
|
|
property labels editable</a></h3>
|
|
<p>Normally only the second column (i.e. the one at column index 1) is editable by user. However, you can make any column editable by calling wxPropertyGrid::MakeColumnEditable(index). For instance, calling that function with index 0 you can make property labels editable.</p>
|
|
<p>Events wxEVT_PG_LABEL_EDIT_BEGIN and wxEVT_PG_LABEL_EDIT_ENDING are generated as appropriate. You can veto these events to prevent label editor from (dis)appearing.</p>
|
|
<h3><a class="anchor" id="colourproperty">
|
|
wxColourProperty and wxSystemColourProperty</a></h3>
|
|
<p>Through subclassing, these two property classes provide substantial customization features. Subclass <a class="el" href="classwxSystemColourProperty.htm" title="Has dropdown list of wxWidgets system colours.">wxSystemColourProperty</a> if you want to use <a class="el" href="classwxColourPropertyValue.htm" title="Because text, background and other colours tend to differ between platforms, wxSystemColourProperty...">wxColourPropertyValue</a> (which features colour type in addition to wxColour), and <a class="el" href="classwxColourProperty.htm">wxColourProperty</a> if plain wxColour is enough.</p>
|
|
<p>Override <a class="el" href="classwxSystemColourProperty.htm#a6e71b47f3ab9b9393b840f472ee272ca" title="Override in derived class to customize how colours are printed as strings.">wxSystemColourProperty::ColourToString()</a> to redefine how colours are printed as strings.</p>
|
|
<p>Override <a class="el" href="classwxSystemColourProperty.htm#af462285f69372e4f8408963e826d691f" title="Returns index of entry that triggers colour picker dialog (default is last).">wxSystemColourProperty::GetCustomColourIndex()</a> to redefine location of the item that triggers colour picker dialog (default is last).</p>
|
|
<p>Override <a class="el" href="classwxSystemColourProperty.htm#ae5bc6d37153b260d99f790867df6e088" title="Default is to use wxSystemSettings::GetColour(index).">wxSystemColourProperty::GetColour()</a> to determine which colour matches which choice entry.</p>
|
|
<h3><a class="anchor" id="compilerdefines">
|
|
Supported Preprocessor Defines</a></h3>
|
|
<p>Here is list of supported preprocessor defines (other than those that relate with wxWidgets core library):</p>
|
|
<p><b>wxPG_INCLUDE_MANAGER:</b> Defines as 0 to exclude <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a> from compilation.</p>
|
|
<p><b>wxPG_INCLUDE_ADVPROPS:</b> Defines as 0 to exclude properties and editors defined in advprops.h and advprops.cpp.</p>
|
|
<p><b>wxPG_USE_WXMODULE:</b> Define as 0 to not use wxModule to manage global variables. This may be needed in cases where <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> is linked as a plugin DLL, or when <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> is linked statically in a DLL.</p>
|
|
<p><b>WXMAKINGLIB_PROPGRID:</b> Define if you are linking <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> statically but wxWidgets itself is DLL.</p>
|
|
<p><b>WXMAKINGDLL_PROPGRID:</b> Define when building <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> as a DLL. This should be automatically defined correctly by the Bakefile-generated makefiles.</p>
|
|
<p><b>wxPG_USE_STL:</b> Define as 1 to let <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> use STL classes in API as much as possible. Default value equals wxUSE_STL.</p>
|
|
<p><b>wxPG_COMPATIBILITY_1_2_0:</b> Define as 1 to make <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> more compatible with the old 1.2.x releases.</p>
|
|
<p><b>wxPG_COMPATIBILITY_1_0_0:</b> Define to make <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> more compatible with the old 1.0.x releases.</p>
|
|
<h2><a class="anchor" id="proplist">
|
|
Property Class Descriptions</a></h2>
|
|
<p>Here are descriptions of built-in properties, with attributes (see <a class="el" href="classwxPropertyGridInterface.htm#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute of a property.">wxPropertyGrid::SetPropertyAttribute</a>) that apply to them. Note that not all attributes are necessarily here. For complete list, see <a class="el" href="group__attrids.htm">Property Attributes</a>.</p>
|
|
<h3><a class="anchor" id="wxPropertyCategory">
|
|
wxPropertyCategory</a></h3>
|
|
<p>Not an actual property per se, but a header for a group of properties.</p>
|
|
<h3><a class="anchor" id="wxStringProperty">
|
|
wxStringProperty</a></h3>
|
|
<p><b>Inheritable Class:</b> <a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a></p>
|
|
<p>Simple string property. wxPG_STRING_PASSWORD attribute may be used to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.</p>
|
|
<dl class="remark"><dt><b>Remarks:</b></dt><dd><a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a> has a special trait: if it has value of "<composed>", and also has child properties, then its displayed value becomes composition of child property values, similar as with <a class="el" href="classwxFontProperty.htm" title="Property representing wxFont.">wxFontProperty</a>, for instance.</dd></dl>
|
|
<h3><a class="anchor" id="wxIntProperty">
|
|
wxIntProperty</a></h3>
|
|
<p>Like <a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>, but converts text to a signed long integer. <a class="el" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a> seemlessly supports 64-bit integers (ie. wxLongLong).</p>
|
|
<h3><a class="anchor" id="wxUIntProperty">
|
|
wxUIntProperty</a></h3>
|
|
<p>Like <a class="el" href="classwxIntProperty.htm" title="Basic property with integer value.">wxIntProperty</a>, but displays value as unsigned int. To set the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute. To set the globally used base, manipulate wxPG_UINT_BASE int attribute. Regardless of current prefix, understands (hex) values starting with both "0x" and "$". <a class="el" href="classwxUIntProperty.htm" title="Basic property with unsigned integer value.">wxUIntProperty</a> seemlessly supports 64-bit unsigned integers (ie. wxULongLong).</p>
|
|
<h3><a class="anchor" id="wxFloatProperty">
|
|
wxFloatProperty</a></h3>
|
|
<p>Like <a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>, but converts text to a double-precision floating point. Default float-to-text precision is 6 decimals, but this can be changed by modifying wxPG_FLOAT_PRECISION attribute.</p>
|
|
<h3><a class="anchor" id="wxBoolProperty">
|
|
wxBoolProperty</a></h3>
|
|
<p>Represents a boolean value. wxChoice is used as editor control, by the default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use check box instead.</p>
|
|
<h3><a class="anchor" id="wxLongStringProperty">
|
|
wxLongStringProperty</a></h3>
|
|
<p>Like <a class="el" href="classwxStringProperty.htm" title="Basic property with string value.">wxStringProperty</a>, but has a button that triggers a small text editor dialog.</p>
|
|
<h3><a class="anchor" id="wxDirProperty">
|
|
wxDirProperty</a></h3>
|
|
<p>Like <a class="el" href="classwxLongStringProperty.htm" title="Like wxStringProperty, but has a button that triggers a small text editor dialog...">wxLongStringProperty</a>, but the button triggers dir selector instead.</p>
|
|
<h3><a class="anchor" id="wxFileProperty">
|
|
wxFileProperty</a></h3>
|
|
<p>Like <a class="el" href="classwxLongStringProperty.htm" title="Like wxStringProperty, but has a button that triggers a small text editor dialog...">wxLongStringProperty</a>, but the button triggers file selector instead. Default wildcard is "All files..." but this can be changed by setting wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details). Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show only the filename, not the entire path.</p>
|
|
<h3><a class="anchor" id="wxEnumProperty">
|
|
wxEnumProperty</a></h3>
|
|
<p>Represents a single selection from a list of choices - custom combobox control is used to edit the value.</p>
|
|
<h3><a class="anchor" id="wxFlagsProperty">
|
|
wxFlagsProperty</a></h3>
|
|
<p>Represents a bit set that fits in a long integer. <a class="el" href="classwxBoolProperty.htm" title="Basic property with boolean value.">wxBoolProperty</a> sub-properties are created for editing individual bits. Textctrl is created to manually edit the flags as a text; a continous sequence of spaces, commas and semicolons is considered as a flag id separator. <b>Note: </b> When changing "choices" (ie. flag labels) of <a class="el" href="classwxFlagsProperty.htm" title="Represents a bit set that fits in a long integer.">wxFlagsProperty</a>, you will need to use SetPropertyChoices - otherwise they will not get updated properly.</p>
|
|
<h3><a class="anchor" id="wxArrayStringProperty">
|
|
wxArrayStringProperty</a></h3>
|
|
<p>Allows editing of a list of strings in wxTextCtrl and in a separate dialog.</p>
|
|
<h3><a class="anchor" id="wxDateProperty">
|
|
wxDateProperty</a></h3>
|
|
<p>wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl should work as well. wxPG_DATE_FORMAT attribute can be used to change string wxDateTime::Format uses (altough default is recommended as it is locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY; specifying wxDP_ALLOWNONE enables better support for unspecified property value).</p>
|
|
<h3><a class="anchor" id="wxEditEnumProperty">
|
|
wxEditEnumProperty</a></h3>
|
|
<p>Represents a string that can be freely edited or selected from list of choices - custom combobox control is used to edit the value.</p>
|
|
<h3><a class="anchor" id="wxMultiChoiceProperty">
|
|
wxMultiChoiceProperty</a></h3>
|
|
<p>Allows editing a multiple selection from a list of strings. This is property is pretty much built around concept of wxMultiChoiceDialog. It uses wxArrayString value.</p>
|
|
<h3><a class="anchor" id="wxImageFileProperty">
|
|
wxImageFileProperty</a></h3>
|
|
<p>Like <a class="el" href="classwxFileProperty.htm" title="Like wxLongStringProperty, but the button triggers file selector instead.">wxFileProperty</a>, but has thumbnail of the image in front of the filename and autogenerates wildcard from available image handlers.</p>
|
|
<h3><a class="anchor" id="wxColourProperty">
|
|
wxColourProperty</a></h3>
|
|
<p><b>Useful alternate editor:</b> Choice.</p>
|
|
<p>Represents wxColour. wxButton is used to trigger a colour picker dialog.</p>
|
|
<h3><a class="anchor" id="wxFontProperty">
|
|
wxFontProperty</a></h3>
|
|
<p>Represents wxFont. Various sub-properties are used to edit individual subvalues.</p>
|
|
<h3><a class="anchor" id="wxSystemColourProperty">
|
|
wxSystemColourProperty</a></h3>
|
|
<p>Represents wxColour and a system colour index. wxChoice is used to edit the value. Drop-down list has color images.</p>
|
|
<h3><a class="anchor" id="wxCursorProperty">
|
|
wxCursorProperty</a></h3>
|
|
<p>Represents a wxCursor. wxChoice is used to edit the value. Drop-down list has cursor images under some (wxMSW) platforms.</p>
|
|
<h3><a class="anchor" id="Additional">
|
|
Sample Properties</a></h3>
|
|
<p>Sample application has following additional examples of custom properties:</p>
|
|
<ul>
|
|
<li>wxFontDataProperty ( edits wxFontData )</li>
|
|
<li>wxPointProperty ( edits wxPoint )</li>
|
|
<li>wxSizeProperty ( edits wxSize )</li>
|
|
<li>wxAdvImageFileProperty ( like <a class="el" href="classwxImageFileProperty.htm" title="Property representing image file(name).">wxImageFileProperty</a>, but also has a drop-down for recent image selection)</li>
|
|
<li>wxDirsProperty ( edits a wxArrayString consisting of directory strings)</li>
|
|
<li>wxArrayDoubleProperty ( edits wxArrayDouble )</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="userhelp">
|
|
Using wxPropertyGrid control</a></h2>
|
|
<p>This is a short summary of how a <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a> is used (not how it is programmed), or, rather, how it <b>should</b> behave in practice.</p>
|
|
<ul>
|
|
<li>Basic mouse usage is as follows:<br/>
|
|
<ul>
|
|
<li>Clicking property label selects it.</li>
|
|
<li>Clicking property value selects it and focuses to editor control.</li>
|
|
<li>Clicking category label selects the category.</li>
|
|
<li>Double-clicking category label selects the category and expands/collapses it.</li>
|
|
<li>Double-clicking labels of a property with children expands/collapses it.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Following apply if wxPG_EX_MULTIPLE_SELECTION extra window style is used:<br/>
|
|
<ul>
|
|
<li>Clicking property with Shift down will add it to list of selected properties</li>
|
|
<li>Dragging with left mouse button down will select multiple properties.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>Keyboard usage is as follows:<br/>
|
|
<ul>
|
|
<li>alt + down (or right) - displays editor dialog (if any) for a property. Note that this shortcut can be changed using <a class="el" href="classwxPropertyGrid.htm#a523f90a749685d6d97ca247907f1793a" title="Changes keyboard shortcut to push the editor button.">wxPropertyGrid::SetButtonShortcut</a>.<br/>
|
|
Only when editor control is not focused:<br/>
|
|
</li>
|
|
<li>cursor up - moves to previous visible property<br/>
|
|
</li>
|
|
<li>cursor down - moves to next visible property<br/>
|
|
</li>
|
|
<li>cursor left - if collapsible, collapses, otherwise moves to previous property<br/>
|
|
</li>
|
|
<li>cursor right - if expandable, expands, otherwise moves to next property<br/>
|
|
</li>
|
|
<li>tab (if enabled) - focuses keyboard to the editor control of selected property NOTE: This doesn't work at the moment (and is unlikely to be fixed). Same applies to other tab key combos described below.<br/>
|
|
Only when editor control is focused:<br/>
|
|
</li>
|
|
<li>return/enter - confirms changes made to a wxTextCtrl based editor<br/>
|
|
</li>
|
|
<li>tab - moves to next visible property (or, if in last one, moves out of grid)<br/>
|
|
</li>
|
|
<li>shift-tab - moves to previous visible property (or, if in first one, moves out of grid)<br/>
|
|
</li>
|
|
<li>escape - unfocuses from editor control and cancels any changes made (latter for wxTextCtrl based editor only)<br/>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>In long strings tabs are represented by "\t" and line break by "\n".</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="notes">
|
|
Design Notes</a></h2>
|
|
<ul>
|
|
<li>Currently <a class="el" href="classwxPropertyGridManager.htm" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which...">wxPropertyGridManager</a> uses "easy" way to relay events from embedded <a class="el" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>. That is, the exact same id is used for both.</li>
|
|
</ul>
|
|
<ul>
|
|
<li>If wxPG_DOUBLE_BUFFER is 1 (default for MSW, GTK and MAC), wxPropertyGrid::DoDrawItems composes the image on a wxMemoryDC. This effectively eliminates flicker caused by drawing itself (property editor controls are another matter).</li>
|
|
</ul>
|
|
<ul>
|
|
<li>Under wxMSW, flicker freedom when creating native editor controls is achieved by using following undocumented scheme: <div class="fragment"><pre class="fragment"> wxControl* ctrl = <span class="keyword">new</span> wxControl();
|
|
<span class="preprocessor"> #ifdef __WXMSW__</span>
|
|
<span class="preprocessor"></span> ctrl->Hide();
|
|
<span class="preprocessor"> #endif</span>
|
|
<span class="preprocessor"></span> ctrl->Create(parent,<span class="keywordtype">id</span>,...);
|
|
|
|
...further initialize, move, resize, etc...
|
|
|
|
#ifdef __WXMSW__
|
|
ctrl->Show();
|
|
<span class="preprocessor"> #endif</span>
|
|
</pre></div></li>
|
|
</ul>
|
|
<h2><a class="anchor" id="crossplatform">
|
|
Crossplatform Notes (not necessarily wxPropertyGrid specific)</a></h2>
|
|
<ul>
|
|
<li>GTK1: When showing a dialog you may encounter invisible font! Solution: Set parent's font using SetOwnFont instead of SetFont.</li>
|
|
</ul>
|
|
<ul>
|
|
<li>GTK: Your own control can overdraw wxGTK wxWindow border!</li>
|
|
</ul>
|
|
<ul>
|
|
<li>wxWindow::SetSizeHints may be necessary to shrink controls below certain treshold, but only on some platforms. For example wxMSW might allow any shrinking without SetSizeHints call where wxGTK might not.</li>
|
|
</ul>
|
|
<ul>
|
|
<li>GTK Choice (atleast, maybe other controls as well) likes its items set in constructor. Appending them seems to be slower (Freeze+Thaw won't help). Even using Append that gets wxArrayString argument may not be good, since it may just append every string one at a time.</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="newprops">
|
|
Creating New Properties</a></h2>
|
|
<p>Easiest solution for creating an arbitrary property is to subclass an existing, property class that most resembles the intended end result. You may need to include header file wx/propgrid/propdev.h.</p>
|
|
<p>For instance:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <wx/propgrid/propdev.h></span>
|
|
|
|
<span class="comment">//</span>
|
|
<span class="comment">// wxLongStringProperty has wxString as value type and TextCtrlAndButton as editor.</span>
|
|
<span class="comment">// Here we will derive a new property class that will show single choice dialog</span>
|
|
<span class="comment">// on button click.</span>
|
|
<span class="comment">//</span>
|
|
|
|
<span class="keyword">class </span>MyStringProperty : <span class="keyword">public</span> <a class="code" href="classwxLongStringProperty.htm" title="Like wxStringProperty, but has a button that triggers a small text editor dialog...">wxLongStringProperty</a>
|
|
{
|
|
DECLARE_DYNAMIC_CLASS(MyStringProperty)
|
|
public:
|
|
|
|
<span class="comment">// Default constructor</span>
|
|
MyStringProperty() { }
|
|
|
|
<span class="comment">// Normal property constructor.</span>
|
|
MyStringProperty(<span class="keyword">const</span> wxString& label,
|
|
<span class="keyword">const</span> wxString& name = wxPG_LABEL,
|
|
<span class="keyword">const</span> wxString& value = wxEmptyString)
|
|
: <a class="code" href="classwxLongStringProperty.htm" title="Like wxStringProperty, but has a button that triggers a small text editor dialog...">wxLongStringProperty</a>(label, name, value)
|
|
{
|
|
<span class="comment">// Prepare choices</span>
|
|
m_choices.Add(wxT(<span class="stringliteral">"Cat"</span>));
|
|
m_choices.Add(wxT(<span class="stringliteral">"Dog"</span>));
|
|
m_choices.Add(wxT(<span class="stringliteral">"Gibbon"</span>));
|
|
m_choices.Add(wxT(<span class="stringliteral">"Otter"</span>));
|
|
}
|
|
|
|
<span class="comment">// Do something special when button is clicked.</span>
|
|
<span class="keyword">virtual</span> <a class="code" href="classwxPGEditorDialogAdapter.htm" title="Derive a class from this to adapt an existing editor dialog or function to be used...">wxPGEditorDialogAdapter</a>* GetEditorDialog()<span class="keyword"> const</span>
|
|
<span class="keyword"> </span>{
|
|
<span class="keywordflow">return</span> <span class="keyword">new</span> wxSingleChoiceDialogAdapter(m_choices);
|
|
}
|
|
|
|
<span class="keyword">protected</span>:
|
|
<a class="code" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a> m_choices;
|
|
};
|
|
|
|
IMPLEMENT_DYNAMIC_CLASS(MyStringProperty, <a class="code" href="classwxLongStringProperty.htm" title="Like wxStringProperty, but has a button that triggers a small text editor dialog...">wxLongStringProperty</a>)
|
|
|
|
<span class="comment">//</span>
|
|
<span class="comment">// Actually implement the editor dialog adapter</span>
|
|
<span class="comment">// Naturally, in real code this would have to come</span>
|
|
<span class="comment">// before wxPGProperty::GetEditorDialog()</span>
|
|
<span class="comment">// implementation.</span>
|
|
<span class="comment">//</span>
|
|
|
|
class wxSingleChoiceDialogAdapter : public <a class="code" href="classwxPGEditorDialogAdapter.htm" title="Derive a class from this to adapt an existing editor dialog or function to be used...">wxPGEditorDialogAdapter</a>
|
|
{
|
|
<span class="keyword">public</span>:
|
|
|
|
wxSingleChoiceDialogAdapter( <span class="keyword">const</span> <a class="code" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a>& choices )
|
|
: wxPGEditorDialogAdapter(), m_choices(choices)
|
|
{
|
|
}
|
|
|
|
<span class="keyword">virtual</span> <span class="keywordtype">bool</span> DoShowDialog( <a class="code" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>* WXUNUSED(propGrid),
|
|
<a class="code" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* WXUNUSED(property) )
|
|
{
|
|
wxString s = ::wxGetSingleChoice(wxT(<span class="stringliteral">"Message"</span>),
|
|
wxT(<span class="stringliteral">"Caption"</span>),
|
|
m_choices.GetLabels());
|
|
<span class="keywordflow">if</span> ( s.length() )
|
|
{
|
|
SetValue(s);
|
|
<span class="keywordflow">return</span> <span class="keyword">true</span>;
|
|
}
|
|
|
|
<span class="keywordflow">return</span> <span class="keyword">false</span>;
|
|
}
|
|
|
|
<span class="keyword">protected</span>:
|
|
<span class="keyword">const</span> <a class="code" href="classwxPGChoices.htm" title="Helper class for managing choices for properties.">wxPGChoices</a>& m_choices;
|
|
};
|
|
</pre></div><p>You can then create a property instance, for instance:</p>
|
|
<div class="fragment"><pre class="fragment"> pg-><a class="code" href="classwxPropertyGridInterface.htm#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> MyStringProperty(label, name, value) );
|
|
</pre></div><p>If you want to change editor used, use code like below (continues our sample above).</p>
|
|
<p>Note that built-in editors include: TextCtrl, Choice, ComboBox, TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl, and DatePickerCtrl.</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// In class body:</span>
|
|
<span class="keyword">virtual</span> <span class="keyword">const</span> <a class="code" href="classwxPGEditor.htm" title="Base for property editor classes.">wxPGEditor</a>* DoGetEditorClass()<span class="keyword"> const</span>
|
|
<span class="keyword"> </span>{
|
|
<span class="keywordflow">return</span> wxPG_EDITOR(TextCtrl);
|
|
}
|
|
</pre></div><p>You can change the 'value type' of a property by simply assigning different type of variant with SetValue. <b>It is mandatory to implement wxVariantData class for all data types used as property values.</b> Also, it is further recommended to derive your class from <a class="el" href="classwxPGVariantData.htm" title="wxVariantData with additional functionality.">wxPGVariantData</a> (see class documentation for more info).</p>
|
|
<dl class="remark"><dt><b>Remarks:</b></dt><dd><ul>
|
|
<li>For practical examples of arbitrary properties, please take a look at the sample properties in samples/sampleprops.cpp.</li>
|
|
<li>Read <a class="el" href="classwxPGProperty.htm" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a> class documentation to find out what each virtual member function should do.</li>
|
|
<li>Documentation below may be helpful (altough you'd probably do better by looking at the sample properties first).</li>
|
|
</ul>
|
|
</dd></dl>
|
|
<h3><a class="anchor" id="methoda">
|
|
Macro Pairs</a></h3>
|
|
<p>These are quick methods for creating customized properties.</p>
|
|
<h4><a class="anchor" id="custstringprop">
|
|
String Property with Button</a></h4>
|
|
<p>This custom property will be exactly the same as <a class="el" href="classwxLongStringProperty.htm" title="Like wxStringProperty, but has a button that triggers a small text editor dialog...">wxLongStringProperty</a>, except that you can specify a custom code to handle what happens when the button is pressed.</p>
|
|
<p>In header: </p>
|
|
<div class="fragment"><pre class="fragment"> WX_PG_DECLARE_STRING_PROPERTY(PROPNAME)
|
|
</pre></div><p>In source: </p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// FLAGS can be wxPG_NO_ESCAPE if escape sequences shall not be expanded.</span>
|
|
WX_PG_IMPLEMENT_STRING_PROPERTY(PROPNAME, FLAGS)
|
|
|
|
bool PROPNAME::OnButtonClick( <a class="code" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>* propgrid, wxString& value )
|
|
{
|
|
<span class="comment">//</span>
|
|
<span class="comment">// TODO: Show dialog, read initial string from value. If changed,</span>
|
|
<span class="comment">// store new string to value and return TRUE.</span>
|
|
<span class="comment">// NB: You must use wxPGProperty::SetValueInEvent().</span>
|
|
<span class="comment">//</span>
|
|
}
|
|
</pre></div><p>FLAGS is either wxPG_NO_ESCAPE (newlines and tabs are not translated to and from escape sequences) or wxPG_ESCAPE (newlines and tabs are transformed into C-string escapes).</p>
|
|
<p>There is also WX_PG_IMPLEMENT_STRING_PROPERTY_WITH_VALIDATOR variant which also allows setting up a validator for the property. Like this:</p>
|
|
<div class="fragment"><pre class="fragment"> WX_PG_IMPLEMENT_STRING_PROPERTY_WITH_VALIDATOR(PROPNAME, FLAGS)
|
|
|
|
bool PROPNAME::OnButtonClick( <a class="code" href="classwxPropertyGrid.htm" title="wxPropertyGrid is a specialized two-column grid for editing properties such as strings...">wxPropertyGrid</a>* propgrid, wxString& value )
|
|
{
|
|
<span class="comment">//</span>
|
|
<span class="comment">// TODO: Show dialog, read initial string from value. If changed,</span>
|
|
<span class="comment">// store new string to value and return TRUE.</span>
|
|
<span class="comment">// NB: You must use wxPGProperty::SetValueInEvent().</span>
|
|
<span class="comment">//</span>
|
|
}
|
|
|
|
wxValidator* PROPNAME::DoGetValidator()<span class="keyword"> const</span>
|
|
<span class="keyword"> </span>{
|
|
<span class="comment">//</span>
|
|
<span class="comment">// TODO: Return pointer to a new wxValidator instance. In most situations,</span>
|
|
<span class="comment">// code like this should work well:</span>
|
|
<span class="comment">//</span>
|
|
<span class="comment">// WX_PG_DOGETVALIDATOR_ENTRY()</span>
|
|
<span class="comment">//</span>
|
|
<span class="comment">// wxMyValidator* validator = new wxMyValidator(...);</span>
|
|
<span class="comment">//</span>
|
|
<span class="comment">// ... prepare validator...</span>
|
|
<span class="comment">//</span>
|
|
<span class="comment">// WX_PG_DOGETVALIDATOR_EXIT(validator)</span>
|
|
<span class="comment">//</span>
|
|
<span class="comment">// Macros are used to maintain only one actual validator instance</span>
|
|
<span class="comment">// (ie. on a second call, function exits within the first macro).</span>
|
|
<span class="comment">//</span>
|
|
<span class="comment">// For real examples, search props.cpp for ::DoGetValidator, it should</span>
|
|
<span class="comment">// have several.</span>
|
|
<span class="comment">//</span>
|
|
}
|
|
</pre></div><h4><a class="anchor" id="custflagsprop">
|
|
Custom Flags Property</a></h4>
|
|
<p>Flags property with custom default value and built-in labels/values.</p>
|
|
<p>In header: </p>
|
|
<div class="fragment"><pre class="fragment"> WX_PG_DECLARE_CUSTOM_FLAGS_PROPERTY(PROPNAME)
|
|
</pre></div><p>In source: </p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// LABELS are VALUES are as in the arguments to wxFlagsProperty</span>
|
|
<span class="comment">// constructor. DEFVAL is the new default value (normally it is 0).</span>
|
|
WX_PG_IMPLEMENT_CUSTOM_FLAGS_PROPERTY(PROPNAME,LABELS,VALUES,DEFAULT_FLAGS)
|
|
</pre></div><p>The new property class will have simple (label,name,value) constructor.</p>
|
|
<h4><a class="anchor" id="custenumprop">
|
|
Custom EnumProperty</a></h4>
|
|
<p>Exactly the same as custom FlagsProperty. Simply replace FLAGS with ENUM in macro names to create <a class="el" href="classwxEnumProperty.htm" title="You can derive custom properties with choices from this class.">wxEnumProperty</a> based class instead.</p>
|
|
<h4><a class="anchor" id="custarraystringprop">
|
|
Custom ArrayString property</a></h4>
|
|
<p>This type of custom property allows selecting different string delimiter (default is '"' on both sides of the string - as in C code), and allows adding custom button into the editor dialog.</p>
|
|
<p>In header: </p>
|
|
<div class="fragment"><pre class="fragment"> WX_PG_DECLARE_ARRAYSTRING_PROPERTY(wxMyArrayStringProperty)
|
|
</pre></div><p>In source:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// second argument = string delimiter. '"' for C string style (default),</span>
|
|
<span class="comment">// and anything else for str1<delimiter> str2<delimiter> str3 style</span>
|
|
<span class="comment">// (so for example, using ';' would result to str1; str2; str3).</span>
|
|
<span class="comment">// third argument = const wxChar* text for the custom button. If NULL</span>
|
|
<span class="comment">// then no button is added.</span>
|
|
WX_PG_IMPLEMENT_ARRAYSTRING_PROPERTY(wxMyArrayStringProperty,<span class="charliteral">','</span>,wxT(<span class="stringliteral">"Browse"</span>))
|
|
|
|
bool wxMyArrayStringProperty::OnCustomStringEdit(wxWindow* parent,
|
|
wxString& value)
|
|
{
|
|
<span class="comment">//</span>
|
|
<span class="comment">// TODO: Show custom editor dialog, read initial string from value.</span>
|
|
<span class="comment">// If changed, store new string to value and return TRUE.</span>
|
|
<span class="comment">//</span>
|
|
}
|
|
</pre></div><h4><a class="anchor" id="custcolprop">
|
|
Custom ColourProperty</a></h4>
|
|
<p>wxColourProperty/wxSystemColourProperty that can have custom list of colours in dropdown.</p>
|
|
<p>Use version that doesn't have _USES_WXCOLOUR in macro names to have <a class="el" href="classwxColourPropertyValue.htm" title="Because text, background and other colours tend to differ between platforms, wxSystemColourProperty...">wxColourPropertyValue</a> as value type instead of plain wxColour (in this case values array might also make sense).</p>
|
|
<p>In header: </p>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <wx/propgrid/advprops.h></span>
|
|
WX_PG_DECLARE_CUSTOM_COLOUR_PROPERTY_USES_WXCOLOUR(wxMyColourProperty)
|
|
</pre></div><p>In source:</p>
|
|
<div class="fragment"><pre class="fragment"> <span class="comment">// Colour labels. Last (before NULL, if any) must be Custom.</span>
|
|
<span class="keyword">static</span> <span class="keyword">const</span> wxChar* mycolprop_labels[] = {
|
|
wxT(<span class="stringliteral">"Black"</span>),
|
|
wxT(<span class="stringliteral">"Blue"</span>),
|
|
wxT(<span class="stringliteral">"Brown"</span>),
|
|
wxT(<span class="stringliteral">"Custom"</span>),
|
|
(<span class="keyword">const</span> wxChar*) NULL
|
|
};
|
|
|
|
<span class="comment">// Relevant colour values as unsigned longs.</span>
|
|
<span class="keyword">static</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> mycolprop_colours[] = {
|
|
<a class="code" href="group__miscellaneous.htm#ga59fd572254a501df13236ad5363b4253" title="Convert Red, Green and Blue to a single 32-bit value.">wxPG_COLOUR</a>(0,0,0),
|
|
<a class="code" href="group__miscellaneous.htm#ga59fd572254a501df13236ad5363b4253" title="Convert Red, Green and Blue to a single 32-bit value.">wxPG_COLOUR</a>(0,0,255),
|
|
<a class="code" href="group__miscellaneous.htm#ga59fd572254a501df13236ad5363b4253" title="Convert Red, Green and Blue to a single 32-bit value.">wxPG_COLOUR</a>(166,124,81),
|
|
<a class="code" href="group__miscellaneous.htm#ga59fd572254a501df13236ad5363b4253" title="Convert Red, Green and Blue to a single 32-bit value.">wxPG_COLOUR</a>(0,0,0)
|
|
};
|
|
|
|
<span class="comment">// Implement property class. Third argument is optional values array,</span>
|
|
<span class="comment">// but in this example we are only interested in creating a shortcut</span>
|
|
<span class="comment">// for user to access the colour values.</span>
|
|
WX_PG_IMPLEMENT_CUSTOM_COLOUR_PROPERTY_USES_WXCOLOUR(wxMyColourProperty,
|
|
mycolprop_labels,
|
|
(<span class="keywordtype">long</span>*)NULL,
|
|
mycolprop_colours)
|
|
</pre></div><h2><a class="anchor" id="neweditors">
|
|
Creating Custom Property Editor</a></h2>
|
|
<ul>
|
|
<li>See the sources of built-in editors in contrib/src/propgrid/propgrid.cpp (search for <a class="el" href="classwxPGTextCtrlEditor.htm">wxPGTextCtrlEditor</a>).</li>
|
|
</ul>
|
|
<ul>
|
|
<li>For additional information, see <a class="el" href="classwxPGEditor.htm" title="Base for property editor classes.">wxPGEditor</a> class reference</li>
|
|
</ul>
|
|
<h3><a class="anchor" id="wxpythoneditors">
|
|
In wxPython</a></h3>
|
|
<ul>
|
|
<li>See README-propgrid-wxPython.txt </li>
|
|
</ul>
|
|
</div>
|
|
<!--- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Enumerator</a></div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<hr class="footer"/><address style="text-align: right;"><small>Generated on Sun Aug 22 12:42:13 2010 for wxPropertyGrid by
|
|
<a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
|
|
</body>
|
|
</html>
|