]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: property.h | |
3 | // Purpose: interface of wxPGProperty | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows licence | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | // ----------------------------------------------------------------------- | |
10 | ||
11 | /** | |
12 | @class wxPropertyGridInterface | |
13 | ||
14 | Most of the shared property manipulation interface shared by wxPropertyGrid, | |
15 | wxPropertyGridPage, and wxPropertyGridManager is defined in this class. | |
16 | ||
17 | @remarks | |
18 | - In separate wxPropertyGrid component this class was known as | |
19 | wxPropertyContainerMethods. | |
20 | ||
21 | - wxPropertyGridInterface's property operation member functions all accept | |
22 | a special wxPGPropArg id argument, using which you can refer to properties | |
23 | either by their pointer (for performance) or by their name (for conveniency). | |
24 | ||
25 | @library{wxpropgrid} | |
26 | @category{propgrid} | |
27 | */ | |
28 | class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface | |
29 | { | |
30 | public: | |
31 | ||
32 | /** Destructor */ | |
33 | virtual ~wxPropertyGridInterface() { } | |
34 | ||
35 | /** | |
36 | Appends property to the list. wxPropertyGrid assumes ownership of the | |
37 | object. Becomes child of most recently added category. | |
38 | ||
39 | @remarks | |
40 | - wxPropertyGrid takes the ownership of the property pointer. | |
41 | - If appending a category with name identical to a category already in | |
42 | the wxPropertyGrid, then newly created category is deleted, and most | |
43 | recently added category (under which properties are appended) is set | |
44 | to the one with same name. This allows easier adding of items to same | |
45 | categories in multiple passes. | |
46 | - Does not automatically redraw the control, so you may need to call | |
47 | Refresh() when calling this function after control has been shown for | |
48 | the first time. | |
49 | - This functions deselects selected property, if any. Validation | |
50 | failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. | |
51 | selection is cleared even if editor had invalid value. | |
52 | */ | |
53 | wxPGProperty* Append( wxPGProperty* property ); | |
54 | ||
55 | /** | |
56 | Same as Append(), but appends under given parent property. | |
57 | ||
58 | @param id | |
59 | Name or pointer to parent property. | |
60 | ||
61 | @param newProperty | |
62 | Property to be added. | |
63 | */ | |
64 | wxPGProperty* AppendIn( wxPGPropArg id, wxPGProperty* newProperty ); | |
65 | ||
66 | /** | |
67 | In order to add new items into a property with private children (for | |
68 | instance, wxFlagsProperty), you need to call this method. | |
69 | After populating has been finished, you need to call EndAddChildren(). | |
70 | ||
71 | @see EndAddChildren() | |
72 | */ | |
73 | void BeginAddChildren( wxPGPropArg id ); | |
74 | ||
75 | /** | |
76 | Deletes all properties. | |
77 | ||
78 | @remarks This functions deselects selected property, if any. Validation | |
79 | failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. | |
80 | selection is cleared even if editor had invalid value. | |
81 | */ | |
82 | virtual void Clear() = 0; | |
83 | ||
84 | /** | |
85 | Clears current selection, if any. | |
86 | ||
87 | @param validation | |
88 | If set to @false, deselecting the property will always work, | |
89 | even if its editor had invalid value in it. | |
90 | ||
91 | @return Returns @true if successful or if there was no selection. May | |
92 | fail if validation was enabled and active editor had invalid | |
93 | value. | |
94 | ||
95 | @remarks In wxPropertyGrid 1.4, this member function used to send | |
96 | wxPG_EVT_SELECTED. In wxWidgets 2.9 and later, it no longer | |
97 | does that. | |
98 | ||
99 | @see wxPropertyGrid::SelectProperty() | |
100 | */ | |
101 | bool ClearSelection( bool validation = false); | |
102 | ||
103 | /** | |
104 | Resets modified status of all properties. | |
105 | */ | |
106 | void ClearModifiedStatus(); | |
107 | ||
108 | /** | |
109 | Collapses given category or property with children. | |
110 | ||
111 | @return Returns @true if actually collapsed. | |
112 | ||
113 | @remarks This function may deselect selected property, if any. Validation | |
114 | failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. | |
115 | selection is cleared even if editor had invalid value. | |
116 | */ | |
117 | bool Collapse( wxPGPropArg id ); | |
118 | ||
119 | /** | |
120 | Collapses all items that can be collapsed. | |
121 | ||
122 | @remarks This functions clears selection. Validation failure option | |
123 | wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. selection | |
124 | is cleared even if editor had invalid value. | |
125 | */ | |
126 | bool CollapseAll(); | |
127 | ||
128 | /** | |
129 | Changes value of a property, as if by user. Use this instead of | |
130 | SetPropertyValue() if you need the value to run through validation | |
131 | process, and also send the property change event. | |
132 | ||
133 | @return Returns @true if value was successfully changed. | |
134 | */ | |
135 | bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue ); | |
136 | ||
137 | /** | |
138 | Removes and deletes a property and any children. | |
139 | ||
140 | @param id | |
141 | Pointer or name of a property. | |
142 | ||
143 | @remarks If you delete a property in a wxPropertyGrid event | |
144 | handler, the actual deletion is postponed until the next | |
145 | idle event. | |
146 | ||
147 | This functions deselects selected property, if any. | |
148 | Validation failure option wxPG_VFB_STAY_IN_PROPERTY is not | |
149 | respected, ie. selection is cleared even if editor had | |
150 | invalid value. | |
151 | */ | |
152 | void DeleteProperty( wxPGPropArg id ); | |
153 | ||
154 | /** | |
155 | Disables a property. | |
156 | ||
157 | @see EnableProperty(), wxPGProperty::Enable() | |
158 | */ | |
159 | bool DisableProperty( wxPGPropArg id ); | |
160 | ||
161 | /** | |
162 | Returns @true if all property grid data changes have been committed. Usually | |
163 | only returns @false if value in active editor has been invalidated by a | |
164 | wxValidator. | |
165 | */ | |
166 | bool EditorValidate(); | |
167 | ||
168 | /** | |
169 | Enables or disables property. Disabled property usually appears as | |
170 | having grey text. | |
171 | ||
172 | @param id | |
173 | Name or pointer to a property. | |
174 | @param enable | |
175 | If @false, property is disabled instead. | |
176 | ||
177 | @see wxPGProperty::Enable() | |
178 | */ | |
179 | bool EnableProperty( wxPGPropArg id, bool enable = true ); | |
180 | ||
181 | /** | |
182 | Called after population of property with fixed children has finished. | |
183 | ||
184 | @see BeginAddChildren() | |
185 | */ | |
186 | void EndAddChildren( wxPGPropArg id ); | |
187 | ||
188 | /** | |
189 | Expands given category or property with children. | |
190 | ||
191 | @return Returns @true if actually expanded. | |
192 | ||
193 | @remarks This function may deselect selected property, if any. Validation | |
194 | failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. | |
195 | selection is cleared even if editor had invalid value. | |
196 | */ | |
197 | bool Expand( wxPGPropArg id ); | |
198 | ||
199 | /** | |
200 | Expands all items that can be expanded. | |
201 | ||
202 | @remarks This functions clears selection. Validation failure option | |
203 | wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. selection | |
204 | is cleared even if editor had invalid value. | |
205 | */ | |
206 | bool ExpandAll( bool expand = true ); | |
207 | ||
208 | /** | |
209 | Returns auto-resize proportion of the given column. | |
210 | ||
211 | @see SetColumnProportion() | |
212 | */ | |
213 | int GetColumnProportion( unsigned int column ) const; | |
214 | ||
215 | /** | |
216 | Returns id of first child of given property. | |
217 | ||
218 | @remarks Does not return private children! | |
219 | */ | |
220 | wxPGProperty* GetFirstChild( wxPGPropArg id ); | |
221 | ||
222 | //@{ | |
223 | /** | |
224 | Returns iterator class instance. | |
225 | ||
226 | @param flags | |
227 | See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes | |
228 | iteration over everything except private child properties. | |
229 | @param firstProp | |
230 | Property to start iteration from. If @NULL, then first child of root | |
231 | is used. | |
232 | ||
233 | */ | |
234 | wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, | |
235 | wxPGProperty* firstProp = NULL ); | |
236 | wxPropertyGridConstIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, | |
237 | wxPGProperty* firstProp = NULL ) const; | |
238 | //@} | |
239 | ||
240 | //@{ | |
241 | /** | |
242 | Returns iterator class instance. | |
243 | ||
244 | @param flags | |
245 | See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes | |
246 | iteration over everything except private child properties. | |
247 | @param startPos | |
248 | Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start | |
249 | from the first property from the top, and wxBOTTOM means that the | |
250 | iteration will instead begin from bottommost valid item. | |
251 | ||
252 | */ | |
253 | wxPropertyGridIterator GetIterator( int flags, int startPos ); | |
254 | wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const; | |
255 | //@} | |
256 | ||
257 | /** | |
258 | Returns id of first item that matches given criteria. | |
259 | ||
260 | @param flags | |
261 | See @ref propgrid_iterator_flags. | |
262 | */ | |
263 | wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ); | |
264 | ||
265 | /** | |
266 | Returns pointer to a property with given name (case-sensitive). | |
267 | If there is no property with such name, @NULL pointer is returned. | |
268 | ||
269 | @remarks Properties which have non-category, non-root parent | |
270 | cannot be accessed globally by their name. Instead, use | |
271 | "<property>.<subproperty>" instead of "<subproperty>". | |
272 | */ | |
273 | wxPGProperty* GetProperty( const wxString& name ) const; | |
274 | ||
275 | /** | |
276 | Adds to 'targetArr' pointers to properties that have given flags 'flags' set. | |
277 | However, if @a 'inverse' is set to @true, then only properties without | |
278 | given flags are stored. | |
279 | ||
280 | @param targetArr | |
281 | @todo docme | |
282 | @param flags | |
283 | Property flags to use. | |
284 | @param inverse | |
285 | @todo docme | |
286 | @param iterFlags | |
287 | Iterator flags to use. Default is everything expect private children. | |
288 | See @ref propgrid_iterator_flags. | |
289 | */ | |
290 | void GetPropertiesWithFlag( wxArrayPGProperty* targetArr, | |
291 | wxPGProperty::FlagType flags, | |
292 | bool inverse = false, | |
293 | int iterFlags = (wxPG_ITERATE_PROPERTIES|wxPG_ITERATE_HIDDEN|wxPG_ITERATE_CATEGORIES) ) const; | |
294 | ||
295 | /** | |
296 | Returns value of given attribute. If none found, returns wxNullVariant. | |
297 | */ | |
298 | wxVariant GetPropertyAttribute( wxPGPropArg id, const wxString& attrName ) const; | |
299 | ||
300 | /** | |
301 | Returns background colour of first cell of a property. | |
302 | */ | |
303 | wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const; | |
304 | ||
305 | /** | |
306 | Returns pointer of property's nearest parent category. If no category | |
307 | found, returns @NULL. | |
308 | */ | |
309 | wxPropertyCategory* GetPropertyCategory( wxPGPropArg id ) const; | |
310 | ||
311 | /** Returns client data (void*) of a property. */ | |
312 | void* GetPropertyClientData( wxPGPropArg id ) const; | |
313 | ||
314 | /** | |
315 | Returns first property which label matches given string. @NULL if none | |
316 | found. Note that this operation is very slow when compared to | |
317 | GetPropertyByName(). | |
318 | */ | |
319 | wxPGProperty* GetPropertyByLabel( const wxString& label ) const; | |
320 | ||
321 | /** | |
322 | Returns pointer to a property with given name (case-sensitive). | |
323 | If there is no property with such name, @NULL pointer is returned. | |
324 | ||
325 | @remarks Properties which have non-category, non-root parent | |
326 | cannot be accessed globally by their name. Instead, use | |
327 | "<property>.<subproperty>" instead of "<subproperty>". | |
328 | */ | |
329 | wxPGProperty* GetPropertyByName( const wxString& name ) const; | |
330 | ||
331 | /** | |
332 | Returns child property 'subname' of property 'name'. Same as | |
333 | calling GetPropertyByName("name.subname"), albeit slightly faster. | |
334 | */ | |
335 | wxPGProperty* GetPropertyByName( const wxString& name, | |
336 | const wxString& subname ) const; | |
337 | ||
338 | /** | |
339 | Returns property's editor. | |
340 | */ | |
341 | const wxPGEditor* GetPropertyEditor( wxPGPropArg id ) const; | |
342 | ||
343 | /** | |
344 | Returns help string associated with a property. | |
345 | */ | |
346 | wxString GetPropertyHelpString( wxPGPropArg id ) const; | |
347 | ||
348 | /** | |
349 | Returns property's custom value image (@NULL of none). | |
350 | */ | |
351 | wxBitmap* GetPropertyImage( wxPGPropArg id ) const; | |
352 | ||
353 | /** Returns label of a property. */ | |
354 | const wxString& GetPropertyLabel( wxPGPropArg id ); | |
355 | ||
356 | /** Returns property's name, by which it is globally accessible. */ | |
357 | wxString GetPropertyName( wxPGProperty* property ); | |
358 | ||
359 | /** | |
360 | Returns text colour of first cell of a property. | |
361 | */ | |
362 | wxColour GetPropertyTextColour( wxPGPropArg id ) const; | |
363 | ||
364 | /** | |
365 | Returns validator of a property as a reference, which you | |
366 | can pass to any number of SetPropertyValidator. | |
367 | */ | |
368 | wxValidator* GetPropertyValidator( wxPGPropArg id ); | |
369 | ||
370 | /** | |
371 | Returns property's value as wxVariant. | |
372 | ||
373 | If property value is unspecified, Null variant is returned. | |
374 | */ | |
375 | wxVariant GetPropertyValue( wxPGPropArg id ); | |
376 | ||
377 | /** Return's property's value as wxArrayInt. */ | |
378 | wxArrayInt GetPropertyValueAsArrayInt( wxPGPropArg id ) const; | |
379 | ||
380 | /** Returns property's value as wxArrayString. */ | |
381 | wxArrayString GetPropertyValueAsArrayString( wxPGPropArg id ) const; | |
382 | ||
383 | /** Returns property's value as bool */ | |
384 | bool GetPropertyValueAsBool( wxPGPropArg id ) const; | |
385 | ||
386 | /** Return's property's value as wxDateTime. */ | |
387 | wxDateTime GetPropertyValueAsDateTime( wxPGPropArg id ) const; | |
388 | ||
389 | /** Returns property's value as double-precision floating point number. */ | |
390 | double GetPropertyValueAsDouble( wxPGPropArg id ) const; | |
391 | ||
392 | /** Returns property's value as integer */ | |
393 | int GetPropertyValueAsInt( wxPGPropArg id ) const; | |
394 | ||
395 | /** Returns property's value as integer */ | |
396 | long GetPropertyValueAsLong( wxPGPropArg id ) const; | |
397 | ||
398 | /** Returns property's value as native signed 64-bit integer. */ | |
399 | wxLongLong_t GetPropertyValueAsLongLong( wxPGPropArg id ) const; | |
400 | ||
401 | /** | |
402 | Returns property's value as wxString. If property does not | |
403 | use string value type, then its value is converted using | |
404 | wxPGProperty::GetValueAsString(). | |
405 | */ | |
406 | wxString GetPropertyValueAsString( wxPGPropArg id ) const; | |
407 | ||
408 | /** Returns property's value as unsigned integer */ | |
409 | unsigned long GetPropertyValueAsULong( wxPGPropArg id ) const; | |
410 | ||
411 | /** Returns property's value as native unsigned 64-bit integer. */ | |
412 | wxULongLong_t GetPropertyValueAsULongLong( wxPGPropArg id ) const; | |
413 | ||
414 | /** | |
415 | Returns a wxVariant list containing wxVariant versions of all | |
416 | property values. Order is not guaranteed. | |
417 | ||
418 | @param listname | |
419 | @todo docme | |
420 | @param baseparent | |
421 | @todo docme | |
422 | @param flags | |
423 | Use wxPG_KEEP_STRUCTURE to retain category structure; each sub | |
424 | category will be its own wxVariantList of wxVariant. | |
425 | ||
426 | Use wxPG_INC_ATTRIBUTES to include property attributes as well. | |
427 | Each attribute will be stored as list variant named | |
428 | "@@<propname>@@attr." | |
429 | */ | |
430 | wxVariant GetPropertyValues( const wxString& listname = wxEmptyString, | |
431 | wxPGProperty* baseparent = NULL, long flags = 0 ) const; | |
432 | ||
433 | /** | |
434 | Returns list of currently selected properties. | |
435 | ||
436 | @remarks wxArrayPGProperty should be compatible with std::vector API. | |
437 | */ | |
438 | const wxArrayPGProperty& GetSelectedProperties() const; | |
439 | ||
440 | /** | |
441 | Returns currently selected property. NULL if none. | |
442 | ||
443 | @remarks When wxPG_EX_MULTIPLE_SELECTION extra style is used, this | |
444 | member function returns the focused property, that is the | |
445 | one which can have active editor. | |
446 | */ | |
447 | wxPGProperty* GetSelection() const; | |
448 | ||
449 | /** | |
450 | Similar to GetIterator(), but instead returns wxPGVIterator instance, | |
451 | which can be useful for forward-iterating through arbitrary property | |
452 | containers. | |
453 | ||
454 | @param flags | |
455 | See @ref propgrid_iterator_flags. | |
456 | */ | |
457 | virtual wxPGVIterator GetVIterator( int flags ) const; | |
458 | ||
459 | /** | |
460 | Hides or reveals a property. | |
461 | ||
462 | @param id | |
463 | @todo docme | |
464 | @param hide | |
465 | If @true, hides property, otherwise reveals it. | |
466 | @param flags | |
467 | By default changes are applied recursively. Set this parameter | |
468 | wxPG_DONT_RECURSE to prevent this. | |
469 | */ | |
470 | bool HideProperty( wxPGPropArg id, bool hide = true, int flags = wxPG_RECURSE ); | |
471 | ||
472 | /** | |
473 | Initializes *all* property types. Causes references to most object | |
474 | files in the library, so calling this may cause significant increase | |
475 | in executable size when linking with static library. | |
476 | */ | |
477 | static void InitAllTypeHandlers(); | |
478 | ||
479 | /** | |
480 | Inserts property to the property container. | |
481 | ||
482 | @param priorThis | |
483 | New property is inserted just prior to this. Available only | |
484 | in the first variant. There are two versions of this function | |
485 | to allow this parameter to be either an id or name to | |
486 | a property. | |
487 | @param newProperty | |
488 | Pointer to the inserted property. wxPropertyGrid will take | |
489 | ownership of this object. | |
490 | ||
491 | @return Returns newProperty. | |
492 | ||
493 | @remarks | |
494 | ||
495 | - wxPropertyGrid takes the ownership of the property pointer. | |
496 | ||
497 | - While Append may be faster way to add items, make note that when | |
498 | both types of data storage (categoric and | |
499 | non-categoric) are active, Insert becomes even more slow. This is | |
500 | especially true if current mode is non-categoric. | |
501 | ||
502 | - This functions deselects selected property, if any. Validation | |
503 | failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. | |
504 | selection is cleared even if editor had invalid value. | |
505 | ||
506 | Example of use: | |
507 | ||
508 | @code | |
509 | ||
510 | // append category | |
511 | wxPGProperty* my_cat_id = propertygrid->Append( new wxPropertyCategory("My Category") ); | |
512 | ||
513 | ... | |
514 | ||
515 | // insert into category - using second variant | |
516 | wxPGProperty* my_item_id_1 = propertygrid->Insert( my_cat_id, 0, new wxStringProperty("My String 1") ); | |
517 | ||
518 | // insert before to first item - using first variant | |
519 | wxPGProperty* my_item_id_2 = propertygrid->Insert( my_item_id, new wxStringProperty("My String 2") ); | |
520 | ||
521 | @endcode | |
522 | */ | |
523 | wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newProperty ); | |
524 | ||
525 | /** | |
526 | Inserts property to the property container. | |
527 | See the other overload for more details. | |
528 | ||
529 | @param parent | |
530 | New property is inserted under this category. Available only | |
531 | in the second variant. There are two versions of this function | |
532 | to allow this parameter to be either an id or name to | |
533 | a property. | |
534 | @param index | |
535 | Index under category. Available only in the second variant. | |
536 | If index is < 0, property is appended in category. | |
537 | @param newProperty | |
538 | Pointer to the inserted property. wxPropertyGrid will take | |
539 | ownership of this object. | |
540 | ||
541 | @return Returns newProperty. | |
542 | */ | |
543 | wxPGProperty* Insert( wxPGPropArg parent, int index, wxPGProperty* newProperty ); | |
544 | ||
545 | /** Returns @true if property is a category. */ | |
546 | bool IsPropertyCategory( wxPGPropArg id ) const; | |
547 | ||
548 | /** Returns @true if property is enabled. */ | |
549 | bool IsPropertyEnabled( wxPGPropArg id ) const; | |
550 | ||
551 | /** | |
552 | Returns @true if given property is expanded. Naturally, always returns | |
553 | @false for properties that cannot be expanded. | |
554 | */ | |
555 | bool IsPropertyExpanded( wxPGPropArg id ) const; | |
556 | ||
557 | /** | |
558 | Returns @true if property has been modified after value set or modify | |
559 | flag clear by software. | |
560 | */ | |
561 | bool IsPropertyModified( wxPGPropArg id ) const; | |
562 | ||
563 | /** | |
564 | Returns true if property is selected. | |
565 | */ | |
566 | virtual bool IsPropertySelected( wxPGPropArg id ) const; | |
567 | ||
568 | /** | |
569 | Returns @true if property is shown (ie. HideProperty() with @true not | |
570 | called for it). | |
571 | */ | |
572 | bool IsPropertyShown( wxPGPropArg id ) const; | |
573 | ||
574 | /** | |
575 | Returns @true if property value is set to unspecified. | |
576 | */ | |
577 | bool IsPropertyValueUnspecified( wxPGPropArg id ) const; | |
578 | ||
579 | /** | |
580 | Disables (limit = @true) or enables (limit = @false) wxTextCtrl editor | |
581 | of a property, if it is not the sole mean to edit the value. | |
582 | */ | |
583 | void LimitPropertyEditing( wxPGPropArg id, bool limit = true ); | |
584 | ||
585 | /** | |
586 | Initializes additional property editors (SpinCtrl etc.). Causes | |
587 | references to most object files in the library, so calling this may | |
588 | cause significant increase in executable size when linking with static | |
589 | library. | |
590 | */ | |
591 | static void RegisterAdditionalEditors(); | |
592 | ||
593 | /** | |
594 | Removes a property. Does not delete the property object, but | |
595 | instead returns it. | |
596 | ||
597 | @param id | |
598 | Pointer or name of a property. | |
599 | ||
600 | @remarks Removed property cannot have any children. | |
601 | ||
602 | Also, if you remove property in a wxPropertyGrid event | |
603 | handler, the actual removal is postponed until the next | |
604 | idle event. | |
605 | */ | |
606 | wxPGProperty* RemoveProperty( wxPGPropArg id ); | |
607 | ||
608 | /** | |
609 | Replaces property with id with newly created one. For example, | |
610 | this code replaces existing property named "Flags" with one that | |
611 | will have different set of items: | |
612 | ||
613 | @code | |
614 | pg->ReplaceProperty("Flags", | |
615 | wxFlagsProperty("Flags", wxPG_LABEL, newItems)) | |
616 | @endcode | |
617 | ||
618 | @see Insert() | |
619 | */ | |
620 | wxPGProperty* ReplaceProperty( wxPGPropArg id, wxPGProperty* property ); | |
621 | ||
622 | /** | |
623 | @anchor propgridinterface_editablestate_flags | |
624 | ||
625 | Flags for wxPropertyGridInterface::SaveEditableState() and | |
626 | wxPropertyGridInterface::RestoreEditableState(). | |
627 | */ | |
628 | enum EditableStateFlags | |
629 | { | |
630 | /** Include selected property. */ | |
631 | SelectionState = 0x01, | |
632 | /** Include expanded/collapsed property information. */ | |
633 | ExpandedState = 0x02, | |
634 | /** Include scrolled position. */ | |
635 | ScrollPosState = 0x04, | |
636 | /** Include selected page information. Only applies to | |
637 | wxPropertyGridManager. */ | |
638 | PageState = 0x08, | |
639 | /** Include splitter position. Stored for each page. */ | |
640 | SplitterPosState = 0x10, | |
641 | /** Include description box size. | |
642 | Only applies to wxPropertyGridManager. */ | |
643 | DescBoxState = 0x20, | |
644 | ||
645 | /** | |
646 | Include all supported user editable state information. | |
647 | This is usually the default value. */ | |
648 | AllStates = SelectionState | | |
649 | ExpandedState | | |
650 | ScrollPosState | | |
651 | PageState | | |
652 | SplitterPosState | | |
653 | DescBoxState | |
654 | }; | |
655 | ||
656 | /** | |
657 | Restores user-editable state. See also wxPropertyGridInterface::SaveEditableState(). | |
658 | ||
659 | @param src | |
660 | String generated by SaveEditableState. | |
661 | ||
662 | @param restoreStates | |
663 | Which parts to restore from source string. See @ref propgridinterface_editablestate_flags | |
664 | "list of editable state flags". | |
665 | ||
666 | @return Returns @false if there was problem reading the string. | |
667 | ||
668 | @remarks If some parts of state (such as scrolled or splitter position) | |
669 | fail to restore correctly, please make sure that you call this | |
670 | function after wxPropertyGrid size has been set (this may | |
671 | sometimes be tricky when sizers are used). | |
672 | */ | |
673 | bool RestoreEditableState( const wxString& src, | |
674 | int restoreStates = AllStates ); | |
675 | ||
676 | /** | |
677 | Used to acquire user-editable state (selected property, expanded | |
678 | properties, scrolled position, splitter positions). | |
679 | ||
680 | @param includedStates | |
681 | Which parts of state to include. See @ref propgridinterface_editablestate_flags | |
682 | "list of editable state flags". | |
683 | */ | |
684 | wxString SaveEditableState( int includedStates = AllStates ) const; | |
685 | ||
686 | /** | |
687 | Sets strings listed in the choice dropdown of a wxBoolProperty. | |
688 | ||
689 | Defaults are "True" and "False", so changing them to, say, "Yes" and | |
690 | "No" may be useful in some less technical applications. | |
691 | */ | |
692 | static void SetBoolChoices( const wxString& trueChoice, | |
693 | const wxString& falseChoice ); | |
694 | ||
695 | /** | |
696 | Set proportion of a auto-stretchable column. wxPG_SPLITTER_AUTO_CENTER | |
697 | window style needs to be used to indicate that columns are auto- | |
698 | resizable. | |
699 | ||
700 | @returns Returns @false on failure. | |
701 | ||
702 | @remarks You should call this for individual pages of | |
703 | wxPropertyGridManager (if used). | |
704 | ||
705 | @see GetColumnProportion() | |
706 | */ | |
707 | bool SetColumnProportion( unsigned int column, int proportion ); | |
708 | ||
709 | /** | |
710 | Sets an attribute for this property. | |
711 | ||
712 | @param id | |
713 | @todo docme | |
714 | @param attrName | |
715 | Text identifier of attribute. See @ref propgrid_property_attributes. | |
716 | @param value | |
717 | Value of attribute. | |
718 | @param argFlags | |
719 | Optional. | |
720 | Use wxPG_RECURSE to set the attribute to child properties recursively. | |
721 | ||
722 | @remarks Setting attribute's value to Null variant will simply remove it | |
723 | from property's set of attributes. | |
724 | */ | |
725 | void SetPropertyAttribute( wxPGPropArg id, const wxString& attrName, | |
726 | wxVariant value, long argFlags = 0 ); | |
727 | ||
728 | /** | |
729 | Sets property attribute for all applicapple properties. | |
730 | Be sure to use this method only after all properties have been | |
731 | added to the grid. | |
732 | */ | |
733 | void SetPropertyAttributeAll( const wxString& attrName, wxVariant value ); | |
734 | ||
735 | /** | |
736 | Sets background colour of a property. | |
737 | ||
738 | @param id | |
739 | Property name or pointer. | |
740 | ||
741 | @param colour | |
742 | New background colour. | |
743 | ||
744 | @param flags | |
745 | Default is wxPG_RECURSE which causes colour to be set recursively. | |
746 | Omit this flag to only set colour for the property in question | |
747 | and not any of its children. | |
748 | */ | |
749 | void SetPropertyBackgroundColour( wxPGPropArg id, | |
750 | const wxColour& colour, | |
751 | int flags = wxPG_RECURSE ); | |
752 | ||
753 | /** | |
754 | Sets text, bitmap, and colours for given column's cell. | |
755 | ||
756 | @remarks | |
757 | - You can set label cell by using column 0. | |
758 | - You can use wxPG_LABEL as text to use default text for column. | |
759 | */ | |
760 | void SetPropertyCell( wxPGPropArg id, | |
761 | int column, | |
762 | const wxString& text = wxEmptyString, | |
763 | const wxBitmap& bitmap = wxNullBitmap, | |
764 | const wxColour& fgCol = wxNullColour, | |
765 | const wxColour& bgCol = wxNullColour ); | |
766 | ||
767 | /** | |
768 | Sets client data (void*) of a property. | |
769 | ||
770 | @remarks | |
771 | This untyped client data has to be deleted manually. | |
772 | */ | |
773 | void SetPropertyClientData( wxPGPropArg id, void* clientData ); | |
774 | ||
775 | /** | |
776 | Resets text and background colours of given property. | |
777 | */ | |
778 | void SetPropertyColoursToDefault( wxPGPropArg id ); | |
779 | ||
780 | /** | |
781 | Sets editor for a property. | |
782 | ||
783 | @param id | |
784 | @todo docme | |
785 | @param editor | |
786 | For builtin editors, use wxPGEditor_X, where X is builtin editor's | |
787 | name (TextCtrl, Choice, etc. see wxPGEditor documentation for full | |
788 | list). | |
789 | ||
790 | For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass(). | |
791 | */ | |
792 | void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor ); | |
793 | ||
794 | /** | |
795 | Sets editor control of a property. As editor argument, use | |
796 | editor name string, such as "TextCtrl" or "Choice". | |
797 | */ | |
798 | void SetPropertyEditor( wxPGPropArg id, const wxString& editorName ); | |
799 | ||
800 | /** | |
801 | Sets label of a property. | |
802 | ||
803 | @remarks | |
804 | - Properties under same parent may have same labels. However, | |
805 | property names must still remain unique. | |
806 | */ | |
807 | void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel ); | |
808 | ||
809 | /** | |
810 | Sets name of a property. | |
811 | ||
812 | @param id | |
813 | Name or pointer of property which name to change. | |
814 | ||
815 | @param newName | |
816 | New name for property. | |
817 | */ | |
818 | void SetPropertyName( wxPGPropArg id, const wxString& newName ); | |
819 | ||
820 | /** | |
821 | Sets property (and, recursively, its children) to have read-only value. | |
822 | In other words, user cannot change the value in the editor, but they can | |
823 | still copy it. | |
824 | ||
825 | @param id | |
826 | Property name or pointer. | |
827 | ||
828 | @param set | |
829 | Use @true to enable read-only, @false to disable it. | |
830 | ||
831 | @param flags | |
832 | By default changes are applied recursively. Set this parameter | |
833 | wxPG_DONT_RECURSE to prevent this. | |
834 | ||
835 | @remarks This is mainly for use with textctrl editor. Only some other | |
836 | editors fully support it. | |
837 | */ | |
838 | void SetPropertyReadOnly( wxPGPropArg id, bool set = true, | |
839 | int flags = wxPG_RECURSE ); | |
840 | ||
841 | /** | |
842 | Sets property's value to unspecified. If it has children (it may be | |
843 | category), then the same thing is done to them. | |
844 | */ | |
845 | void SetPropertyValueUnspecified( wxPGPropArg id ); | |
846 | ||
847 | /** | |
848 | Sets property values from a list of wxVariants. | |
849 | */ | |
850 | void SetPropertyValues( const wxVariantList& list, | |
851 | wxPGPropArg defaultCategory = wxNullProperty ); | |
852 | ||
853 | /** | |
854 | Sets property values from a list of wxVariants. | |
855 | */ | |
856 | void SetPropertyValues( const wxVariant& list, | |
857 | wxPGPropArg defaultCategory = wxNullProperty ); | |
858 | ||
859 | /** | |
860 | Associates the help string with property. | |
861 | ||
862 | @remarks By default, text is shown either in the manager's "description" | |
863 | text box or in the status bar. If extra window style | |
864 | wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as | |
865 | a tooltip. | |
866 | */ | |
867 | void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString ); | |
868 | ||
869 | /** | |
870 | Set wxBitmap in front of the value. | |
871 | ||
872 | @remarks Bitmap will be scaled to a size returned by | |
873 | wxPropertyGrid::GetImageSize(); | |
874 | */ | |
875 | void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp ); | |
876 | ||
877 | /** | |
878 | Sets max length of property's text. | |
879 | */ | |
880 | bool SetPropertyMaxLength( wxPGPropArg id, int maxLen ); | |
881 | ||
882 | ||
883 | /** | |
884 | Sets text colour of a property. | |
885 | ||
886 | @param id | |
887 | Property name or pointer. | |
888 | ||
889 | @param colour | |
890 | New background colour. | |
891 | ||
892 | @param flags | |
893 | Default is wxPG_RECURSE which causes colour to be set recursively. | |
894 | Omit this flag to only set colour for the property in question | |
895 | and not any of its children. | |
896 | */ | |
897 | void SetPropertyTextColour( wxPGPropArg id, | |
898 | const wxColour& colour, | |
899 | int flags = wxPG_RECURSE ); | |
900 | ||
901 | /** | |
902 | Sets validator of a property. | |
903 | */ | |
904 | void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator ); | |
905 | ||
906 | /** Sets value (integer) of a property. */ | |
907 | void SetPropertyValue( wxPGPropArg id, long value ); | |
908 | ||
909 | /** Sets value (integer) of a property. */ | |
910 | void SetPropertyValue( wxPGPropArg id, int value ); | |
911 | ||
912 | /** Sets value (floating point) of a property. */ | |
913 | void SetPropertyValue( wxPGPropArg id, double value ); | |
914 | ||
915 | /** Sets value (bool) of a property. */ | |
916 | void SetPropertyValue( wxPGPropArg id, bool value ); | |
917 | ||
918 | /** Sets value (string) of a property. */ | |
919 | void SetPropertyValue( wxPGPropArg id, const wxString& value ); | |
920 | ||
921 | /** Sets value (wxArrayString) of a property. */ | |
922 | void SetPropertyValue( wxPGPropArg id, const wxArrayString& value ); | |
923 | ||
924 | /** Sets value (wxDateTime) of a property. */ | |
925 | void SetPropertyValue( wxPGPropArg id, const wxDateTime& value ); | |
926 | ||
927 | /** Sets value (wxObject*) of a property. */ | |
928 | void SetPropertyValue( wxPGPropArg id, wxObject* value ); | |
929 | ||
930 | /** Sets value (wxObject&) of a property. */ | |
931 | void SetPropertyValue( wxPGPropArg id, wxObject& value ); | |
932 | ||
933 | /** Sets value (native 64-bit int) of a property. */ | |
934 | void SetPropertyValue( wxPGPropArg id, wxLongLong_t value ); | |
935 | ||
936 | /** Sets value (native 64-bit unsigned int) of a property. */ | |
937 | void SetPropertyValue( wxPGPropArg id, wxULongLong_t value ); | |
938 | ||
939 | /** Sets value (wxArrayInt&) of a property. */ | |
940 | void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value ); | |
941 | ||
942 | /** | |
943 | Sets value (wxString) of a property. | |
944 | ||
945 | @remarks This method uses wxPGProperty::SetValueFromString(), which all | |
946 | properties should implement. This means that there should not be | |
947 | a type error, and instead the string is converted to property's | |
948 | actual value type. | |
949 | */ | |
950 | void SetPropertyValueString( wxPGPropArg id, const wxString& value ); | |
951 | ||
952 | /** | |
953 | Sets value (wxVariant&) of a property. | |
954 | ||
955 | @remarks Use wxPropertyGrid::ChangePropertyValue() instead if you need to | |
956 | run through validation process and send property change event. | |
957 | */ | |
958 | void SetPropertyValue( wxPGPropArg id, wxVariant value ); | |
959 | ||
960 | /** | |
961 | Adjusts how wxPropertyGrid behaves when invalid value is entered | |
962 | in a property. | |
963 | ||
964 | @param vfbFlags | |
965 | See @ref propgrid_vfbflags for possible values. | |
966 | */ | |
967 | void SetValidationFailureBehavior( int vfbFlags ); | |
968 | ||
969 | /** | |
970 | Sorts all properties recursively. | |
971 | ||
972 | @param flags | |
973 | This can contain any of the following options: | |
974 | wxPG_SORT_TOP_LEVEL_ONLY: Only sort categories and their | |
975 | immediate children. Sorting done by wxPG_AUTO_SORT option | |
976 | uses this. | |
977 | ||
978 | @see SortChildren, wxPropertyGrid::SetSortFunction | |
979 | */ | |
980 | void Sort( int flags = 0 ); | |
981 | ||
982 | /** | |
983 | Sorts children of a property. | |
984 | ||
985 | @param id | |
986 | Name or pointer to a property. | |
987 | ||
988 | @param flags | |
989 | This can contain any of the following options: | |
990 | wxPG_RECURSE: Sorts recursively. | |
991 | ||
992 | @see Sort, wxPropertyGrid::SetSortFunction | |
993 | */ | |
994 | void SortChildren( wxPGPropArg id, int flags = 0 ); | |
995 | ||
996 | /** | |
997 | Returns editor pointer of editor with given name; | |
998 | */ | |
999 | static wxPGEditor* GetEditorByName( const wxString& editorName ); | |
1000 | }; | |
1001 |