]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: property.h | |
3 | // Purpose: interface of wxPGProperty | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | ||
10 | #define wxNullProperty ((wxPGProperty*)NULL) | |
11 | ||
12 | ||
13 | /** | |
14 | @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers | |
15 | ||
16 | wxPGProperty::SetAttribute() and wxPropertyGridInterface::SetPropertyAttribute() | |
17 | accept one of these as attribute name argument. | |
18 | ||
19 | You can use strings instead of constants. | |
20 | However, some of these constants are redefined to use cached strings which | |
21 | may reduce your binary size by some amount. | |
22 | ||
23 | @{ | |
24 | */ | |
25 | ||
26 | /** Set default value for property. | |
27 | */ | |
28 | #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue") | |
29 | ||
30 | /** Universal, int or double. Minimum value for numeric properties. | |
31 | */ | |
32 | #define wxPG_ATTR_MIN wxS("Min") | |
33 | ||
34 | /** Universal, int or double. Maximum value for numeric properties. | |
35 | */ | |
36 | #define wxPG_ATTR_MAX wxS("Max") | |
37 | ||
38 | /** Universal, string. When set, will be shown as text after the displayed | |
39 | text value. Alternatively, if third column is enabled, text will be shown | |
40 | there (for any type of property). | |
41 | */ | |
42 | #define wxPG_ATTR_UNITS wxS("Units") | |
43 | ||
44 | /** Universal, string. When set, will be shown in property's value cell | |
45 | when displayed value string is empty, or value is unspecified. | |
46 | */ | |
47 | #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp") | |
48 | ||
49 | /** Universal, wxArrayString. Set to enable auto-completion in any | |
50 | wxTextCtrl-based property editor. | |
51 | */ | |
52 | #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete") | |
53 | ||
54 | /** wxBoolProperty and wxFlagsProperty specific. Value type is bool. | |
55 | Default value is False. | |
56 | ||
57 | When set to True, bool property will use check box instead of a | |
58 | combo box as its editor control. If you set this attribute | |
59 | for a wxFlagsProperty, it is automatically applied to child | |
60 | bool properties. | |
61 | */ | |
62 | #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox") | |
63 | ||
64 | /** wxBoolProperty and wxFlagsProperty specific. Value type is bool. | |
65 | Default value is False. | |
66 | ||
67 | Set to True for the bool property to cycle value on double click | |
68 | (instead of showing the popup listbox). If you set this attribute | |
69 | for a wxFlagsProperty, it is automatically applied to child | |
70 | bool properties. | |
71 | */ | |
72 | #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling") | |
73 | ||
74 | /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision | |
75 | used when floating point value is rendered as text. The default -1 means infinite | |
76 | precision. | |
77 | */ | |
78 | #define wxPG_FLOAT_PRECISION wxS("Precision") | |
79 | ||
80 | /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc). | |
81 | */ | |
82 | #define wxPG_STRING_PASSWORD wxS("Password") | |
83 | ||
84 | /** Define base used by a wxUIntProperty. Valid constants are | |
85 | wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL | |
86 | (lowercase characters). | |
87 | */ | |
88 | #define wxPG_UINT_BASE wxS("Base") | |
89 | ||
90 | /** Define prefix rendered to wxUIntProperty. Accepted constants | |
91 | wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN. | |
92 | <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal | |
93 | numbers. | |
94 | */ | |
95 | #define wxPG_UINT_PREFIX wxS("Prefix") | |
96 | ||
97 | /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies. | |
98 | Sets the wildcard used in the triggered wxFileDialog. Format is the | |
99 | same. | |
100 | */ | |
101 | #define wxPG_FILE_WILDCARD wxS("Wildcard") | |
102 | ||
103 | /** wxFileProperty/wxImageFileProperty specific, int, default 1. | |
104 | When 0, only the file name is shown (i.e. drive and directory are hidden). | |
105 | */ | |
106 | #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath") | |
107 | ||
108 | /** Specific to wxFileProperty and derived properties, wxString, default empty. | |
109 | If set, then the filename is shown relative to the given path string. | |
110 | */ | |
111 | #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath") | |
112 | ||
113 | /** Specific to wxFileProperty and derived properties, wxString, default is empty. | |
114 | Sets the initial path of where to look for files. | |
115 | */ | |
116 | #define wxPG_FILE_INITIAL_PATH wxS("InitialPath") | |
117 | ||
118 | /** Specific to wxFileProperty and derivatives, wxString, default is empty. | |
119 | Sets a specific title for the dir dialog. | |
120 | */ | |
121 | #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle") | |
122 | ||
123 | /** Specific to wxDirProperty, wxString, default is empty. | |
124 | Sets a specific message for the dir dialog. | |
125 | */ | |
126 | #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage") | |
127 | ||
128 | /** Sets displayed date format for wxDateProperty. | |
129 | */ | |
130 | #define wxPG_DATE_FORMAT wxS("DateFormat") | |
131 | ||
132 | /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default | |
133 | is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable | |
134 | better unspecified value support in the editor. | |
135 | */ | |
136 | #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle") | |
137 | ||
138 | /** SpinCtrl editor, int or double. How much number changes when button is | |
139 | pressed (or up/down on keybard). | |
140 | */ | |
141 | #define wxPG_ATTR_SPINCTRL_STEP wxS("Step") | |
142 | ||
143 | /** SpinCtrl editor, bool. If @true, value wraps at Min/Max. | |
144 | */ | |
145 | #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap") | |
146 | ||
147 | /** SpinCtrl editor, bool. If @true, value can also by changed by moving | |
148 | mouse when left mouse button is being pressed. | |
149 | */ | |
150 | #define wxPG_ATTR_SPINCTRL_MOTIONSPIN wxS("MotionSpin") | |
151 | ||
152 | /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings | |
153 | appear before list strings. If 2, user strings appear after list string. | |
154 | */ | |
155 | #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode") | |
156 | ||
157 | /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom | |
158 | colour from property's list of choices. | |
159 | */ | |
160 | #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom") | |
161 | ||
162 | /** @} | |
163 | */ | |
164 | ||
165 | ||
166 | ||
167 | /** | |
168 | @class wxPGProperty | |
169 | ||
170 | wxPGProperty is base class for all wxPropertyGrid properties. In | |
171 | sections below we cover few related topics. | |
172 | ||
173 | @li @ref pgproperty_properties | |
174 | @li @ref pgproperty_creating | |
175 | ||
176 | @section pgproperty_properties Supplied Ready-to-use Property Classes | |
177 | ||
178 | Here is a list and short description of supplied fully-functional | |
179 | property classes. They are located in either props.h or advprops.h. | |
180 | ||
181 | @li @ref wxArrayStringProperty | |
182 | @li @ref wxBoolProperty | |
183 | @li @ref wxColourProperty | |
184 | @li @ref wxCursorProperty | |
185 | @li @ref wxDateProperty | |
186 | @li @ref wxDirProperty | |
187 | @li @ref wxEditEnumProperty | |
188 | @li @ref wxEnumProperty | |
189 | @li @ref wxFileProperty | |
190 | @li @ref wxFlagsProperty | |
191 | @li @ref wxFloatProperty | |
192 | @li @ref wxFontProperty | |
193 | @li @ref wxImageFileProperty | |
194 | @li @ref wxIntProperty | |
195 | @li @ref wxLongStringProperty | |
196 | @li @ref wxMultiChoiceProperty | |
197 | @li @ref wxPropertyCategory | |
198 | @li @ref wxStringProperty | |
199 | @li @ref wxSystemColourProperty | |
200 | @li @ref wxUIntProperty | |
201 | ||
202 | @subsection wxPropertyCategory | |
203 | ||
204 | Not an actual property per se, but a header for a group of properties. | |
205 | Regardless inherits from wxPGProperty. | |
206 | ||
207 | @subsection wxStringProperty | |
208 | ||
209 | Simple string property. wxPG_STRING_PASSWORD attribute may be used | |
210 | to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl. | |
211 | wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion | |
212 | (use a wxArrayString value), and is also supported by any property that | |
213 | happens to use a wxTextCtrl-based editor. | |
214 | ||
215 | @remarks wxStringProperty has a special trait: if it has value of | |
216 | "<composed>", and also has child properties, then its displayed | |
217 | value becomes composition of child property values, similar as | |
218 | with wxFontProperty, for instance. | |
219 | ||
220 | @subsection wxIntProperty | |
221 | ||
222 | Like wxStringProperty, but converts text to a signed long integer. | |
223 | wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong). | |
224 | To safely convert variant to integer, use code like this: | |
225 | ||
226 | @code | |
227 | wxLongLong ll; | |
228 | ll << property->GetValue(); | |
229 | ||
230 | // or | |
231 | wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property); | |
232 | @endcode | |
233 | ||
234 | @subsection wxUIntProperty | |
235 | ||
236 | Like wxIntProperty, but displays value as unsigned int. To set | |
237 | the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute. | |
238 | To set the globally used base, manipulate wxPG_UINT_BASE int | |
239 | attribute. Regardless of current prefix, understands (hex) values starting | |
240 | with both "0x" and "$". | |
241 | Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned | |
242 | integers (ie. wxULongLong). Same wxVariant safety rules apply. | |
243 | ||
244 | @subsection wxFloatProperty | |
245 | ||
246 | Like wxStringProperty, but converts text to a double-precision floating point. | |
247 | Default float-to-text precision is 6 decimals, but this can be changed | |
248 | by modifying wxPG_FLOAT_PRECISION attribute. | |
249 | ||
250 | @subsection wxBoolProperty | |
251 | ||
252 | Represents a boolean value. wxChoice is used as editor control, by the | |
253 | default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use | |
254 | check box instead. | |
255 | ||
256 | @subsection wxLongStringProperty | |
257 | ||
258 | Like wxStringProperty, but has a button that triggers a small text editor | |
259 | dialog. Note that in long string values, tabs are represented by "\t" and | |
260 | line break by "\n". | |
261 | ||
262 | To display custom dialog on button press, you can subclass | |
263 | wxLongStringProperty and implement OnButtonClick, like this: | |
264 | ||
265 | @code | |
266 | virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value ) | |
267 | { | |
268 | wxSize dialogSize(...size of your dialog...); | |
269 | ||
270 | wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this, | |
271 | dialogSize) | |
272 | ||
273 | // Create dialog dlg at dlgPos. Use value as initial string | |
274 | // value. | |
275 | ... | |
276 | ||
277 | if ( dlg.ShowModal() == wxID_OK ) | |
278 | { | |
279 | value = dlg.GetStringValue); | |
280 | return true; | |
281 | } | |
282 | return false; | |
283 | } | |
284 | @endcode | |
285 | ||
286 | Also, if you wish not to have line breaks and tabs translated to | |
287 | escape sequences, then do following in constructor of your subclass: | |
288 | ||
289 | @code | |
290 | m_flags |= wxPG_PROP_NO_ESCAPE; | |
291 | @endcode | |
292 | ||
293 | @subsection wxDirProperty | |
294 | ||
295 | Like wxLongStringProperty, but the button triggers dir selector instead. | |
296 | Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE. | |
297 | ||
298 | @subsection wxFileProperty | |
299 | ||
300 | Like wxLongStringProperty, but the button triggers file selector instead. | |
301 | Default wildcard is "All files..." but this can be changed by setting | |
302 | wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details). | |
303 | Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show | |
304 | only the filename, not the entire path. | |
305 | ||
306 | @subsection wxEnumProperty | |
307 | ||
308 | Represents a single selection from a list of choices - | |
309 | wxOwnerDrawnComboBox is used to edit the value. | |
310 | ||
311 | @subsection wxFlagsProperty | |
312 | ||
313 | Represents a bit set that fits in a long integer. wxBoolProperty sub- | |
314 | properties are created for editing individual bits. Textctrl is created to | |
315 | manually edit the flags as a text; a continous sequence of spaces, commas | |
316 | and semicolons are considered as a flag id separator. | |
317 | ||
318 | <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty, | |
319 | you will need to use wxPGProperty::SetChoices() - otherwise they will not | |
320 | get updated properly. | |
321 | ||
322 | wxFlagsProperty supports the same attributes as wxBoolProperty. | |
323 | ||
324 | @subsection wxArrayStringProperty | |
325 | ||
326 | Allows editing of a list of strings in wxTextCtrl and in a separate dialog. | |
327 | ||
328 | @subsection wxDateProperty | |
329 | ||
330 | wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl | |
331 | should work as well. wxPG_DATE_FORMAT attribute can be used to change | |
332 | string wxDateTime::Format uses (altough default is recommended as it is | |
333 | locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window | |
334 | style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY). | |
335 | Using wxDP_ALLOWNONE will enable better unspecified value support. | |
336 | ||
337 | @subsection wxEditEnumProperty | |
338 | ||
339 | Represents a string that can be freely edited or selected from list of choices - | |
340 | custom combobox control is used to edit the value. | |
341 | ||
342 | @subsection wxMultiChoiceProperty | |
343 | ||
344 | Allows editing a multiple selection from a list of strings. This is | |
345 | property is pretty much built around concept of wxMultiChoiceDialog. | |
346 | It uses wxArrayString value. | |
347 | ||
348 | @subsection wxImageFileProperty | |
349 | ||
350 | Like wxFileProperty, but has thumbnail of the image in front of | |
351 | the filename and autogenerates wildcard from available image handlers. | |
352 | ||
353 | @subsection wxColourProperty | |
354 | ||
355 | <b>Useful alternate editor:</b> Choice. | |
356 | ||
357 | Represents wxColour. wxButton is used to trigger a colour picker dialog. | |
358 | There are various sub-classing opportunities with this class. See | |
359 | below in wxSystemColourProperty section for details. | |
360 | ||
361 | @subsection wxFontProperty | |
362 | ||
363 | Represents wxFont. Various sub-properties are used to edit individual | |
364 | subvalues. | |
365 | ||
366 | @subsection wxSystemColourProperty | |
367 | ||
368 | Represents wxColour and a system colour index. wxChoice is used to edit | |
369 | the value. Drop-down list has color images. Note that value type | |
370 | is wxColourPropertyValue instead of wxColour (which wxColourProperty | |
371 | uses). | |
372 | ||
373 | @code | |
374 | class wxColourPropertyValue : public wxObject | |
375 | { | |
376 | public: | |
377 | // An integer value relating to the colour, and which exact | |
378 | // meaning depends on the property with which it is used. | |
379 | // | |
380 | // For wxSystemColourProperty: | |
381 | // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR | |
382 | // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM. | |
383 | wxUint32 m_type; | |
384 | ||
385 | // Resulting colour. Should be correct regardless of type. | |
386 | wxColour m_colour; | |
387 | }; | |
388 | @endcode | |
389 | ||
390 | in wxSystemColourProperty, and its derived class wxColourProperty, there | |
391 | are various sub-classing features. To set basic list list of colour | |
392 | names, call wxPGProperty::SetChoices(). | |
393 | ||
394 | @code | |
395 | // Override in derived class to customize how colours are translated | |
396 | // to strings. | |
397 | virtual wxString ColourToString( const wxColour& col, int index ) const; | |
398 | ||
399 | // Returns index of entry that triggers colour picker dialog | |
400 | // (default is last). | |
401 | virtual int GetCustomColourIndex() const; | |
402 | ||
403 | // Helper function to show the colour dialog | |
404 | bool QueryColourFromUser( wxVariant& variant ) const; | |
405 | ||
406 | // Returns colour for given choice. | |
407 | // Default function returns wxSystemSettings::GetColour(index). | |
408 | virtual wxColour GetColour( int index ) const; | |
409 | @endcode | |
410 | ||
411 | @subsection wxCursorProperty | |
412 | ||
413 | Represents a wxCursor. wxChoice is used to edit the value. | |
414 | Drop-down list has cursor images under some (wxMSW) platforms. | |
415 | ||
416 | ||
417 | @section pgproperty_creating Creating Custom Properties | |
418 | ||
419 | New properties can be created by subclassing wxPGProperty or one | |
420 | of the provided property classes, and (re)implementing necessary | |
421 | member functions. Below, each virtual member function has ample | |
422 | documentation about its purpose and any odd details which to keep | |
423 | in mind. | |
424 | ||
425 | Here is a very simple 'template' code: | |
426 | ||
427 | @code | |
428 | class MyProperty : public wxPGProperty | |
429 | { | |
430 | public: | |
431 | // All arguments of ctor must have a default value - | |
432 | // use wxPG_LABEL for label and name | |
433 | MyProperty( const wxString& label = wxPG_LABEL, | |
434 | const wxString& name = wxPG_LABEL, | |
435 | const wxString& value = wxEmptyString ) | |
436 | { | |
437 | // m_value is wxVariant | |
438 | m_value = value; | |
439 | } | |
440 | ||
441 | virtual ~MyProperty() { } | |
442 | ||
443 | const wxPGEditor* DoGetEditorClass() const | |
444 | { | |
445 | // Determines editor used by property. | |
446 | // You can replace 'TextCtrl' below with any of these | |
447 | // builtin-in property editor identifiers: Choice, ComboBox, | |
448 | // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl, | |
449 | // DatePickerCtrl. | |
450 | return wxPGEditor_TextCtrl; | |
451 | } | |
452 | ||
453 | virtual wxString ValueToString( wxVariant& value, | |
454 | int argFlags ) const | |
455 | { | |
456 | // TODO: Convert given property value to a string | |
457 | } | |
458 | ||
459 | virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags ) | |
460 | { | |
461 | // TODO: Adapt string to property value. | |
462 | } | |
463 | ||
464 | protected: | |
465 | }; | |
466 | @endcode | |
467 | ||
468 | Since wxPGProperty derives from wxObject, you can use standard | |
469 | DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the | |
470 | above example they were omitted for sake of simplicity, and besides, | |
471 | they are only really needed if you need to use wxRTTI with your | |
472 | property class. | |
473 | ||
474 | You can change the 'value type' of a property by simply assigning different | |
475 | type of variant with SetValue. <b>It is mandatory to implement | |
476 | wxVariantData class for all data types used as property values.</b> | |
477 | You can use macros declared in wxPropertyGrid headers. For instance: | |
478 | ||
479 | @code | |
480 | // In header file: | |
481 | // (If you need to have export declaration, use version of macros | |
482 | // with _EXPORTED postfix) | |
483 | WX_PG_DECLARE_VARIANT_DATA(MyDataClass) | |
484 | ||
485 | // In sources file: | |
486 | WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass) | |
487 | ||
488 | // Or, if you don't have valid == operator: | |
489 | WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass) | |
490 | @endcode | |
491 | ||
492 | @library{wxpropgrid} | |
493 | @category{propgrid} | |
494 | */ | |
495 | class wxPGProperty : public wxObject | |
496 | { | |
497 | public: | |
498 | typedef wxUint32 FlagType; | |
499 | ||
500 | /** | |
501 | Default constructor. | |
502 | */ | |
503 | wxPGProperty(); | |
504 | ||
505 | /** | |
506 | Constructor. | |
507 | Non-abstract property classes should have constructor of this style: | |
508 | ||
509 | @code | |
510 | ||
511 | MyProperty( const wxString& label, const wxString& name, const T& value ) | |
512 | : wxPGProperty() | |
513 | { | |
514 | // Generally recommended way to set the initial value | |
515 | // (as it should work in pretty much 100% of cases). | |
516 | wxVariant variant; | |
517 | variant << value; | |
518 | SetValue(variant); | |
519 | ||
520 | // If has private child properties then create them here. | |
521 | // For example: | |
522 | // AddPrivateChild( new wxStringProperty("Subprop 1", | |
523 | // wxPG_LABEL, | |
524 | // value.GetSubProp1())); | |
525 | } | |
526 | ||
527 | @endcode | |
528 | */ | |
529 | wxPGProperty( const wxString& label, const wxString& name ); | |
530 | ||
531 | /** | |
532 | Virtual destructor. It is customary for derived properties to implement this. | |
533 | */ | |
534 | virtual ~wxPGProperty(); | |
535 | ||
536 | /** | |
537 | This virtual function is called after m_value has been set. | |
538 | ||
539 | @remarks | |
540 | - If m_value was set to Null variant (ie. unspecified value), OnSetValue() | |
541 | will not be called. | |
542 | - m_value may be of any variant type. Typically properties internally support only | |
543 | one variant type, and as such OnSetValue() provides a good opportunity to convert | |
544 | supported values into internal type. | |
545 | - Default implementation does nothing. | |
546 | */ | |
547 | virtual void OnSetValue(); | |
548 | ||
549 | /** | |
550 | Override this to return something else than m_value as the value. | |
551 | */ | |
552 | virtual wxVariant DoGetValue() const; | |
553 | ||
554 | /** | |
555 | Implement this function in derived class to check the value. | |
556 | Return @true if it is ok. Returning @false prevents property change events | |
557 | from occurring. | |
558 | ||
559 | @remarks | |
560 | - Default implementation always returns @true. | |
561 | */ | |
562 | virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const; | |
563 | ||
564 | /** | |
565 | Converts text into wxVariant value appropriate for this property. | |
566 | ||
567 | @param variant | |
568 | On function entry this is the old value (should not be wxNullVariant | |
569 | in normal cases). Translated value must be assigned back to it. | |
570 | ||
571 | @param text | |
572 | Text to be translated into variant. | |
573 | ||
574 | @param argFlags | |
575 | If wxPG_FULL_VALUE is set, returns complete, storable value instead | |
576 | of displayable one (they may be different). | |
577 | If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of | |
578 | composite property string value (as generated by ValueToString() | |
579 | called with this same flag). | |
580 | ||
581 | @return Returns @true if resulting wxVariant value was different. | |
582 | ||
583 | @remarks Default implementation converts semicolon delimited tokens into | |
584 | child values. Only works for properties with children. | |
585 | ||
586 | You might want to take into account that m_value is Null variant | |
587 | if property value is unspecified (which is usually only case if | |
588 | you explicitly enabled that sort behavior). | |
589 | */ | |
590 | virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const; | |
591 | ||
592 | /** | |
593 | Converts integer (possibly a choice selection) into wxVariant value | |
594 | appropriate for this property. | |
595 | ||
596 | @param variant | |
597 | On function entry this is the old value (should not be wxNullVariant | |
598 | in normal cases). Translated value must be assigned back to it. | |
599 | @param number | |
600 | Integer to be translated into variant. | |
601 | @param argFlags | |
602 | If wxPG_FULL_VALUE is set, returns complete, storable value instead | |
603 | of displayable one. | |
604 | ||
605 | @return Returns @true if resulting wxVariant value was different. | |
606 | ||
607 | @remarks | |
608 | - If property is not supposed to use choice or spinctrl or other editor | |
609 | with int-based value, it is not necessary to implement this method. | |
610 | - Default implementation simply assign given int to m_value. | |
611 | - If property uses choice control, and displays a dialog on some choice | |
612 | items, then it is preferred to display that dialog in IntToValue | |
613 | instead of OnEvent. | |
614 | - You might want to take into account that m_value is Mull variant if | |
615 | property value is unspecified (which is usually only case if you | |
616 | explicitly enabled that sort behavior). | |
617 | */ | |
618 | virtual bool IntToValue( wxVariant& variant, int number, int argFlags = 0 ) const; | |
619 | ||
620 | /** | |
621 | Converts property value into a text representation. | |
622 | ||
623 | @param value | |
624 | Value to be converted. | |
625 | @param argFlags | |
626 | If 0 (default value), then displayed string is returned. | |
627 | If wxPG_FULL_VALUE is set, returns complete, storable string value | |
628 | instead of displayable. If wxPG_EDITABLE_VALUE is set, returns | |
629 | string value that must be editable in textctrl. | |
630 | If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to | |
631 | display as a part of string property's composite text representation. | |
632 | ||
633 | @remarks Default implementation calls GenerateComposedValue(). | |
634 | */ | |
635 | virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const; | |
636 | ||
637 | /** | |
638 | Converts string to a value, and if successful, calls SetValue() on it. | |
639 | Default behavior is to do nothing. | |
640 | ||
641 | @param text | |
642 | String to get the value from. | |
643 | @param flags | |
644 | @todo docme | |
645 | ||
646 | @return @true if value was changed. | |
647 | */ | |
648 | bool SetValueFromString( const wxString& text, int flags = 0 ); | |
649 | ||
650 | /** | |
651 | Converts integer to a value, and if succesful, calls SetValue() on it. | |
652 | Default behavior is to do nothing. | |
653 | ||
654 | @param value | |
655 | Int to get the value from. | |
656 | @param flags | |
657 | If has wxPG_FULL_VALUE, then the value given is a actual value and not an index. | |
658 | ||
659 | @return @true if value was changed. | |
660 | */ | |
661 | bool SetValueFromInt( long value, int flags = 0 ); | |
662 | ||
663 | /** | |
664 | Returns size of the custom painted image in front of property. This method | |
665 | must be overridden to return non-default value if OnCustomPaint is to be | |
666 | called. | |
667 | ||
668 | @param item | |
669 | Normally -1, but can be an index to the property's list of items. | |
670 | ||
671 | @remarks | |
672 | - Default behavior is to return wxSize(0,0), which means no image. | |
673 | - Default image width or height is indicated with dimension -1. | |
674 | - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1). | |
675 | */ | |
676 | virtual wxSize OnMeasureImage( int item = -1 ) const; | |
677 | ||
678 | /** | |
679 | Events received by editor widgets are processed here. Note that editor class | |
680 | usually processes most events. Some, such as button press events of | |
681 | TextCtrlAndButton class, can be handled here. Also, if custom handling | |
682 | for regular events is desired, then that can also be done (for example, | |
683 | wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED | |
684 | to display colour picker dialog when 'custom' selection is made). | |
685 | ||
686 | If the event causes value to be changed, SetValueInEvent() should be called | |
687 | to set the new value. | |
688 | ||
689 | The parameter @a event is the associated wxEvent. | |
690 | ||
691 | @retval | |
692 | Should return @true if any changes in value should be reported. | |
693 | ||
694 | @remarks | |
695 | - If property uses choice control, and displays a dialog on some choice items, | |
696 | then it is preferred to display that dialog in IntToValue instead of OnEvent. | |
697 | */ | |
698 | virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event ); | |
699 | ||
700 | /** | |
701 | Called after value of a child property has been altered. Note that this function is | |
702 | usually called at the time that value of this property, or given child property, is | |
703 | still pending for change. | |
704 | ||
705 | Sample pseudo-code implementation: | |
706 | ||
707 | @code | |
708 | void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const | |
709 | { | |
710 | // Acquire reference to actual type of data stored in variant | |
711 | // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create | |
712 | // the variant class). | |
713 | T& data = TFromVariant(thisValue); | |
714 | ||
715 | // Copy childValue into data. | |
716 | switch ( childIndex ) | |
717 | { | |
718 | case 0: | |
719 | data.SetSubProp1( childvalue.GetLong() ); | |
720 | break; | |
721 | case 1: | |
722 | data.SetSubProp2( childvalue.GetString() ); | |
723 | break; | |
724 | ... | |
725 | } | |
726 | } | |
727 | @endcode | |
728 | ||
729 | @param thisValue | |
730 | Value of this property, that should be altered. | |
731 | @param childIndex | |
732 | Index of child changed (you can use Item(childIndex) to get). | |
733 | @param childValue | |
734 | Value of the child property. | |
735 | */ | |
736 | virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const; | |
737 | ||
738 | /** | |
739 | Returns pointer to an instance of used editor. | |
740 | */ | |
741 | virtual const wxPGEditor* DoGetEditorClass() const; | |
742 | ||
743 | /** | |
744 | Returns pointer to the wxValidator that should be used | |
745 | with the editor of this property (@NULL for no validator). | |
746 | Setting validator explicitly via SetPropertyValidator | |
747 | will override this. | |
748 | ||
749 | In most situations, code like this should work well | |
750 | (macros are used to maintain one actual validator instance, | |
751 | so on the second call the function exits within the first | |
752 | macro): | |
753 | ||
754 | @code | |
755 | ||
756 | wxValidator* wxMyPropertyClass::DoGetValidator () const | |
757 | { | |
758 | WX_PG_DOGETVALIDATOR_ENTRY() | |
759 | ||
760 | wxMyValidator* validator = new wxMyValidator(...); | |
761 | ||
762 | ... prepare validator... | |
763 | ||
764 | WX_PG_DOGETVALIDATOR_EXIT(validator) | |
765 | } | |
766 | ||
767 | @endcode | |
768 | ||
769 | @remarks | |
770 | You can get common filename validator by returning | |
771 | wxFileProperty::GetClassValidator(). wxDirProperty, | |
772 | for example, uses it. | |
773 | */ | |
774 | virtual wxValidator* DoGetValidator () const; | |
775 | ||
776 | /** | |
777 | Override to paint an image in front of the property value text or drop-down | |
778 | list item (but only if wxPGProperty::OnMeasureImage is overridden as well). | |
779 | ||
780 | If property's OnMeasureImage() returns size that has height != 0 but less than | |
781 | row height ( < 0 has special meanings), wxPropertyGrid calls this method to | |
782 | draw a custom image in a limited area in front of the editor control or | |
783 | value text/graphics, and if control has drop-down list, then the image is | |
784 | drawn there as well (even in the case OnMeasureImage() returned higher height | |
785 | than row height). | |
786 | ||
787 | NOTE: Following applies when OnMeasureImage() returns a "flexible" height ( | |
788 | using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items: | |
789 | If rect.x is < 0, then this is a measure item call, which means that | |
790 | dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight | |
791 | to the height of the image of item at index paintdata.m_choiceItem. This call | |
792 | may be done even as often as once every drop-down popup show. | |
793 | ||
794 | @param dc | |
795 | wxDC to paint on. | |
796 | @param rect | |
797 | Box reserved for custom graphics. Includes surrounding rectangle, if any. | |
798 | If x is < 0, then this is a measure item call (see above). | |
799 | @param paintdata | |
800 | wxPGPaintData structure with much useful data about painted item. | |
801 | @code | |
802 | struct wxPGPaintData | |
803 | { | |
804 | // wxPropertyGrid. | |
805 | const wxPropertyGrid* m_parent; | |
806 | ||
807 | // Normally -1, otherwise index to drop-down list item that has to be drawn. | |
808 | int m_choiceItem; | |
809 | ||
810 | // Set to drawn width in OnCustomPaint (optional). | |
811 | int m_drawnWidth; | |
812 | ||
813 | // In a measure item call, set this to the height of item at m_choiceItem index | |
814 | int m_drawnHeight; | |
815 | }; | |
816 | @endcode | |
817 | ||
818 | @remarks | |
819 | - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth | |
820 | must be set to the full width drawn in pixels. | |
821 | - Due to technical reasons, rect's height will be default even if custom height | |
822 | was reported during measure call. | |
823 | - Brush is guaranteed to be default background colour. It has been already used to | |
824 | clear the background of area being painted. It can be modified. | |
825 | - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for | |
826 | drawing framing rectangle. It can be changed as well. | |
827 | ||
828 | @see ValueToString() | |
829 | */ | |
830 | virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, wxPGPaintData& paintdata ); | |
831 | ||
832 | /** | |
833 | Returns used wxPGCellRenderer instance for given property column (label=0, value=1). | |
834 | ||
835 | Default implementation returns editor's renderer for all columns. | |
836 | */ | |
837 | virtual wxPGCellRenderer* GetCellRenderer( int column ) const; | |
838 | ||
839 | /** | |
840 | Returns which choice is currently selected. Only applies to properties | |
841 | which have choices. | |
842 | ||
843 | Needs to reimplemented in derived class if property value does not | |
844 | map directly to a choice. Integer as index, bool, and string usually do. | |
845 | */ | |
846 | virtual int GetChoiceSelection() const; | |
847 | ||
848 | /** | |
849 | Refresh values of child properties. Automatically called after value is set. | |
850 | */ | |
851 | virtual void RefreshChildren(); | |
852 | ||
853 | /** | |
854 | Special handling for attributes of this property. | |
855 | ||
856 | If returns @false, then the attribute will be automatically stored in | |
857 | m_attributes. | |
858 | ||
859 | Default implementation simply returns @false. | |
860 | */ | |
861 | virtual bool DoSetAttribute( const wxString& name, wxVariant& value ); | |
862 | ||
863 | /** | |
864 | Returns value of an attribute. | |
865 | ||
866 | Override if custom handling of attributes is needed. | |
867 | ||
868 | Default implementation simply return @NULL variant. | |
869 | */ | |
870 | virtual wxVariant DoGetAttribute( const wxString& name ) const; | |
871 | ||
872 | /** | |
873 | Returns instance of a new wxPGEditorDialogAdapter instance, which is | |
874 | used when user presses the (optional) button next to the editor control; | |
875 | ||
876 | Default implementation returns @NULL (ie. no action is generated when | |
877 | button is pressed). | |
878 | */ | |
879 | virtual wxPGEditorDialogAdapter* GetEditorDialog() const; | |
880 | ||
881 | /** | |
882 | Called whenever validation has failed with given pending value. | |
883 | ||
884 | @remarks If you implement this in your custom property class, please | |
885 | remember to call the baser implementation as well, since they | |
886 | may use it to revert property into pre-change state. | |
887 | */ | |
888 | virtual void OnValidationFailure( wxVariant& pendingValue ); | |
889 | ||
890 | /** | |
891 | Append a new choice to property's list of choices. | |
892 | ||
893 | @param label | |
894 | Label for added choice. | |
895 | ||
896 | @param value | |
897 | Value for new choice. Do not specify if you wish this | |
898 | to equal choice index. | |
899 | ||
900 | @return | |
901 | Index to added choice. | |
902 | */ | |
903 | int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE ); | |
904 | ||
905 | /** | |
906 | Adds a private child property. | |
907 | ||
908 | @deprecated Use AddPrivateChild() instead. | |
909 | ||
910 | @see AddPrivateChild() | |
911 | */ | |
912 | wxDEPRECATED( void AddChild( wxPGProperty* prop ) ); | |
913 | ||
914 | /** | |
915 | Adds a private child property. If you use this instead of | |
916 | wxPropertyGridInterface::Insert() or | |
917 | wxPropertyGridInterface::AppendIn(), then property's parental | |
918 | type will automatically be set up to wxPG_PROP_AGGREGATE. In other | |
919 | words, all properties of this property will become private. | |
920 | */ | |
921 | void AddPrivateChild( wxPGProperty* prop ); | |
922 | ||
923 | /** | |
924 | Adapts list variant into proper value using consecutive | |
925 | ChildChanged() calls. | |
926 | */ | |
927 | void AdaptListToValue( wxVariant& list, wxVariant* value ) const; | |
928 | ||
929 | /** | |
930 | Use this member function to add independent (ie. regular) children to | |
931 | a property. | |
932 | ||
933 | @return Appended childProperty. | |
934 | ||
935 | @remarks wxPropertyGrid is not automatically refreshed by this | |
936 | function. | |
937 | ||
938 | @see InsertChild(), AddPrivateChild() | |
939 | */ | |
940 | wxPGProperty* AppendChild( wxPGProperty* childProperty ); | |
941 | ||
942 | /** | |
943 | Determines, recursively, if all children are not unspecified. | |
944 | ||
945 | @param pendingList | |
946 | Assumes members in this wxVariant list as pending | |
947 | replacement values. | |
948 | */ | |
949 | bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const; | |
950 | ||
951 | /** | |
952 | Returns @true if children of this property are component values (for instance, | |
953 | points size, face name, and is_underlined are component values of a font). | |
954 | */ | |
955 | bool AreChildrenComponents() const; | |
956 | ||
957 | /** | |
958 | Deletes children of the property. | |
959 | */ | |
960 | void DeleteChildren(); | |
961 | ||
962 | /** | |
963 | Removes entry from property's wxPGChoices and editor control (if it is active). | |
964 | ||
965 | If selected item is deleted, then the value is set to unspecified. | |
966 | */ | |
967 | void DeleteChoice( int index ); | |
968 | ||
969 | /** Deletes all child properties. */ | |
970 | void Empty(); | |
971 | ||
972 | /** | |
973 | Composes text from values of child properties. | |
974 | */ | |
975 | wxString GenerateComposedValue() const; | |
976 | ||
977 | /** | |
978 | Returns property attribute value, null variant if not found. | |
979 | */ | |
980 | wxVariant GetAttribute( const wxString& name ) const; | |
981 | ||
982 | /** Returns named attribute, as string, if found. Otherwise defVal is returned. | |
983 | */ | |
984 | wxString GetAttribute( const wxString& name, const wxString& defVal ) const; | |
985 | ||
986 | /** Returns named attribute, as long, if found. Otherwise defVal is returned. | |
987 | */ | |
988 | long GetAttributeAsLong( const wxString& name, long defVal ) const; | |
989 | ||
990 | /** Returns named attribute, as double, if found. Otherwise defVal is returned. | |
991 | */ | |
992 | double GetAttributeAsDouble( const wxString& name, double defVal ) const; | |
993 | ||
994 | /** | |
995 | Returns attributes as list wxVariant. | |
996 | */ | |
997 | wxVariant GetAttributesAsList() const; | |
998 | ||
999 | /** | |
1000 | Returns editor used for given column. @NULL for no editor. | |
1001 | */ | |
1002 | const wxPGEditor* GetColumnEditor( int column ) const; | |
1003 | ||
1004 | /** Returns property's base name (ie. parent's name is not added in any case) */ | |
1005 | const wxString& GetBaseName() const; | |
1006 | ||
1007 | /** | |
1008 | Returns wxPGCell of given column. | |
1009 | */ | |
1010 | const wxPGCell& GetCell( unsigned int column ) const; | |
1011 | ||
1012 | /** | |
1013 | Returns number of child properties. | |
1014 | */ | |
1015 | unsigned int GetChildCount() const; | |
1016 | ||
1017 | /** | |
1018 | Returns height of children, recursively, and | |
1019 | by taking expanded/collapsed status into account. | |
1020 | ||
1021 | @param lh | |
1022 | Line height. Pass result of GetGrid()->GetRowHeight() here. | |
1023 | ||
1024 | @param iMax | |
1025 | Only used (internally) when finding property y-positions. | |
1026 | */ | |
1027 | int GetChildrenHeight( int lh, int iMax = -1 ) const; | |
1028 | ||
1029 | /** | |
1030 | Returns read-only reference to property's list of choices. | |
1031 | */ | |
1032 | const wxPGChoices& GetChoices() const; | |
1033 | ||
1034 | /** | |
1035 | Returns client data (void*) of a property. | |
1036 | */ | |
1037 | void* GetClientData() const; | |
1038 | ||
1039 | /** Sets managed client object of a property. | |
1040 | */ | |
1041 | wxClientData *GetClientObject() const; | |
1042 | ||
1043 | /** | |
1044 | Returns property's default value. If property's value type is not | |
1045 | a built-in one, and "DefaultValue" attribute is not defined, then | |
1046 | this function usually returns Null variant. | |
1047 | */ | |
1048 | wxVariant GetDefaultValue() const; | |
1049 | ||
1050 | /** Returns property's displayed text. | |
1051 | */ | |
1052 | wxString GetDisplayedString() const; | |
1053 | ||
1054 | /** | |
1055 | Returns wxPGEditor that will be used and created when | |
1056 | property becomes selected. Returns more accurate value | |
1057 | than DoGetEditorClass(). | |
1058 | */ | |
1059 | const wxPGEditor* GetEditorClass() const; | |
1060 | ||
1061 | /** Returns property grid where property lies. */ | |
1062 | wxPropertyGrid* GetGrid() const; | |
1063 | ||
1064 | /** | |
1065 | Returns owner wxPropertyGrid, but only if one is currently on a page | |
1066 | displaying this property. | |
1067 | */ | |
1068 | wxPropertyGrid* GetGridIfDisplayed() const; | |
1069 | ||
1070 | /** | |
1071 | Returns property's help or description text. | |
1072 | ||
1073 | @see SetHelpString() | |
1074 | */ | |
1075 | const wxString& GetHelpString() const; | |
1076 | ||
1077 | /** | |
1078 | Returns position in parent's array. | |
1079 | */ | |
1080 | unsigned int GetIndexInParent() const; | |
1081 | ||
1082 | /** Returns property's label. */ | |
1083 | const wxString& GetLabel() const; | |
1084 | ||
1085 | /** | |
1086 | Returns last visible child property, recursively. | |
1087 | */ | |
1088 | const wxPGProperty* GetLastVisibleSubItem() const; | |
1089 | ||
1090 | /** | |
1091 | Returns highest level non-category, non-root parent. Useful when you | |
1092 | have nested properties with children. | |
1093 | ||
1094 | @remarks If immediate parent is root or category, this will return the | |
1095 | property itself. | |
1096 | */ | |
1097 | wxPGProperty* GetMainParent() const; | |
1098 | ||
1099 | /** Returns maximum allowed length of property's text value. | |
1100 | */ | |
1101 | int GetMaxLength() const; | |
1102 | ||
1103 | /** Returns property's name with all (non-category, non-root) parents. */ | |
1104 | wxString GetName() const; | |
1105 | ||
1106 | /** Return parent of property */ | |
1107 | wxPGProperty* GetParent() const; | |
1108 | ||
1109 | /** | |
1110 | Returns (direct) child property with given name (or @NULL if not found). | |
1111 | */ | |
1112 | wxPGProperty* GetPropertyByName( const wxString& name ) const; | |
1113 | ||
1114 | /** Gets assignable version of property's validator. */ | |
1115 | wxValidator* GetValidator() const; | |
1116 | ||
1117 | /** | |
1118 | Returns property's value. | |
1119 | */ | |
1120 | wxVariant GetValue() const; | |
1121 | ||
1122 | /** | |
1123 | Returns bitmap that appears next to value text. Only returns non-@NULL | |
1124 | bitmap if one was set with SetValueImage(). | |
1125 | */ | |
1126 | wxBitmap* GetValueImage() const; | |
1127 | ||
1128 | /** Returns text representation of property's value. | |
1129 | ||
1130 | @param argFlags | |
1131 | If 0 (default value), then displayed string is returned. | |
1132 | If wxPG_FULL_VALUE is set, returns complete, storable string value | |
1133 | instead of displayable. If wxPG_EDITABLE_VALUE is set, returns | |
1134 | string value that must be editable in textctrl. If | |
1135 | wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to | |
1136 | display as a part of string property's composite text | |
1137 | representation. | |
1138 | ||
1139 | @remarks In older versions, this function used to be overridden to convert | |
1140 | property's value into a string representation. This function is | |
1141 | now handled by ValueToString(), and overriding this function now | |
1142 | will result in run-time assertion failure. | |
1143 | */ | |
1144 | virtual wxString GetValueAsString( int argFlags = 0 ) const; | |
1145 | ||
1146 | /** Synonymous to GetValueAsString(). | |
1147 | ||
1148 | @deprecated Use GetValueAsString() instead. | |
1149 | ||
1150 | @see GetValueAsString() | |
1151 | */ | |
1152 | wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const ); | |
1153 | ||
1154 | /** | |
1155 | Returns value type used by this property. | |
1156 | */ | |
1157 | wxString GetValueType() const; | |
1158 | ||
1159 | /** | |
1160 | Returns coordinate to the top y of the property. Note that the | |
1161 | position of scrollbars is not taken into account. | |
1162 | */ | |
1163 | int GetY() const; | |
1164 | ||
1165 | /** | |
1166 | Returns @true if property has even one visible child. | |
1167 | */ | |
1168 | bool HasVisibleChildren() const; | |
1169 | ||
1170 | /** | |
1171 | Hides or reveals the property. | |
1172 | ||
1173 | @param hide | |
1174 | @true for hide, @false for reveal. | |
1175 | ||
1176 | @param flags | |
1177 | By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this. | |
1178 | */ | |
1179 | bool Hide( bool hide, int flags = wxPG_RECURSE ); | |
1180 | ||
1181 | /** | |
1182 | Returns index of given child property. wxNOT_FOUND if | |
1183 | given property is not child of this. | |
1184 | */ | |
1185 | int Index( const wxPGProperty* p ) const; | |
1186 | ||
1187 | /** | |
1188 | Use this member function to add independent (ie. regular) children to | |
1189 | a property. | |
1190 | ||
1191 | @return Inserted childProperty. | |
1192 | ||
1193 | @remarks wxPropertyGrid is not automatically refreshed by this | |
1194 | function. | |
1195 | ||
1196 | @see AppendChild(), AddPrivateChild() | |
1197 | */ | |
1198 | wxPGProperty* InsertChild( int index, wxPGProperty* childProperty ); | |
1199 | ||
1200 | /** | |
1201 | Inserts a new choice to property's list of choices. | |
1202 | ||
1203 | @param label | |
1204 | Text for new choice | |
1205 | ||
1206 | @param index | |
1207 | Insertion position. Use wxNOT_FOUND to append. | |
1208 | ||
1209 | @param value | |
1210 | Value for new choice. Do not specify if you wish this | |
1211 | to equal choice index. | |
1212 | */ | |
1213 | int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE ); | |
1214 | ||
1215 | /** | |
1216 | Returns @true if this property is actually a wxPropertyCategory. | |
1217 | */ | |
1218 | bool IsCategory() const; | |
1219 | ||
1220 | /** | |
1221 | Returns @true if property is enabled. | |
1222 | */ | |
1223 | bool IsEnabled() const; | |
1224 | ||
1225 | /** | |
1226 | Returns @true if property has visible children. | |
1227 | */ | |
1228 | bool IsExpanded() const; | |
1229 | ||
1230 | /** | |
1231 | Returns @true if this property is actually a wxRootProperty. | |
1232 | */ | |
1233 | bool IsRoot() const; | |
1234 | ||
1235 | /** | |
1236 | Returns @true if candidateParent is some parent of this property. | |
1237 | */ | |
1238 | bool IsSomeParent( wxPGProperty* candidateParent ) const; | |
1239 | ||
1240 | /** | |
1241 | Returns true if property has editable wxTextCtrl when selected. | |
1242 | ||
1243 | @remarks Altough disabled properties do not displayed editor, they still | |
1244 | return @true here as being disabled is considered a temporary | |
1245 | condition (unlike being read-only or having limited editing enabled). | |
1246 | */ | |
1247 | bool IsTextEditable() const; | |
1248 | ||
1249 | /** | |
1250 | Returns @true if property's value is considered unspecified. This | |
1251 | usually means that value is Null variant. | |
1252 | */ | |
1253 | bool IsValueUnspecified() const; | |
1254 | ||
1255 | /** | |
1256 | Returns true if all parents expanded. | |
1257 | */ | |
1258 | bool IsVisible() const; | |
1259 | ||
1260 | /** | |
1261 | Returns child property at index i. | |
1262 | */ | |
1263 | wxPGProperty* Item( unsigned int i ) const; | |
1264 | ||
1265 | /** | |
1266 | If property's editor is active, then update it's value. | |
1267 | */ | |
1268 | void RefreshEditor(); | |
1269 | ||
1270 | /** | |
1271 | Sets an attribute for this property. | |
1272 | ||
1273 | @param name | |
1274 | Text identifier of attribute. See @ref propgrid_property_attributes. | |
1275 | ||
1276 | @param value | |
1277 | Value of attribute. | |
1278 | ||
1279 | @remarks Setting attribute's value to Null variant will simply remove it | |
1280 | from property's set of attributes. | |
1281 | */ | |
1282 | void SetAttribute( const wxString& name, wxVariant value ); | |
1283 | ||
1284 | /** | |
1285 | Sets property's background colour. | |
1286 | ||
1287 | @param colour | |
1288 | Background colour to use. | |
1289 | ||
1290 | @param recursively | |
1291 | If @true, children are affected recursively, and any categories | |
1292 | are not. | |
1293 | */ | |
1294 | void SetBackgroundColour( const wxColour& colour, | |
1295 | bool recursively = false ); | |
1296 | ||
1297 | /** | |
1298 | Sets editor for a property. | |
1299 | ||
1300 | @param editor | |
1301 | For builtin editors, use wxPGEditor_X, where X is builtin editor's | |
1302 | name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list). | |
1303 | ||
1304 | For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass(). | |
1305 | */ | |
1306 | void SetEditor( const wxPGEditor* editor ); | |
1307 | ||
1308 | /** | |
1309 | Sets editor for a property, by editor name. | |
1310 | */ | |
1311 | void SetEditor( const wxString& editorName ); | |
1312 | ||
1313 | /** | |
1314 | Sets cell information for given column. | |
1315 | */ | |
1316 | void SetCell( int column, const wxPGCell& cell ); | |
1317 | ||
1318 | /** | |
1319 | Sets new set of choices for property. | |
1320 | ||
1321 | @remarks This operation clears the property value. | |
1322 | */ | |
1323 | bool SetChoices( wxPGChoices& choices ); | |
1324 | ||
1325 | /** | |
1326 | Sets client data (void*) of a property. | |
1327 | ||
1328 | @remarks This untyped client data has to be deleted manually. | |
1329 | */ | |
1330 | void SetClientData( void* clientData ); | |
1331 | ||
1332 | /** Returns client object of a property. | |
1333 | */ | |
1334 | void SetClientObject(wxClientData* clientObject); | |
1335 | ||
1336 | /** | |
1337 | Sets selected choice and changes property value. | |
1338 | ||
1339 | Tries to retain value type, although currently if it is not string, | |
1340 | then it is forced to integer. | |
1341 | */ | |
1342 | void SetChoiceSelection( int newValue ); | |
1343 | ||
1344 | /** | |
1345 | Sets property's help string, which is shown, for example, in | |
1346 | wxPropertyGridManager's description text box. | |
1347 | */ | |
1348 | void SetHelpString( const wxString& helpString ); | |
1349 | ||
1350 | /** | |
1351 | Sets property's label. | |
1352 | ||
1353 | @remarks Properties under same parent may have same labels. However, | |
1354 | property names must still remain unique. | |
1355 | */ | |
1356 | void SetLabel( const wxString& label ); | |
1357 | ||
1358 | /** | |
1359 | Set max length of text in text editor. | |
1360 | */ | |
1361 | bool SetMaxLength( int maxLen ); | |
1362 | ||
1363 | /** | |
1364 | Sets property's "is it modified?" flag. Affects children recursively. | |
1365 | */ | |
1366 | void SetModifiedStatus( bool modified ); | |
1367 | ||
1368 | /** | |
1369 | Sets new (base) name for property. | |
1370 | */ | |
1371 | void SetName( const wxString& newName ); | |
1372 | ||
1373 | /** | |
1374 | Changes what sort of parent this property is for its children. | |
1375 | ||
1376 | @param flag | |
1377 | Use one of the following values: wxPG_PROP_MISC_PARENT (for generic | |
1378 | parents), wxPG_PROP_CATEGORY (for categories), or | |
1379 | wxPG_PROP_AGGREGATE (for derived property classes with private | |
1380 | children). | |
1381 | ||
1382 | @remarks You generally do not need to call this function. | |
1383 | */ | |
1384 | void SetParentalType( int flag ); | |
1385 | ||
1386 | /** | |
1387 | Sets property's text colour. | |
1388 | ||
1389 | @param colour | |
1390 | Text colour to use. | |
1391 | ||
1392 | @param recursively | |
1393 | If @true, children are affected recursively, and any categories | |
1394 | are not. | |
1395 | */ | |
1396 | void SetTextColour( const wxColour& colour, | |
1397 | bool recursively = false ); | |
1398 | ||
1399 | /** Sets wxValidator for a property */ | |
1400 | void SetValidator( const wxValidator& validator ); | |
1401 | ||
1402 | /** | |
1403 | Call this to set value of the property. Unlike methods in wxPropertyGrid, | |
1404 | this does not automatically update the display. | |
1405 | ||
1406 | @remarks | |
1407 | Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through | |
1408 | validation process and send property change event. | |
1409 | ||
1410 | If you need to change property value in event, based on user input, use | |
1411 | SetValueInEvent() instead. | |
1412 | ||
1413 | @param value | |
1414 | The value to set. | |
1415 | @param pList | |
1416 | Pointer to list variant that contains child values. Used to indicate | |
1417 | which children should be marked as modified. Usually you just use @NULL. | |
1418 | @param flags | |
1419 | wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor | |
1420 | and redraw properties. | |
1421 | */ | |
1422 | void SetValue( wxVariant value, wxVariant* pList = NULL, | |
1423 | int flags = wxPG_SETVAL_REFRESH_EDITOR ); | |
1424 | ||
1425 | /** | |
1426 | Set wxBitmap in front of the value. This bitmap may be ignored | |
1427 | by custom cell renderers. | |
1428 | */ | |
1429 | void SetValueImage( wxBitmap& bmp ); | |
1430 | ||
1431 | /** | |
1432 | Call this function in OnEvent(), OnButtonClick() etc. to change the | |
1433 | property value based on user input. | |
1434 | ||
1435 | @remarks This method is const since it doesn't actually modify value, but posts | |
1436 | given variant as pending value, stored in wxPropertyGrid. | |
1437 | */ | |
1438 | void SetValueInEvent( wxVariant value ) const; | |
1439 | ||
1440 | /** | |
1441 | Sets property's value to unspecified (ie. Null variant). | |
1442 | */ | |
1443 | void SetValueToUnspecified(); | |
1444 | ||
1445 | /** | |
1446 | Call with @false in OnSetValue() to cancel value changes after all | |
1447 | (ie. cancel @true returned by StringToValue() or IntToValue()). | |
1448 | */ | |
1449 | void SetWasModified( bool set = true ); | |
1450 | ||
1451 | /** | |
1452 | Updates composed values of parent non-category properties, recursively. | |
1453 | Returns topmost property updated. | |
1454 | */ | |
1455 | wxPGProperty* UpdateParentValues(); | |
1456 | ||
1457 | /** | |
1458 | Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES. | |
1459 | */ | |
1460 | bool UsesAutoUnspecified() const; | |
1461 | }; | |
1462 | ||
1463 | ||
1464 | /** | |
1465 | @class wxPGChoices | |
1466 | ||
1467 | Helper class for managing choices of wxPropertyGrid properties. | |
1468 | Each entry can have label, value, bitmap, text colour, and background | |
1469 | colour. | |
1470 | ||
1471 | wxPGChoices uses reference counting, similar to other wxWidgets classes. | |
1472 | This means that assignment operator and copy constructor only copy the | |
1473 | reference and not the actual data. Use Copy() member function to create a | |
1474 | real copy. | |
1475 | ||
1476 | @remarks If you do not specify value for entry, index is used. | |
1477 | ||
1478 | @library{wxpropgrid} | |
1479 | @category{propgrid} | |
1480 | */ | |
1481 | class WXDLLIMPEXP_PROPGRID wxPGChoices | |
1482 | { | |
1483 | public: | |
1484 | typedef long ValArrItem; | |
1485 | ||
1486 | /** | |
1487 | Default constructor. | |
1488 | */ | |
1489 | wxPGChoices(); | |
1490 | ||
1491 | /** | |
1492 | Copy constructor, uses reference counting. To create a real copy, | |
1493 | use Copy() member function instead. | |
1494 | */ | |
1495 | wxPGChoices( const wxPGChoices& a ); | |
1496 | ||
1497 | /** Constructor. */ | |
1498 | wxPGChoices( const wxChar** labels, const long* values = NULL ); | |
1499 | ||
1500 | /** Constructor. */ | |
1501 | wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() ); | |
1502 | ||
1503 | /** Constructor. */ | |
1504 | wxPGChoices( wxPGChoicesData* data ); | |
1505 | ||
1506 | /** Destructor. */ | |
1507 | ~wxPGChoices(); | |
1508 | ||
1509 | /** | |
1510 | Adds to current. If did not have own copies, creates them now. If was empty, | |
1511 | identical to set except that creates copies. | |
1512 | */ | |
1513 | void Add( const wxChar** labels, const ValArrItem* values = NULL ); | |
1514 | ||
1515 | /** Version that works with wxArrayString. */ | |
1516 | void Add( const wxArrayString& arr, const ValArrItem* values = NULL ); | |
1517 | ||
1518 | /** Version that works with wxArrayString and wxArrayInt. */ | |
1519 | void Add( const wxArrayString& arr, const wxArrayInt& arrint ); | |
1520 | ||
1521 | /** Adds single item. */ | |
1522 | wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE ); | |
1523 | ||
1524 | /** Adds a single item, with bitmap. */ | |
1525 | wxPGChoiceEntry& Add( const wxString& label, const wxBitmap& bitmap, | |
1526 | int value = wxPG_INVALID_VALUE ); | |
1527 | ||
1528 | /** Adds a single item with full entry information. */ | |
1529 | wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry ); | |
1530 | ||
1531 | /** Adds single item, sorted. */ | |
1532 | wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE ); | |
1533 | ||
1534 | /** | |
1535 | Assigns choices data, using reference counting. To create a real copy, | |
1536 | use Copy() member function instead. | |
1537 | */ | |
1538 | void Assign( const wxPGChoices& a ); | |
1539 | ||
1540 | /** | |
1541 | Assigns data from another set of choices. | |
1542 | */ | |
1543 | void AssignData( wxPGChoicesData* data ); | |
1544 | ||
1545 | /** | |
1546 | Deletes all items. | |
1547 | */ | |
1548 | void Clear(); | |
1549 | ||
1550 | /** | |
1551 | Returns a real copy of the choices. | |
1552 | */ | |
1553 | wxPGChoices Copy() const; | |
1554 | ||
1555 | /** | |
1556 | Returns labe of item. | |
1557 | */ | |
1558 | const wxString& GetLabel( unsigned int ind ) const; | |
1559 | ||
1560 | /** | |
1561 | Returns number of items. | |
1562 | */ | |
1563 | unsigned int GetCount() const; | |
1564 | ||
1565 | /** | |
1566 | Returns value of item; | |
1567 | */ | |
1568 | int GetValue( unsigned int ind ) const; | |
1569 | ||
1570 | /** | |
1571 | Returns array of values matching the given strings. Unmatching strings | |
1572 | result in wxPG_INVALID_VALUE entry in array. | |
1573 | */ | |
1574 | wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const; | |
1575 | ||
1576 | /** | |
1577 | Returns array of indices matching given strings. Unmatching strings | |
1578 | are added to 'unmatched', if not @NULL. | |
1579 | */ | |
1580 | wxArrayInt GetIndicesForStrings( const wxArrayString& strings, | |
1581 | wxArrayString* unmatched = NULL ) const; | |
1582 | ||
1583 | /** | |
1584 | Returns @true if item at given index has a valid value; | |
1585 | */ | |
1586 | bool HasValue( unsigned int i ) const; | |
1587 | ||
1588 | /** | |
1589 | Returns index of item with given label. | |
1590 | */ | |
1591 | int Index( const wxString& label ) const; | |
1592 | ||
1593 | /** | |
1594 | Returns index of item with given value. | |
1595 | */ | |
1596 | int Index( int val ) const; | |
1597 | ||
1598 | /** | |
1599 | Inserts single item. | |
1600 | */ | |
1601 | wxPGChoiceEntry& Insert( const wxString& label, int index, int value = wxPG_INVALID_VALUE ); | |
1602 | ||
1603 | /** | |
1604 | Inserts a single item with full entry information. | |
1605 | */ | |
1606 | wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index ); | |
1607 | ||
1608 | /** | |
1609 | Returns @false if this is a constant empty set of choices, | |
1610 | which should not be modified. | |
1611 | */ | |
1612 | bool IsOk() const; | |
1613 | ||
1614 | /** | |
1615 | Returns item at given index. | |
1616 | */ | |
1617 | const wxPGChoiceEntry& Item( unsigned int i ) const; | |
1618 | ||
1619 | /** | |
1620 | Returns item at given index. | |
1621 | */ | |
1622 | wxPGChoiceEntry& Item( unsigned int i ); | |
1623 | ||
1624 | /** | |
1625 | Removes count items starting at position nIndex. | |
1626 | */ | |
1627 | void RemoveAt(size_t nIndex, size_t count = 1); | |
1628 | ||
1629 | /** | |
1630 | Sets contents from lists of strings and values. | |
1631 | */ | |
1632 | void Set( const wxChar** labels, const long* values = NULL ); | |
1633 | ||
1634 | /** | |
1635 | Sets contents from lists of strings and values. | |
1636 | */ | |
1637 | void Set( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() ); | |
1638 | ||
1639 | /** | |
1640 | Creates exclusive copy of current choices. | |
1641 | */ | |
1642 | void AllocExclusive(); | |
1643 | ||
1644 | /** | |
1645 | Returns array of choice labels. | |
1646 | */ | |
1647 | wxArrayString GetLabels() const; | |
1648 | ||
1649 | void operator= (const wxPGChoices& a); | |
1650 | ||
1651 | wxPGChoiceEntry& operator[](unsigned int i); | |
1652 | const wxPGChoiceEntry& operator[](unsigned int i) const; | |
1653 | }; | |
1654 | ||
1655 | // ----------------------------------------------------------------------- |