1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
|
<!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"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: wxPropertyGrid Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#propgrid_basics">Creating and Populating wxPropertyGrid</a></li>
<li class="level1"><a href="#propgrid_categories">Categories</a></li>
<li class="level1"><a href="#propgrid_parentprops">Tree-like Property Structure</a></li>
<li class="level1"><a href="#propgrid_enumandflags">wxEnumProperty and wxFlagsProperty</a></li>
<li class="level1"><a href="#propgrid_advprops">Specialized Properties</a></li>
<li class="level1"><a href="#propgrid_processingvalues">Processing Property Values</a></li>
<li class="level1"><a href="#propgrid_iterating">Iterating through a property container</a></li>
<li class="level1"><a href="#propgrid_populating">Populating wxPropertyGrid Automatically</a><ul><li class="level2"><a href="#propgrid_fromvariants">Populating from List of wxVariants</a></li>
<li class="level2"><a href="#propgrid_fromfile">Loading Population from a Text-based Storage</a></li>
<li class="level2"><a href="#editablestate">Saving and Restoring User-Editable State</a></li>
</ul>
</li>
<li class="level1"><a href="#propgrid_events">Event Handling</a></li>
<li class="level1"><a href="#propgrid_tooltipandhint">Help String, Hint and Tool Tips</a></li>
<li class="level1"><a href="#propgrid_validating">Validating Property Values</a></li>
<li class="level1"><a href="#propgrid_cellrender">Customizing Individual Cell Appearance</a></li>
<li class="level1"><a href="#propgrid_keyhandling">Customizing Keyboard Handling</a></li>
<li class="level1"><a href="#propgrid_customizing">Customizing Properties (without sub-classing)</a><ul><li class="level2"><a href="#propgrid_customimage">Setting Value Image</a></li>
<li class="level2"><a href="#propgrid_customeditor">Setting Property's Editor Control(s)</a></li>
<li class="level2"><a href="#propgrid_editorattrs">Property Attributes Recognized by Editors</a></li>
<li class="level2"><a href="#propgrid_multiplebuttons">Adding Multiple Buttons Next to an Editor</a></li>
<li class="level2"><a href="#propgrid_customeventhandling">Handling Events Passed from Properties</a></li>
<li class="level2"><a href="#propgrid_attributes">Property Attributes</a></li>
</ul>
</li>
<li class="level1"><a href="#propgrid_usage2">Using wxPropertyGridManager</a><ul><li class="level2"><a href="#propgrid_propgridpage">wxPropertyGridPage</a></li>
</ul>
</li>
<li class="level1"><a href="#propgrid_subclassing">Sub-classing wxPropertyGrid and wxPropertyGridManager</a></li>
<li class="level1"><a href="#propgrid_misc">Miscellaneous Topics</a><ul><li class="level2"><a href="#propgrid_namescope">Property Name Scope</a></li>
<li class="level2"><a href="#propgrid_nonuniquelabels">Non-unique Labels</a></li>
<li class="level2"><a href="#propgrid_boolproperty">wxBoolProperty</a></li>
<li class="level2"><a href="#propgrid_textctrlupdates">Updates from wxTextCtrl Based Editor</a></li>
<li class="level2"><a href="#propgrid_splittercentering">Centering the Splitter</a></li>
<li class="level2"><a href="#propgrid_splittersetting">Setting Splitter Position When Creating Property Grid</a></li>
<li class="level2"><a href="#propgrid_colourproperty">wxColourProperty and wxSystemColourProperty</a></li>
</ul>
</li>
<li class="level1"><a href="#propgrid_proplist">Property Class Descriptions</a></li>
<li class="level1"><a href="#propgrid_compat">Changes from wxPropertyGrid 1.4</a><ul><li class="level2"><a href="#propgrid_compat_general">General Changes</a></li>
<li class="level2"><a href="#propgrid_compat_propdev">Property and Editor Sub-classing Changes</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p><a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> is a specialized grid for editing properties - in other words name = value pairs.</p>
<p>List of ready-to-use property classes include strings, numbers, flag sets, fonts, colours and many others. It is possible, for example, to categorize properties, set up a complete tree-hierarchy, add more than two columns, and set arbitrary per-property attributes.</p>
<p>As this version of <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> has some backward-incompatible changes from version 1.4, everybody who need to maintain custom property classes should carefully read final section in <a class="el" href="overview_propgrid.html#propgrid_compat">Changes from wxPropertyGrid 1.4</a>.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a>, <a class="el" href="classwx_property_grid_event.html" title="A property grid event holds information about events associated with wxPropertyGrid objects...">wxPropertyGridEvent</a>, <a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a>, <a class="el" href="classwx_property_grid_page.html" title="Holder of property grid page information.">wxPropertyGridPage</a>, <a class="el" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a></dd></dl>
<h1><a class="anchor" id="propgrid_basics"></a>
Creating and Populating wxPropertyGrid</h1>
<p>As seen here, <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> is constructed in the same way as other wxWidgets controls:</p>
<div class="fragment"><div class="line"><span class="comment">// Necessary header file</span></div>
<div class="line"><span class="preprocessor">#include <<a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html">wx/propgrid/propgrid.h</a>></span></div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Assumes code is in frame/dialog constructor</span></div>
<div class="line"></div>
<div class="line"> <span class="comment">// Construct wxPropertyGrid control</span></div>
<div class="line"> <a class="code" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a>* pg = <span class="keyword">new</span> <a class="code" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a>(</div>
<div class="line"> <span class="keyword">this</span>, <span class="comment">// parent</span></div>
<div class="line"> PGID, <span class="comment">// id</span></div>
<div class="line"> <a class="code" href="gdicmn_8h.html#af5a90c753eaf3d3e3e5068a19ec3c1d0" title="Global instance of a wxPoint initialized with values (-1,-1).">wxDefaultPosition</a>, <span class="comment">// position</span></div>
<div class="line"> <a class="code" href="gdicmn_8h.html#a33a012cdb075e9f78c93f63bec2dc27b" title="Global instance of a wxSize object initialized to (-1,-1).">wxDefaultSize</a>, <span class="comment">// size</span></div>
<div class="line"> <span class="comment">// Here are just some of the supported window styles</span></div>
<div class="line"> <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#a967b646b15085e115051d83a65ffdfe8a6bc5847c59e582bb9c3910ccb54d8635" title="This will cause Sort() automatically after an item is added.">wxPG_AUTO_SORT</a> | <span class="comment">// Automatic sorting after items added</span></div>
<div class="line"> <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#a967b646b15085e115051d83a65ffdfe8a998b9d55c606adb1010be7438286e3c5" title="When wxPropertyGrid is resized, splitter moves to the center.">wxPG_SPLITTER_AUTO_CENTER</a> | <span class="comment">// Automatically center splitter until user manually adjusts it</span></div>
<div class="line"> <span class="comment">// Default style</span></div>
<div class="line"> <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#acf768b936525faa42392f653a3296eb4" title="Combines various styles.">wxPG_DEFAULT_STYLE</a> );</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Window style flags are at premium, so some less often needed ones are</span></div>
<div class="line"> <span class="comment">// available as extra window styles (wxPG_EX_xxx) which must be set using</span></div>
<div class="line"> <span class="comment">// SetExtraStyle member function. wxPG_EX_HELP_AS_TOOLTIPS, for instance,</span></div>
<div class="line"> <span class="comment">// allows displaying help strings as tool tips.</span></div>
<div class="line"> pg-><a class="code" href="classwx_window.html#ae9655f7c35ce7ac89cac2f6c0054b103" title="Sets the extra style bits for the window.">SetExtraStyle</a>( <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#aeebee6f1621b080999ea22a5b76b00a6aab51ec531320af974c83f1af88dd14b1" title="Show property help strings as tool tips instead as text on the status bar.">wxPG_EX_HELP_AS_TOOLTIPS</a> );</div>
</div><!-- fragment --><p>(for complete list of new window styles, see <a class="el" href="interface_2wx_2propgrid_2propgrid_8h.html#propgrid_window_styles">wxPropertyGrid Window Styles</a>)</p>
<p><a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> is usually populated with lines like this:</p>
<div class="fragment"><div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxStringProperty(<span class="stringliteral">"Label"</span>, <span class="stringliteral">"Name"</span>, <span class="stringliteral">"Initial Value"</span>) );</div>
</div><!-- fragment --><p>Naturally, wxStringProperty 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"><div class="line"><span class="comment">// Add int property</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"IntProperty"</span>, wxPG_LABEL, 12345678) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Add float property (value type is actually double)</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxFloatProperty(<span class="stringliteral">"FloatProperty"</span>, wxPG_LABEL, 12345.678) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Add a bool property</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxBoolProperty(<span class="stringliteral">"BoolProperty"</span>, wxPG_LABEL, <span class="keyword">false</span>) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// A string property that can be edited in a separate editor dialog.</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxLongStringProperty(<span class="stringliteral">"LongStringProperty"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <span class="stringliteral">"This is much longer string than the "</span></div>
<div class="line"> <span class="stringliteral">"first one. Edit it by clicking the button."</span>));</div>
<div class="line"></div>
<div class="line"><span class="comment">// String editor with dir selector button.</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxDirProperty(<span class="stringliteral">"DirProperty"</span>, wxPG_LABEL, ::<a class="code" href="group__group__funcmacro__networkuseros.html#ga18db911e93361ebd5bbfb0d5136ddf5b" title="Returns the home directory for the given user.">wxGetUserHome</a>()) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// wxArrayStringProperty embeds a wxArrayString.</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxArrayStringProperty(<span class="stringliteral">"Label of ArrayStringProperty"</span>,</div>
<div class="line"> <span class="stringliteral">"NameOfArrayStringProp"</span>));</div>
<div class="line"></div>
<div class="line"><span class="comment">// A file selector property.</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxFileProperty(<span class="stringliteral">"FileProperty"</span>, wxPG_LABEL, <a class="code" href="interface_2wx_2string_8h.html#a9a321d587166a30017b608dd2d234033" title="The global wxString instance of an empty string.">wxEmptyString</a>) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Extra: set wild card for file property (format same as in wxFileDialog).</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute for this property.">SetPropertyAttribute</a>( <span class="stringliteral">"FileProperty"</span>,</div>
<div class="line"> <a class="code" href="property_8h.html#a1817e1bea592d9cda7a330ea3a25f851" title="wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.">wxPG_FILE_WILDCARD</a>,</div>
<div class="line"> <span class="stringliteral">"All files (*.*)|*.*"</span> );</div>
</div><!-- fragment --><p>Operations on properties are usually done by directly calling <a class="el" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>'s or <a class="el" href="classwx_property_grid_interface.html" title="Most of the shared property manipulation interface shared by wxPropertyGrid, wxPropertyGridPage, and wxPropertyGridManager is defined in this class.">wxPropertyGridInterface</a>'s member functions. <a class="el" href="classwx_property_grid_interface.html" title="Most of the shared property manipulation interface shared by wxPropertyGrid, wxPropertyGridPage, and wxPropertyGridManager is defined in this class.">wxPropertyGridInterface</a> is an abstract base class for property containers such as <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a>, <a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a>, and <a class="el" href="classwx_property_grid_page.html" title="Holder of property grid page information.">wxPropertyGridPage</a>. Note however that <a class="el" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>'s member functions generally do not refresh the grid.</p>
<p><a class="el" href="classwx_property_grid_interface.html" title="Most of the shared property manipulation interface shared by wxPropertyGrid, wxPropertyGridPage, and wxPropertyGridManager is defined in this class.">wxPropertyGridInterface</a>'s property operation member functions , such as SetPropertyValue() and DisableProperty(), all accept a special wxPGPropArg id argument, using which you can refer to properties either by their pointer (for performance) or by their name (for convenience). For instance:</p>
<div class="fragment"><div class="line"><span class="comment">// Add a file selector property.</span></div>
<div class="line"><a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* prop = pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxFileProperty(<span class="stringliteral">"FileProperty"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <a class="code" href="interface_2wx_2string_8h.html#a9a321d587166a30017b608dd2d234033" title="The global wxString instance of an empty string.">wxEmptyString</a>) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Valid: Set wild card by name</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute for this property.">SetPropertyAttribute</a>( <span class="stringliteral">"FileProperty"</span>,</div>
<div class="line"> <a class="code" href="property_8h.html#a1817e1bea592d9cda7a330ea3a25f851" title="wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.">wxPG_FILE_WILDCARD</a>,</div>
<div class="line"> <span class="stringliteral">"All files (*.*)|*.*"</span> );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Also Valid: Set wild card by property pointer</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute for this property.">SetPropertyAttribute</a>( prop,</div>
<div class="line"> <a class="code" href="property_8h.html#a1817e1bea592d9cda7a330ea3a25f851" title="wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.">wxPG_FILE_WILDCARD</a>,</div>
<div class="line"> <span class="stringliteral">"All files (*.*)|*.*"</span> );</div>
</div><!-- fragment --><p>Using pointer is faster, since it doesn't require hash map lookup. Anyway, you can always get property pointer (wxPGProperty*) as return value from Append() or Insert(), or by calling <a class="el" href="classwx_property_grid_interface.html#ac5723b61ae48d373671343e774632ed3" title="Returns pointer to a property with given name (case-sensitive).">wxPropertyGridInterface::GetPropertyByName()</a> or just plain GetProperty().</p>
<h1><a class="anchor" id="propgrid_categories"></a>
Categories</h1>
<p><a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> has a hierarchic 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. Note however that sometimes the label of a property category may be referred as caption (for example, there is <a class="el" href="classwx_property_grid.html#a690cc9643f94225f38720c336789c7d4" title="Sets category caption text colour.">wxPropertyGrid::SetCaptionTextColour()</a> method that sets text colour of property category labels).</p>
<p>When category is added at the top (i.e. root) level of the hierarchy, it becomes a <em>current category</em>. This means that all other (non-category) properties after it are automatically appended to it. You may add properties to specific categories by using <a class="el" href="classwx_property_grid_interface.html#aed2f5e12acc0bc460c2295ac1564b735" title="Inserts property to the property container.">wxPropertyGridInterface::Insert</a> or <a class="el" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">wxPropertyGridInterface::AppendIn</a>.</p>
<p>Category code sample:</p>
<div class="fragment"><div class="line"><span class="comment">// One way to add category (similar to how other properties are added)</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxPropertyCategory(<span class="stringliteral">"Main"</span>) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// All these are added to "Main" category</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxStringProperty(<span class="stringliteral">"Name"</span>) );</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Age"</span>,wxPG_LABEL,25) );</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Height"</span>,wxPG_LABEL,180) );</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Weight"</span>) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Another one</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxPropertyCategory(<span class="stringliteral">"Attributes"</span>) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// All these are added to "Attributes" category</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Intelligence"</span>) );</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Agility"</span>) );</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Strength"</span>) );</div>
</div><!-- fragment --><h1><a class="anchor" id="propgrid_parentprops"></a>
Tree-like Property Structure</h1>
<p>Basically any property can have children. There are few limitations, however.</p>
<dl class="section remark"><dt>Remarks</dt><dd><ul>
<li>Names of properties with non-category, non-root parents are not stored in global 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 of the child property values, you must use wxStringProperty as parent and use magic string "<composed>" as its value.</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>
</ul>
</dd></dl>
<p>Sample:</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* carProp = pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>(<span class="keyword">new</span> wxStringProperty(<span class="stringliteral">"Car"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <span class="stringliteral">"<composed>"</span>));</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">AppendIn</a>(carProp, <span class="keyword">new</span> wxStringProperty(<span class="stringliteral">"Model"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <span class="stringliteral">"Lamborghini Diablo SV"</span>));</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">AppendIn</a>(carProp, <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Engine Size (cc)"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> 5707) );</div>
<div class="line"></div>
<div class="line"><a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* speedsProp = pg-><a class="code" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">AppendIn</a>(carProp,</div>
<div class="line"> <span class="keyword">new</span> wxStringProperty(<span class="stringliteral">"Speeds"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <span class="stringliteral">"<composed>"</span>));</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">AppendIn</a>( speedsProp, <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Max. Speed (mph)"</span>,</div>
<div class="line"> wxPG_LABEL,290) );</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">AppendIn</a>( speedsProp, <span class="keyword">new</span> wxFloatProperty(<span class="stringliteral">"0-100 mph (sec)"</span>,</div>
<div class="line"> wxPG_LABEL,3.9) );</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">AppendIn</a>( speedsProp, <span class="keyword">new</span> wxFloatProperty(<span class="stringliteral">"1/4 mile (sec)"</span>,</div>
<div class="line"> wxPG_LABEL,8.6) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// This is how child property can be referred to by name</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#aa652e127ce0c9d4e80821cbdcfe4983c" title="Sets value (integer) of a property.">SetPropertyValue</a>( <span class="stringliteral">"Car.Speeds.Max. Speed (mph)"</span>, 300 );</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a7ae5812ea47c050f981aec0b8ccbe83e" title="Same as Append(), but appends under given parent property.">AppendIn</a>(carProp, <span class="keyword">new</span> wxIntProperty(<span class="stringliteral">"Price ($)"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> 300000) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Displayed value of "Car" property is now very close to this:</span></div>
<div class="line"><span class="comment">// "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"</span></div>
</div><!-- fragment --><h1><a class="anchor" id="propgrid_enumandflags"></a>
wxEnumProperty and wxFlagsProperty</h1>
<p>wxEnumProperty is used when you want property's (integer or string) value to be selected from a popup list of choices.</p>
<p>Creating wxEnumProperty is slightly 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="section remark"><dt>Remarks</dt><dd></dd></dl>
<ul>
<li>Value wxPG_INVALID_VALUE (equals INT_MAX) is not allowed as list item value.</li>
</ul>
<p>A very simple example:</p>
<div class="fragment"><div class="line"><span class="comment">//</span></div>
<div class="line"><span class="comment">// Using wxArrayString</span></div>
<div class="line"><span class="comment">//</span></div>
<div class="line"><a class="code" href="classwx_array_string.html" title="wxArrayString is an efficient container for storing wxString objects.">wxArrayString</a> arrDiet;</div>
<div class="line">arr.<a class="code" href="classwx_array_string.html#af06b61455118d83a24183c3a9f6854b1" title="Appends the given number of copies of the new item str to the array and returns the index of the firs...">Add</a>(<span class="stringliteral">"Herbivore"</span>);</div>
<div class="line">arr.Add(<span class="stringliteral">"Carnivore"</span>);</div>
<div class="line">arr.Add(<span class="stringliteral">"Omnivore"</span>);</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxEnumProperty(<span class="stringliteral">"Diet"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> arrDiet) );</div>
<div class="line"></div>
<div class="line"><span class="comment">//</span></div>
<div class="line"><span class="comment">// Using wxChar* array</span></div>
<div class="line"><span class="comment">//</span></div>
<div class="line"><span class="keyword">const</span> <a class="code" href="group__group__funcmacro__string.html#gad42f64d8c82f1ce4ae58773a89b2d6a7" title="wxChar is defined to bechar when wxUSE_UNICODE==0wchar_t when wxUSE_UNICODE==1 (the default)...">wxChar</a>* arrayDiet[] =</div>
<div class="line">{ <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Herbivore"</span>), <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Carnivore"</span>), <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Omnivore"</span>), NULL };</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxEnumProperty(<span class="stringliteral">"Diet"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> arrayDiet) );</div>
</div><!-- fragment --><p>Here's extended example using values as well:</p>
<div class="fragment"><div class="line"><span class="comment">//</span></div>
<div class="line"><span class="comment">// Using wxArrayString and wxArrayInt</span></div>
<div class="line"><span class="comment">//</span></div>
<div class="line"><a class="code" href="classwx_array_string.html" title="wxArrayString is an efficient container for storing wxString objects.">wxArrayString</a> arrDiet;</div>
<div class="line">arr.<a class="code" href="classwx_array_string.html#af06b61455118d83a24183c3a9f6854b1" title="Appends the given number of copies of the new item str to the array and returns the index of the firs...">Add</a>(<span class="stringliteral">"Herbivore"</span>);</div>
<div class="line">arr.Add(<span class="stringliteral">"Carnivore"</span>);</div>
<div class="line">arr.Add(<span class="stringliteral">"Omnivore"</span>);</div>
<div class="line"></div>
<div class="line"><a class="code" href="dynarray_8h.html#add87f199292e36ee87efd6d7f0d4ee66" title="Predefined specialization of wxArray<T> for standard types.">wxArrayInt</a> arrIds;</div>
<div class="line">arrIds.Add(40);</div>
<div class="line">arrIds.Add(45);</div>
<div class="line">arrIds.Add(50);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Note that the initial value (the last argument) is the actual value,</span></div>
<div class="line"><span class="comment">// not index or anything like that. Thus, our value selects "Omnivore".</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxEnumProperty(<span class="stringliteral">"Diet"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> arrDiet,</div>
<div class="line"> arrIds,</div>
<div class="line"> 50));</div>
</div><!-- fragment --><p><a class="el" href="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> is a class where wxEnumProperty, and other properties which require storage for list of items, actually stores strings and values. It is used to facilitate 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="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> directly as well, filling it and then passing it to the constructor. In fact, if you wish to display bitmaps next to labels, your best choice is to use this approach.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> chs;</div>
<div class="line">chs.<a class="code" href="classwx_p_g_choices.html#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(<span class="stringliteral">"Herbivore"</span>, 40);</div>
<div class="line">chs.<a class="code" href="classwx_p_g_choices.html#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(<span class="stringliteral">"Carnivore"</span>, 45);</div>
<div class="line">chs.<a class="code" href="classwx_p_g_choices.html#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(<span class="stringliteral">"Omnivore"</span>, 50);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Let's add an item with bitmap, too</span></div>
<div class="line">chs.<a class="code" href="classwx_p_g_choices.html#a7281ca96c7aaf39b059a93bc08fcd72d" title="Adds to current.">Add</a>(<span class="stringliteral">"None of the above"</span>, <a class="code" href="classwx_bitmap.html" title="This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or co...">wxBitmap</a>(), 60);</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxEnumProperty(<span class="stringliteral">"Primary Diet"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> chs) );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Add same choices to another property as well - this is efficient due</span></div>
<div class="line"><span class="comment">// to reference counting</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxEnumProperty(<span class="stringliteral">"Secondary Diet"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> chs) );</div>
</div><!-- fragment --><p>You can later change choices of property by using <a class="el" href="classwx_p_g_property.html#ab58afbdcd83f0626f44d152127038a89" title="Append a new choice to property's list of choices.">wxPGProperty::AddChoice()</a>, <a class="el" href="classwx_p_g_property.html#ae9f9995783eeaf5320cb0c71482cbbc8" title="Inserts a new choice to property's list of choices.">wxPGProperty::InsertChoice()</a>, <a class="el" href="classwx_p_g_property.html#a137f1b7ea16f1f18fcc3e50ec107da1f" title="Removes entry from property's wxPGChoices and editor control (if it is active).">wxPGProperty::DeleteChoice()</a>, and <a class="el" href="classwx_p_g_property.html#a7275467270d2c7ac3f847f4d1b6a1194" title="Sets new set of choices for the property.">wxPGProperty::SetChoices()</a>.</p>
<p><b>wxEditEnumProperty</b> works exactly like wxEnumProperty, except is uses non-read-only combo box as default editor, and value is stored as string when it is not any of the choices.</p>
<p>wxFlagsProperty has similar construction:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <a class="code" href="group__group__funcmacro__string.html#gad42f64d8c82f1ce4ae58773a89b2d6a7" title="wxChar is defined to bechar when wxUSE_UNICODE==0wchar_t when wxUSE_UNICODE==1 (the default)...">wxChar</a>* flags_prop_labels[] = { <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"wxICONIZE"</span>),</div>
<div class="line"> <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"wxCAPTION"</span>), <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"wxMINIMIZE_BOX"</span>), <a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"wxMAXIMIZE_BOX"</span>), NULL };</div>
<div class="line"></div>
<div class="line"><span class="comment">// this value array would be optional if values matched string indexes</span></div>
<div class="line"><span class="keywordtype">long</span> flags_prop_values[] = { <a class="code" href="defs_8h.html#a8dd8a3b1da393539bbf97740cf8e15a9">wxICONIZE</a>, <a class="code" href="defs_8h.html#ab9dd38fb28514dc86647c9bab14a5abe">wxCAPTION</a>, <a class="code" href="defs_8h.html#a58a06afb75f2d7eaf75678be07cd1bb9">wxMINIMIZE_BOX</a>,</div>
<div class="line"> <a class="code" href="defs_8h.html#a8968324afeca5856872724521f199e04">wxMAXIMIZE_BOX</a> };</div>
<div class="line"></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxFlagsProperty(<span class="stringliteral">"Window Style"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> flags_prop_labels,</div>
<div class="line"> flags_prop_values,</div>
<div class="line"> <a class="code" href="toplevel_8h.html#ab3ad2777e5178344fa798ec8fd8e95e2">wxDEFAULT_FRAME_STYLE</a>) );</div>
</div><!-- fragment --><p>wxFlagsProperty can use <a class="el" href="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> just the same way as wxEnumProperty <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you will need to use <a class="el" href="classwx_p_g_property.html#a7275467270d2c7ac3f847f4d1b6a1194" title="Sets new set of choices for the property.">wxPGProperty::SetChoices()</a> to replace all choices at once - otherwise implicit child properties will not get updated properly.</p>
<h1><a class="anchor" id="propgrid_advprops"></a>
Specialized Properties</h1>
<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"><div class="line"><span class="comment">// Necessary extra header file</span></div>
<div class="line"><span class="preprocessor">#include <wx/propgrid/advprops.h></span></div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Date property.</span></div>
<div class="line"> pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxDateProperty(<span class="stringliteral">"MyDateProperty"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <a class="code" href="classwx_date_time.html#a6e6c37a0414bb4831e2cc03b37f498a2" title="Returns the object corresponding to the current time.">wxDateTime::Now</a>()) );</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Image file property. Wild card is auto-generated from available</span></div>
<div class="line"> <span class="comment">// image handlers, so it is not set this time.</span></div>
<div class="line"> pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxImageFileProperty(<span class="stringliteral">"Label of ImageFileProperty"</span>,</div>
<div class="line"> <span class="stringliteral">"NameOfImageFileProp"</span>) );</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Font property has sub-properties. Note that we give window's font as</span></div>
<div class="line"> <span class="comment">// initial value.</span></div>
<div class="line"> pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxFontProperty(<span class="stringliteral">"Font"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> GetFont()) );</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Colour property with arbitrary colour.</span></div>
<div class="line"> pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxColourProperty(<span class="stringliteral">"My Colour 1"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <a class="code" href="classwx_colour.html" title="A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values...">wxColour</a>(242,109,0) ) );</div>
<div class="line"></div>
<div class="line"> <span class="comment">// System colour property.</span></div>
<div class="line"> pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxSystemColourProperty(<span class="stringliteral">"My SysColour 1"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <a class="code" href="classwx_system_settings.html#ab252414b60f16a233bc17df2a19bd804" title="Returns a system colour.">wxSystemSettings::GetColour</a>(<a class="code" href="settings_8h.html#a44ad26cbd8d579d1b7eff7015c8bd24ba4a6145d1d56adfaa209f03df43a34f63" title="Window background colour.">wxSYS_COLOUR_WINDOW</a>)) );</div>
<div class="line"></div>
<div class="line"> <span class="comment">// System colour property with custom colour.</span></div>
<div class="line"> pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxSystemColourProperty(<span class="stringliteral">"My SysColour 2"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <a class="code" href="classwx_colour.html" title="A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values...">wxColour</a>(0,200,160) ) );</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Cursor property</span></div>
<div class="line"> pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>( <span class="keyword">new</span> wxCursorProperty(<span class="stringliteral">"My Cursor"</span>,</div>
<div class="line"> wxPG_LABEL,</div>
<div class="line"> <a class="code" href="gdicmn_8h.html#ae668769c0de48b50d4695b279c7c41b2a97a7a0012654ded652421164575f960b" title="A standard arrow cursor.">wxCURSOR_ARROW</a>));</div>
</div><!-- fragment --><h1><a class="anchor" id="propgrid_processingvalues"></a>
Processing Property Values</h1>
<p>Properties store their values internally as <a class="el" href="classwx_variant.html" title="The wxVariant class represents a container for any type.">wxVariant</a>, but is also possible to obtain them as <a class="el" href="classwx_any.html" title="The wxAny class represents a container for any type.">wxAny</a>, using implicit conversion. You can get property values with <a class="el" href="classwx_p_g_property.html#a76fdd0b4782957b18aca2e8b8e170a0d" title="Returns property's value.">wxPGProperty::GetValue()</a> and <a class="el" href="classwx_property_grid_interface.html#aa1164652240e4b157ce5250769af537e" title="Returns property's value as wxVariant.">wxPropertyGridInterface::GetPropertyValue()</a>.</p>
<p>Below is a code example which handles wxEVT_PG_CHANGED event:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> MyWindowClass::OnPropertyGridChanged(<a class="code" href="classwx_property_grid_event.html" title="A property grid event holds information about events associated with wxPropertyGrid objects...">wxPropertyGridEvent</a>& event)</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* <span class="keyword">property</span> = <span class="keyword">event</span>.GetProperty();</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Do nothing if event did not have associated property</span></div>
<div class="line"> <span class="keywordflow">if</span> ( !property )</div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"></div>
<div class="line"> <span class="comment">// GetValue() returns wxVariant, but it is converted transparently to</span></div>
<div class="line"> <span class="comment">// wxAny</span></div>
<div class="line"> <a class="code" href="classwx_any.html" title="The wxAny class represents a container for any type.">wxAny</a> value = <span class="keyword">property</span>->GetValue();</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Also, handle the case where property value is unspecified</span></div>
<div class="line"> <span class="keywordflow">if</span> ( value.<a class="code" href="classwx_any.html#abd2b24fc0a7216a5336d8f7d731c2370" title="Tests if wxAny is null (that is, whether there is no data).">IsNull</a>() )</div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Handle changes in values, as needed</span></div>
<div class="line"> <span class="keywordflow">if</span> ( property->GetName() == <span class="stringliteral">"MyStringProperty"</span> )</div>
<div class="line"> OnMyStringPropertyChanged(value.<a class="code" href="classwx_any.html#af0720fd1c4e76e4243ec8473d7044d7b" title="This template function converts wxAny into given type.">As</a><<a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a>>());</div>
<div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span> ( property->GetName() == <span class="stringliteral">"MyColourProperty"</span> )</div>
<div class="line"> OnMyColourPropertyChanged(value.<a class="code" href="classwx_any.html#af0720fd1c4e76e4243ec8473d7044d7b" title="This template function converts wxAny into given type.">As</a><<a class="code" href="classwx_colour.html" title="A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values...">wxColour</a>>());</div>
<div class="line">}</div>
</div><!-- fragment --><p>You can get a string-representation of property's value using <a class="el" href="classwx_p_g_property.html#a29f70a60e4844efbebc140270e1a4358" title="Returns text representation of property's value.">wxPGProperty::GetValueAsString()</a> or <a class="el" href="classwx_property_grid_interface.html#a42537d846f644d3e8cfdb89bd37d9650" title="Returns property's value as wxString.">wxPropertyGridInterface::GetPropertyValueAsString()</a>. This particular function is very safe to use with any kind of property.</p>
<dl class="section note"><dt>Note</dt><dd>There is a one case in which you may want to take extra care when dealing with raw <a class="el" href="classwx_variant.html" title="The wxVariant class represents a container for any type.">wxVariant</a> values. That is, integer-type properties, such as wxIntProperty and wxUIntProperty, store value internally as wx(U)LongLong when number doesn't fit into standard long type. Using << operator to get wx(U)LongLong from <a class="el" href="classwx_variant.html" title="The wxVariant class represents a container for any type.">wxVariant</a> is customized to work quite safely with various types of variant data. However, you can also bypass this problem by using <a class="el" href="classwx_any.html" title="The wxAny class represents a container for any type.">wxAny</a> in your code instead of <a class="el" href="classwx_variant.html" title="The wxVariant class represents a container for any type.">wxVariant</a>.</dd></dl>
<p>Note that in some cases property value can be Null variant, which means that property value is unspecified. This usually occurs only when wxPG_EX_AUTO_UNSPECIFIED_VALUES extra window style is defined or when you manually set property value to Null (or unspecified).</p>
<h1><a class="anchor" id="propgrid_iterating"></a>
Iterating through a property container</h1>
<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 nor private child properties that are normally 'transparent' to application code):</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_property_grid_iterator.html">wxPropertyGridIterator</a> it;</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">for</span> ( it = pg-><a class="code" href="classwx_property_grid_interface.html#a41ab8661411082563c8191f614f91007" title="Returns iterator class instance.">GetIterator</a>();</div>
<div class="line"> !it.<a class="code" href="classwx_property_grid_iterator.html#afd78a5113e37d3b0ba20a410820779a1">AtEnd</a>();</div>
<div class="line"> it++ )</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = *it;</div>
<div class="line"> <span class="comment">// Do something with the property</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>As expected there is also a const iterator:</p>
<div class="fragment"><div class="line">wxPropertyGridConstIterator it;</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">for</span> ( it = pg-><a class="code" href="classwx_property_grid_interface.html#a41ab8661411082563c8191f614f91007" title="Returns iterator class instance.">GetIterator</a>();</div>
<div class="line"> !it.<a class="code" href="classwx_property_grid_iterator.html#afd78a5113e37d3b0ba20a410820779a1">AtEnd</a>();</div>
<div class="line"> it++ )</div>
<div class="line">{</div>
<div class="line"> <span class="keyword">const</span> <a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = *it;</div>
<div class="line"> <span class="comment">// Do something with the property</span></div>
<div class="line">}</div>
</div><!-- fragment --><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="propgridpagestate_8h.html#propgrid_iterator_flags">wxPropertyGridIterator Flags</a>. GetIterator() also accepts other arguments. See <a class="el" href="classwx_property_grid_interface.html#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"><div class="line"><a class="code" href="classwx_property_grid_iterator.html">wxPropertyGridIterator</a> it;</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">for</span> ( it = pg-><a class="code" href="classwx_property_grid_interface.html#a41ab8661411082563c8191f614f91007" title="Returns iterator class instance.">GetIterator</a>(<a class="code" href="propgridpagestate_8h.html#a307ba26bf1eeb9d76108893f4f723b0aaafca9ed41c9420c5efb18b7e519928e5" title="Combines all flags needed to iterate through visible properties (ie.">wxPG_ITERATE_VISIBLE</a>, <a class="code" href="defs_8h.html#ac0f30319732dcceda470516918ff3556a17bc9a3dbb6e30a2418601aa5e30019b">wxBOTTOM</a>);</div>
<div class="line"> !it.<a class="code" href="classwx_property_grid_iterator.html#afd78a5113e37d3b0ba20a410820779a1">AtEnd</a>();</div>
<div class="line"> it-- )</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = *it;</div>
<div class="line"> <span class="comment">// Do something with the property</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>GetIterator() only works with <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> and the individual pages of <a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a>. In order to iterate through an arbitrary property container (such as entire <a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a>), you need to use <a class="el" href="classwx_property_grid_interface.html#a96a1c13733c0a83d7b509fd7a9e9a61a" title="Similar to GetIterator(), but instead returns wxPGVIterator instance, which can be useful for forward...">wxPropertyGridInterface::GetVIterator()</a>. Note however that this virtual iterator is limited to forward iteration.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_p_g_v_iterator.html">wxPGVIterator</a> it;</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">for</span> ( it = manager->GetVIterator(<a class="code" href="propgridpagestate_8h.html#a307ba26bf1eeb9d76108893f4f723b0aacc6979a5992fc69a76cd8c1ce5f844e5" title="Iterate all items.">wxPG_ITERATE_ALL</a>);</div>
<div class="line"> !it.<a class="code" href="classwx_p_g_v_iterator.html#a46dc31e866898f24ac4d0f3f86d471ff">AtEnd</a>();</div>
<div class="line"> it.<a class="code" href="classwx_p_g_v_iterator.html#aa44ee191f93c15bc4a0d510b9723be2f">Next</a>() )</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* p = it.<a class="code" href="classwx_p_g_v_iterator.html#a69fbb856e1046a923f17847725a576c4">GetProperty</a>();</div>
<div class="line"> <span class="comment">// Do something with the property</span></div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="propgrid_populating"></a>
Populating wxPropertyGrid Automatically</h1>
<h2><a class="anchor" id="propgrid_fromvariants"></a>
Populating from List of wxVariants</h2>
<p>Example of populating an empty <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> from a values stored in an arbitrary list of wxVariants.</p>
<div class="fragment"><div class="line"><span class="comment">// This is a static method that initializes *all* built-in type handlers</span></div>
<div class="line"><span class="comment">// available, including those for wxColour and wxFont. Refers to *all*</span></div>
<div class="line"><span class="comment">// included properties, so when compiling with static library, this</span></div>
<div class="line"><span class="comment">// method may increase the executable size noticeably.</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a38bd0419a578467da07d01aef288848d" title="Initializes all property types.">InitAllTypeHandlers</a>();</div>
<div class="line"></div>
<div class="line"><span class="comment">// Get contents of the grid as a wxVariant list</span></div>
<div class="line"><a class="code" href="classwx_variant.html" title="The wxVariant class represents a container for any type.">wxVariant</a> all_values = pg-><a class="code" href="classwx_property_grid_interface.html#a1abce6843caee96faaeeee952f970105" title="Returns a wxVariant list containing wxVariant versions of all property values.">GetPropertyValues</a>();</div>
<div class="line"></div>
<div class="line"><span class="comment">// Populate the list with values. If a property with appropriate</span></div>
<div class="line"><span class="comment">// name is not found, it is created according to the type of variant.</span></div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a85caa9196b0278e844df1af5f12c800b" title="Sets property values from a list of wxVariants.">SetPropertyValues</a>( my_list_variant );</div>
</div><!-- fragment --><h2><a class="anchor" id="propgrid_fromfile"></a>
Loading Population from a Text-based Storage</h2>
<p>Class wxPropertyGridPopulator may be helpful when writing code that loads properties from a text-source. In fact, the <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> xrc-handler (which may not be currently included in wxWidgets, but probably will be in near future) uses it.</p>
<h2><a class="anchor" id="editablestate"></a>
Saving and Restoring User-Editable State</h2>
<p>You can use <a class="el" href="classwx_property_grid_interface.html#a09dcfdf53629918183615627957afe39" title="Used to acquire user-editable state (selected property, expanded properties, scrolled position...">wxPropertyGridInterface::SaveEditableState()</a> and <a class="el" href="classwx_property_grid_interface.html#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>
<h1><a class="anchor" id="propgrid_events"></a>
Event Handling</h1>
<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="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> class reference.</p>
<p>However, one type of event that might need focused attention is EVT_PG_CHANGING, which occurs just prior property value is being changed by user. You can acquire pending value using wxPropertyGridEvent::GetValue(), and if it is not acceptable, call <a class="el" href="classwx_property_grid_event.html#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"><div class="line"><span class="keywordtype">void</span> MyForm::OnPropertyGridChanging( <a class="code" href="classwx_property_grid_event.html" title="A property grid event holds information about events associated with wxPropertyGrid objects...">wxPropertyGridEvent</a>& event )</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* <span class="keyword">property</span> = <span class="keyword">event</span>.GetProperty();</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">if</span> ( property == m_pWatchThisProperty )</div>
<div class="line"> {</div>
<div class="line"> <span class="comment">// GetValue() returns the pending value, but is only</span></div>
<div class="line"> <span class="comment">// supported by wxEVT_PG_CHANGING.</span></div>
<div class="line"> <span class="keywordflow">if</span> ( event.GetValue().<a class="code" href="classwx_command_event.html#a24323d78936e5f6cd7f4780371f373e0" title="Returns item string for a listbox or choice selection event.">GetString</a>() == g_pThisTextIsNotAllowed )</div>
<div class="line"> {</div>
<div class="line"> <span class="keyword">event</span>.Veto();</div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><dl class="section remark"><dt>Remarks</dt><dd>On Child Property Event Handling<ul>
<li>For properties which have private, implicit children (wxFontProperty and wxFlagsProperty), events occur for the main parent property only. For other properties events occur for the children themselves. See <a class="el" href="overview_propgrid.html#propgrid_parentprops">Tree-like Property Structure</a>.</li>
</ul>
</dd></dl>
<ul>
<li>When property's child gets changed, you can use <a class="el" href="classwx_property_grid_event.html#a6f31d0996895c1cd8b38c5c264b2921d" title="Returns highest level non-category, non-root parent of property for which event occurred.">wxPropertyGridEvent::GetMainParent()</a> to obtain its topmost non-category parent (useful, if you have deeply nested properties).</li>
</ul>
<h1><a class="anchor" id="propgrid_tooltipandhint"></a>
Help String, Hint and Tool Tips</h1>
<p>For each property you can specify two different types of help text. First, you can use <a class="el" href="classwx_property_grid_interface.html#a5793ea3ef9afa47fe2c1c5bf437dd583" title="Associates the help string with property.">wxPropertyGridInterface::SetPropertyHelpString()</a> or <a class="el" href="classwx_p_g_property.html#a839af036b24fc35696f0ef3cb2b0670a" title="Sets property's help string, which is shown, for example, in wxPropertyGridManager's description text...">wxPGProperty::SetHelpString()</a> to set property's help text. Second, you can use <a class="el" href="classwx_p_g_property.html#a418c1539969b7a0a9378a3411a5680a6" title="Sets an attribute for this property.">wxPGProperty::SetAttribute()</a> to set property's "Hint" attribute.</p>
<p>Difference between hint and help string is that the hint is shown in an empty property value cell, while help string is shown either in the description text box, as a tool tip, or on the status bar, whichever of these is available.</p>
<p>To enable display of help string as tool tips, you must explicitly use the wxPG_EX_HELP_AS_TOOLTIPS extra window style.</p>
<h1><a class="anchor" id="propgrid_validating"></a>
Validating Property Values</h1>
<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="classwx_property_grid_interface.html#ad83fe8ad87751101316345a14133c45f" title="Sets validator of a property.">wxPropertyGridInterface::SetPropertyValidator()</a> to assign <a class="el" href="classwx_validator.html" title="wxValidator is the base class for a family of validator classes that mediate between a class of contr...">wxValidator</a> to property.</p>
<p>Second, you can subclass a property and override <a class="el" href="classwx_p_g_property.html#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 ways 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="classwx_property_grid_interface.html#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"><div class="line"><span class="keywordtype">void</span> MyFrame::OnPropertyGridChanging(<a class="code" href="classwx_property_grid_event.html" title="A property grid event holds information about events associated with wxPropertyGrid objects...">wxPropertyGridEvent</a>& event)</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* <span class="keyword">property</span> = <span class="keyword">event</span>.GetProperty();</div>
<div class="line"></div>
<div class="line"> <span class="comment">// You must use wxPropertyGridEvent::GetValue() to access</span></div>
<div class="line"> <span class="comment">// the value to be validated.</span></div>
<div class="line"> <a class="code" href="classwx_variant.html" title="The wxVariant class represents a container for any type.">wxVariant</a> pendingValue = <span class="keyword">event</span>.GetValue();</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">if</span> ( property->GetName() == <span class="stringliteral">"Font"</span> )</div>
<div class="line"> {</div>
<div class="line"> <span class="comment">// Make sure value is not unspecified</span></div>
<div class="line"> <span class="keywordflow">if</span> ( !pendingValue.<a class="code" href="classwx_variant.html#a60ce75cca3c61a25f3218d35a438f799" title="Returns true if there is no data associated with this variant, false if there is data.">IsNull</a>() )</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a> font;</div>
<div class="line"> font << pendingValue;</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Let's just allow Arial font</span></div>
<div class="line"> <span class="keywordflow">if</span> ( font.<a class="code" href="classwx_font.html#a8bc47f26fc8ac471b9d312550430adaf" title="Returns the face name associated with the font, or the empty string if there is no face information...">GetFaceName</a>() != <span class="stringliteral">"Arial"</span> )</div>
<div class="line"> {</div>
<div class="line"> <span class="keyword">event</span>.Veto();</div>
<div class="line"> <span class="keyword">event</span>.SetValidationFailureBehavior(<a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#a509a11f37ea5e56864e257cde913035ead2d679dfb2b9d9b7b3a0bedd130599c7" title="Prevents user from leaving property unless value is valid.">wxPG_VFB_STAY_IN_PROPERTY</a> |</div>
<div class="line"> <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#a509a11f37ea5e56864e257cde913035ea8a5434967b7ab365106699c8b8eb729b" title="Calls wxBell() on validation failure.">wxPG_VFB_BEEP</a> |</div>
<div class="line"> <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#a509a11f37ea5e56864e257cde913035ea80db248a442ffa85dd5155d7eb325129" title="Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the message using wxMessageBox.">wxPG_VFB_SHOW_MESSAGEBOX</a>);</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="propgrid_cellrender"></a>
Customizing Individual Cell Appearance</h1>
<p>You can control text colour, background colour, and attached image of each cell in the property grid. Use <a class="el" href="classwx_property_grid_interface.html#afd6721e817062d6c9dbb522334c029a0" title="Sets text, bitmap, and colours for given column's cell.">wxPropertyGridInterface::SetPropertyCell()</a> or <a class="el" href="classwx_p_g_property.html#a0ec5afcf091d8100142887f459d3dd52" 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="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> list items. See <a class="el" href="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> class reference for more info.</p>
<h1><a class="anchor" id="propgrid_keyhandling"></a>
Customizing Keyboard Handling</h1>
<p>There is probably one preference for keyboard handling for every developer out there, and as a conveniency control <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> tries to cater for that. By the default arrow keys are used for navigating between properties, and TAB key is used to move focus between the property editor and the first column. When the focus is in the editor, arrow keys usually no longer work for navigation since they are consumed by the editor.</p>
<p>There are mainly two functions which you can use this customize things, <a class="el" href="classwx_property_grid.html#af19463a573440f6bc928ceaa60a1e5e6" title="Adds given key combination to trigger given action.">wxPropertyGrid::AddActionTrigger()</a> and <a class="el" href="classwx_property_grid.html#a51ca791689c92a604e4b840c055cfc5d" title="Dedicates a specific keycode to wxPropertyGrid.">wxPropertyGrid::DedicateKey()</a>. First one can be used to set a navigation event to occur on a specific key press and the second is used to divert a key from property editors, making it possible for the grid to use keys normally consumed by the focused editors.</p>
<p>For example, let's say you want to have an ENTER-based editing scheme. That is, editor is focused on ENTER press and the next property is selected when the user finishes editing and presses ENTER again. Code like this would accomplish the task:</p>
<div class="fragment"><div class="line"><span class="comment">// Have property editor focus on Enter</span></div>
<div class="line">propgrid->AddActionTrigger( <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#a241dc2408e56a31edee6739e9b101b0aae9909d01fad9d6f803805212e1cbadd2" title="Move focus to the editor control of the currently selected property.">wxPG_ACTION_EDIT</a>, <a class="code" href="defs_8h.html#a41c4609211685cff198618963ec8f77daa097c8ff56f206c7df25f7e011e43e41">WXK_RETURN</a> );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Have Enter work as action trigger even when editor is focused</span></div>
<div class="line">propgrid->DedicateKey( <a class="code" href="defs_8h.html#a41c4609211685cff198618963ec8f77daa097c8ff56f206c7df25f7e011e43e41">WXK_RETURN</a> );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Let Enter also navigate to the next property</span></div>
<div class="line">propgrid->AddActionTrigger( <a class="code" href="interface_2wx_2propgrid_2propgrid_8h.html#a241dc2408e56a31edee6739e9b101b0aa44d7740b93df1d29a130cddacdaefe0e" title="Select the next property.">wxPG_ACTION_NEXT_PROPERTY</a>, <a class="code" href="defs_8h.html#a41c4609211685cff198618963ec8f77daa097c8ff56f206c7df25f7e011e43e41">WXK_RETURN</a> );</div>
</div><!-- fragment --><p>wxPG_ACTION_EDIT is prioritized above wxPG_ACTION_NEXT_PROPERTY so that the above code can work without conflicts. For a complete list of available actions, see <a class="el" href="interface_2wx_2propgrid_2propgrid_8h.html#propgrid_keyboard_actions">wxPropertyGrid Action Identifiers</a>.</p>
<p>Here's another trick. Normally the up and down cursor keys are consumed by the focused <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> editor and as such can't be used for navigating between properties when that editor is focused. However, using DedicateKey() we can change this so that instead of the cursor keys moving the caret inside the <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a>, they navigate between adjacent properties. As such:</p>
<div class="fragment"><div class="line">propgrid->DedicateKey(<a class="code" href="defs_8h.html#a41c4609211685cff198618963ec8f77dad2f4d3fb6940f1c959d2487fd96a9ba6">WXK_UP</a>);</div>
<div class="line">propgrid->DedicateKey(<a class="code" href="defs_8h.html#a41c4609211685cff198618963ec8f77da821b236b6e3cf28b0a958aa98647f1df">WXK_DOWN</a>);</div>
</div><!-- fragment --><h1><a class="anchor" id="propgrid_customizing"></a>
Customizing Properties (without sub-classing)</h1>
<p>In this section are presented miscellaneous ways to have custom appearance and behaviour for your properties without all the necessary hassle of sub-classing a property class etc.</p>
<h2><a class="anchor" id="propgrid_customimage"></a>
Setting Value Image</h2>
<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 wxColourProperty and wxImageFileProperty, but for others it can be set using <a class="el" href="classwx_property_grid_interface.html#a88befed8aa91d5c6e62844da2166bb3c" title="Set wxBitmap in front of the value.">wxPropertyGrid::SetPropertyImage</a> method.</p>
<h2><a class="anchor" id="propgrid_customeditor"></a>
Setting Property's Editor Control(s)</h2>
<p>You can set editor control (or controls, in case of a control and button), of any property using <a class="el" href="classwx_property_grid_interface.html#aff961af9dd2787fb97f510ea5ce46407" title="Sets editor for a property.">wxPropertyGrid::SetPropertyEditor</a>. Editors are passed as wxPGEditor_EditorName, 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="classwx_property_grid_interface.html#a330dc911b08378e967955f8a6a938612" title="Initializes additional property editors (SpinCtrl etc.).">wxPropertyGrid::RegisterAdditionalEditors()</a>.</p>
<p>Following example changes wxColourProperty's editor from default Choice to TextCtrlAndButton. wxColourProperty 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"><div class="line"><a class="code" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>* colProp = <span class="keyword">new</span> wxColourProperty(<span class="stringliteral">"Text Colour"</span>);</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a8496963f469db86941157f8ce67896c4" title="Appends property to the list.">Append</a>(colProp);</div>
<div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#aff961af9dd2787fb97f510ea5ce46407" title="Sets editor for a property.">SetPropertyEditor</a>(colProp, wxPGEditor_TextCtrlAndButton);</div>
</div><!-- fragment --><p>Naturally, creating and setting custom editor classes is a possibility as well. For more information, see <a class="el" href="classwx_p_g_editor.html" title="Base class for custom wxPropertyGrid editors.">wxPGEditor</a> class reference.</p>
<h2><a class="anchor" id="propgrid_editorattrs"></a>
Property Attributes Recognized by Editors</h2>
<p><b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step" and "Wrap" attributes.</p>
<h2><a class="anchor" id="propgrid_multiplebuttons"></a>
Adding Multiple Buttons Next to an Editor</h2>
<p>See <a class="el" href="classwx_p_g_multi_button.html" title="This class can be used to have multiple buttons in a property editor.">wxPGMultiButton</a> class reference.</p>
<h2><a class="anchor" id="propgrid_customeventhandling"></a>
Handling Events Passed from Properties</h2>
<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>
<h2><a class="anchor" id="propgrid_attributes"></a>
Property Attributes</h2>
<p>Miscellaneous values, often specific to a property type, can be set using <a class="el" href="classwx_property_grid_interface.html#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute for this property.">wxPropertyGridInterface::SetPropertyAttribute()</a> and <a class="el" href="classwx_property_grid_interface.html#a9ae755985b70254e3e8a27a629c3fead" title="Sets property attribute for all applicapple properties.">wxPropertyGridInterface::SetPropertyAttributeAll()</a> methods.</p>
<p>Attribute names are strings and values <a class="el" href="classwx_variant.html" title="The wxVariant class represents a container for any type.">wxVariant</a>. Arbitrary names are allowed in order to store values that are relevant to application only and not property grid. Constant equivalents of all attribute string names are provided. Some of them are defined as cached strings, so using these constants can provide for smaller binary size.</p>
<p>For complete list of attributes, see <a class="el" href="property_8h.html#propgrid_property_attributes">wxPropertyGrid Property Attribute Identifiers</a>.</p>
<h1><a class="anchor" id="propgrid_usage2"></a>
Using wxPropertyGridManager</h1>
<p><a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a> is an efficient multi-page version of <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a>, which can optionally have tool bar for mode and page selection, and a help text box. For more information, see <a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a> class reference.</p>
<h2><a class="anchor" id="propgrid_propgridpage"></a>
wxPropertyGridPage</h2>
<p><a class="el" href="classwx_property_grid_page.html" title="Holder of property grid page information.">wxPropertyGridPage</a> is holder of properties for one page in manager. It is derived from <a class="el" href="classwx_evt_handler.html" title="A class that can handle events from the windowing system.">wxEvtHandler</a>, so you can subclass it to process page-specific property grid events. Hand over your page instance in <a class="el" href="classwx_property_grid_manager.html#aea73aeb92bf18ba189198820f5341f7c" title="Creates new property page.">wxPropertyGridManager::AddPage()</a>.</p>
<p>Please note that the <a class="el" href="classwx_property_grid_page.html" title="Holder of property grid page information.">wxPropertyGridPage</a> itself only sports subset of <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> API (but unlike manager, this include item iteration). Naturally it inherits from <a class="el" href="classwx_property_grid_interface.html" title="Most of the shared property manipulation interface shared by wxPropertyGrid, wxPropertyGridPage, and wxPropertyGridManager is defined in this class.">wxPropertyGridInterface</a>.</p>
<p>For more information, see <a class="el" href="classwx_property_grid_page.html" title="Holder of property grid page information.">wxPropertyGridPage</a> class reference.</p>
<h1><a class="anchor" id="propgrid_subclassing"></a>
Sub-classing wxPropertyGrid and wxPropertyGridManager</h1>
<p>Few things to note:</p>
<ul>
<li>Only a small percentage of member functions are virtual. If you need more, just e-mail to wx-dev mailing list.</li>
</ul>
<ul>
<li>Data manipulation is done in wxPropertyGridPageState class. So, instead of overriding <a class="el" href="classwx_property_grid_interface.html#aed2f5e12acc0bc460c2295ac1564b735" title="Inserts property to the property container.">wxPropertyGrid::Insert()</a>, you'll probably want to override wxPropertyGridPageState::DoInsert(). See header file for details.</li>
</ul>
<ul>
<li>Override wxPropertyGrid::CreateState() to instantiate your derivate wxPropertyGridPageState. For <a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a>, you'll need to subclass <a class="el" href="classwx_property_grid_page.html" title="Holder of property grid page information.">wxPropertyGridPage</a> instead (since it is derived from wxPropertyGridPageState), and hand over instances in <a class="el" href="classwx_property_grid_manager.html#aea73aeb92bf18ba189198820f5341f7c" title="Creates new property page.">wxPropertyGridManager::AddPage()</a> calls.</li>
</ul>
<ul>
<li>You can use a derivate <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> with manager by overriding <a class="el" href="classwx_property_grid_manager.html#a6980326efa2bfc466aa9a5bbead7fe8c" title="Creates property grid for the manager.">wxPropertyGridManager::CreatePropertyGrid()</a> member function.</li>
</ul>
<h1><a class="anchor" id="propgrid_misc"></a>
Miscellaneous Topics</h1>
<h2><a class="anchor" id="propgrid_namescope"></a>
Property Name Scope</h2>
<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>
<h2><a class="anchor" id="propgrid_nonuniquelabels"></a>
Non-unique Labels</h2>
<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>
<h2><a class="anchor" id="propgrid_boolproperty"></a>
wxBoolProperty</h2>
<p>There are few points about wxBoolProperty that require further discussion:</p>
<ul>
<li><p class="startli">wxBoolProperty can be shown as either normal combo box or as a check box. Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this. For example, if you have a wxFlagsProperty, you can set its all items to use check box using the following: </p>
<div class="fragment"><div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a129a37f9d87a2a08516772de9860432d" title="Sets an attribute for this property.">SetPropertyAttribute</a>(<span class="stringliteral">"MyFlagsProperty"</span>, <a class="code" href="property_8h.html#a9e92f4867bf9fbc7c71779c74d18ccd1" title="wxBoolProperty and wxFlagsProperty specific.">wxPG_BOOL_USE_CHECKBOX</a>, <span class="keyword">true</span>, wxPG_RECURSE);</div>
</div><!-- fragment --><p class="startli">Following will set all individual bool properties in your control to use check box:</p>
<div class="fragment"><div class="line">pg-><a class="code" href="classwx_property_grid_interface.html#a9ae755985b70254e3e8a27a629c3fead" title="Sets property attribute for all applicapple properties.">SetPropertyAttributeAll</a>(<a class="code" href="property_8h.html#a9e92f4867bf9fbc7c71779c74d18ccd1" title="wxBoolProperty and wxFlagsProperty specific.">wxPG_BOOL_USE_CHECKBOX</a>, <span class="keyword">true</span>);</div>
</div><!-- fragment --></li>
</ul>
<ul>
<li>Default item names for wxBoolProperty are ["False", "True"]. This can be changed using static function <a class="el" href="classwx_property_grid_interface.html#ac02e6f40e5c5138a40c99a4f7b98100b" title="Sets strings listed in the choice dropdown of a wxBoolProperty.">wxPropertyGrid::SetBoolChoices</a>(trueChoice, falseChoice).</li>
</ul>
<h2><a class="anchor" id="propgrid_textctrlupdates"></a>
Updates from wxTextCtrl Based Editor</h2>
<p>Changes from <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> based property editors are committed (ie. wxEVT_PG_CHANGED is sent etc.) <em>only</em> 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="classwx_property_grid.html#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>
<h2><a class="anchor" id="propgrid_splittercentering"></a>
Centering the Splitter</h2>
<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="classwx_property_grid.html#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 behaviour can be customized using <a class="el" href="classwx_property_grid_interface.html#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) from being 'centered' as such, and instead just auto-resized.</p>
<h2><a class="anchor" id="propgrid_splittersetting"></a>
Setting Splitter Position When Creating Property Grid</h2>
<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>
<h2><a class="anchor" id="propgrid_colourproperty"></a>
wxColourProperty and wxSystemColourProperty</h2>
<p>Through sub-classing, these two property classes provide substantial customization features. Subclass wxSystemColourProperty if you want to use wxColourPropertyValue (which features colour type in addition to <a class="el" href="classwx_colour.html" title="A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values...">wxColour</a>), and wxColourProperty if plain <a class="el" href="classwx_colour.html" title="A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values...">wxColour</a> is enough.</p>
<p>Override wxSystemColourProperty::ColourToString() to redefine how colours are printed as strings.</p>
<p>Override wxSystemColourProperty::GetCustomColourIndex() to redefine location of the item that triggers colour picker dialog (default is last).</p>
<p>Override wxSystemColourProperty::GetColour() to determine which colour matches which choice entry.</p>
<h1><a class="anchor" id="propgrid_proplist"></a>
Property Class Descriptions</h1>
<p>See <a class="el" href="classwx_p_g_property.html#pgproperty_properties">Supplied Ready-to-use Property Classes</a></p>
<h1><a class="anchor" id="propgrid_compat"></a>
Changes from wxPropertyGrid 1.4</h1>
<p>Version of <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> bundled with wxWidgets 2.9+ has various backward- incompatible changes from version 1.4, which had a stable API and will remain as the last separate branch.</p>
<p>Note that in general any behaviour-breaking changes should not compile or run without warnings or errors.</p>
<h2><a class="anchor" id="propgrid_compat_general"></a>
General Changes</h2>
<ul>
<li>Tab-traversal can no longer be used to travel between properties. Now it only causes focus to move from main grid to editor of selected property. Arrow keys are now your primary means of navigating between properties, with keyboard. This change allowed fixing broken tab traversal on wxGTK (which is open issue in <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> 1.4).</li>
</ul>
<ul>
<li>wxPG_EX_UNFOCUS_ON_ENTER style is removed and is now default behaviour. That is, when enter is pressed, editing is considered done and focus moves back to the property grid from the editor control.</li>
</ul>
<ul>
<li>A few member functions were removed from <a class="el" href="classwx_property_grid_interface.html" title="Most of the shared property manipulation interface shared by wxPropertyGrid, wxPropertyGridPage, and wxPropertyGridManager is defined in this class.">wxPropertyGridInterface</a>. Please use <a class="el" href="classwx_p_g_property.html" title="wxPGProperty is base class for all wxPropertyGrid properties.">wxPGProperty</a>'s counterparts from now on.</li>
</ul>
<ul>
<li><a class="el" href="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> now has proper Copy-On-Write behaviour.</li>
</ul>
<ul>
<li>wxPGChoices::SetExclusive() was renamed to AllocExclusive().</li>
</ul>
<ul>
<li>wxPGProperty::SetPropertyChoicesExclusive() was removed. Instead, use GetChoices().AllocExclusive().</li>
</ul>
<ul>
<li>wxPGProperty::ClearModifiedStatus() is removed. Please use SetModifiedStatus() instead.</li>
</ul>
<ul>
<li>wxPropertyGridInterface::GetExpandedProperties() is removed. You should now use wxPropertyGridInterface::GetEditableState() instead.</li>
</ul>
<ul>
<li>wxPG_EX_DISABLE_TLP_TRACKING is now enabled by default. To get the old behaviour (recommended if you don't use a system that reparents the grid on its own), use the wxPG_EX_ENABLE_TLP_TRACKING extra style.</li>
</ul>
<ul>
<li>Extended window style wxPG_EX_LEGACY_VALIDATORS was removed.</li>
</ul>
<ul>
<li>Default property validation failure behaviour has been changed to (wxPG_VFB_MARK_CELL | wxPG_VFB_SHOW_MESSAGEBOX), which means that the cell is marked red and wxMessageBox is shown. This is more user-friendly than the old behaviour, which simply beeped and prevented leaving the property editor until a valid value was entered.</li>
</ul>
<ul>
<li><a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a> now has same Get/SetSelection() semantics as <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a>.</li>
</ul>
<ul>
<li>Various <a class="el" href="classwx_property_grid_manager.html" title="wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have...">wxPropertyGridManager</a> page-related functions now return pointer to the page object instead of index.</li>
</ul>
<ul>
<li>wxArrayEditorDialog used by wxArrayStringProperty and some sample properties has been renamed to wxPGArrayEditorDialog. Also, it now uses <a class="el" href="classwx_editable_list_box.html" title="An editable listbox is composite control that lets the user easily enter, delete and reorder a list o...">wxEditableListBox</a> for editing.</li>
</ul>
<ul>
<li>Instead of calling wxPropertyGrid::SetButtonShortcut(), use wxPropertyGrid::SetActionTrigger(wxPG_ACTION_PRESS_BUTTON).</li>
</ul>
<ul>
<li><a class="el" href="classwx_p_g_property.html#af2f256f0d3eda31b18548eaf3c5e992d" title="Returns wxPGCell of given column.">wxPGProperty::GetCell()</a> now returns a reference. AcquireCell() was removed.</li>
</ul>
<ul>
<li>wxPGMultiButton::FinalizePosition() has been renamed to Finalize(), and it has slightly different argument list.</li>
</ul>
<ul>
<li>wxPropertyGridEvent::HasProperty() is removed. You can use GetProperty() as immediate replacement when checking if event has a property.</li>
</ul>
<ul>
<li>"InlineHelp" property has been replaced with "Hint".</li>
</ul>
<ul>
<li>wxPropertyGrid::CanClose() has been removed. Call <a class="el" href="classwx_property_grid_interface.html#a7718a5497b7e5211d847b5a8134bc2ab" title="Returns true if all property grid data changes have been committed.">wxPropertyGridInterface::EditorValidate()</a> instead.</li>
</ul>
<ul>
<li>wxPGProperty::SetFlag() has been moved to private API. This was done to underline the fact that it was not the preferred method to change a property's state since it never had any desired side-effects. ChangeFlag() still exists for those who really need to achieve the same effect.</li>
</ul>
<ul>
<li>wxArrayStringProperty default delimiter is now comma (','), and it can be changed by setting the new "Delimiter" attribute.</li>
</ul>
<h2><a class="anchor" id="propgrid_compat_propdev"></a>
Property and Editor Sub-classing Changes</h2>
<ul>
<li>Confusing custom property macros have been eliminated.</li>
</ul>
<ul>
<li>Implement <a class="el" href="classwx_p_g_property.html#a7bef52444b2c03a4f10eef54ef9e9739" title="Converts property value into a text representation.">wxPGProperty::ValueToString()</a> instead of GetValueAsString().</li>
</ul>
<ul>
<li><a class="el" href="classwx_p_g_property.html#ac3d79ee3ebbbff20c36627d92ea926e1" title="Called after value of a child property has been altered.">wxPGProperty::ChildChanged()</a> must now return the modified value of whole property instead of writing it back into 'thisValue' argument.</li>
</ul>
<ul>
<li>Removed wxPropertyGrid::PrepareValueForDialogEditing(). Use wxPropertyGrid::GetPendingEditedValue() instead.</li>
</ul>
<ul>
<li>wxPGProperty::GetChoiceInfo() is removed, as all properties now carry <a class="el" href="classwx_p_g_choices.html" title="Helper class for managing choices of wxPropertyGrid properties.">wxPGChoices</a> instance (protected wxPGProperty::m_choices).</li>
</ul>
<ul>
<li>Connect() should no longer be called in implementations of <a class="el" href="classwx_p_g_editor.html#a9d33fbd55fe4fe390bdaa826a7ff87e2" title="Instantiates editor controls.">wxPGEditor::CreateControls()</a>. <a class="el" href="classwx_property_grid.html" title="wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs...">wxPropertyGrid</a> automatically passes all events from editor to <a class="el" href="classwx_p_g_editor.html#a035fa3bee4ac87e4300df0c637a56261" title="Handles events.">wxPGEditor::OnEvent()</a> and <a class="el" href="classwx_p_g_property.html#a16fbe26240bf47ab0a9a02d21781da73" title="Events received by editor widgets are processed here.">wxPGProperty::OnEvent()</a>, as appropriate.</li>
</ul>
<ul>
<li>wxPython: Previously some of the reimplemented member functions needed a 'Py' prefix. This is no longer necessary. For instance, if you previously implemented PyStringToValue() for your custom property, you should now just implement StringToValue(). </li>
</ul>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
