implemented wxMemoryFSHandler::FindFirst/Next()
[wxWidgets.git] / interface / wx / propgrid / propgrid.h
CommitLineData
1c4293cb
VZ
1/////////////////////////////////////////////////////////////////////////////
2// Name: propgrid.h
3// Purpose: interface of wxPropertyGrid
4// Author: wxWidgets team
5// RCS-ID: $Id:
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9
6b03a638
JS
10/**
11 @section propgrid_window_styles wxPropertyGrid Window Styles
1c4293cb
VZ
12
13 SetWindowStyleFlag method can be used to modify some of these at run-time.
14 @{
15*/
16enum wxPG_WINDOW_STYLES
17{
18
6b03a638
JS
19/**
20 This will cause Sort() automatically after an item is added.
1c4293cb
VZ
21 When inserting a lot of items in this mode, it may make sense to
22 use Freeze() before operations and Thaw() afterwards to increase
23 performance.
24*/
25wxPG_AUTO_SORT = 0x00000010,
26
6b03a638
JS
27/**
28 Categories are not initially shown (even if added).
1c4293cb
VZ
29 IMPORTANT NOTE: If you do not plan to use categories, then this
30 style will waste resources.
31 This flag can also be changed using wxPropertyGrid::EnableCategories method.
32*/
33wxPG_HIDE_CATEGORIES = 0x00000020,
34
6b03a638
JS
35/*
36 This style combines non-categoric mode and automatic sorting.
1c4293cb
VZ
37*/
38wxPG_ALPHABETIC_MODE = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
39
6b03a638
JS
40/**
41 Modified values are shown in bold font. Changing this requires Refresh()
1c4293cb
VZ
42 to show changes.
43*/
44wxPG_BOLD_MODIFIED = 0x00000040,
45
6b03a638
JS
46/**
47 When wxPropertyGrid is resized, splitter moves to the center. This
1c4293cb
VZ
48 behavior stops once the user manually moves the splitter.
49*/
50wxPG_SPLITTER_AUTO_CENTER = 0x00000080,
51
6b03a638
JS
52/**
53 Display tool tips for cell text that cannot be shown completely. If
1c4293cb
VZ
54 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
55*/
56wxPG_TOOLTIPS = 0x00000100,
57
6b03a638
JS
58/**
59 Disables margin and hides all expand/collapse buttons that would appear
1c4293cb
VZ
60 outside the margin (for sub-properties). Toggling this style automatically
61 expands all collapsed items.
62*/
63wxPG_HIDE_MARGIN = 0x00000200,
64
6b03a638
JS
65/**
66 This style prevents user from moving the splitter.
1c4293cb
VZ
67*/
68wxPG_STATIC_SPLITTER = 0x00000400,
69
6b03a638
JS
70/**
71 Combination of other styles that make it impossible for user to modify
1c4293cb
VZ
72 the layout.
73*/
74wxPG_STATIC_LAYOUT = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER),
75
6b03a638
JS
76/**
77 Disables wxTextCtrl based editors for properties which
78 can be edited in another way. Equals calling
79 wxPropertyGrid::LimitPropertyEditing() for all added properties.
1c4293cb
VZ
80*/
81wxPG_LIMITED_EDITING = 0x00000800,
82
6b03a638
JS
83/**
84 wxPropertyGridManager only: Show tool bar for mode and page selection.
85*/
1c4293cb
VZ
86wxPG_TOOLBAR = 0x00001000,
87
6b03a638
JS
88/**
89 wxPropertyGridManager only: Show adjustable text box showing description
1c4293cb
VZ
90 or help text, if available, for currently selected property.
91*/
92wxPG_DESCRIPTION = 0x00002000
93
94};
95
96enum wxPG_EX_WINDOW_STYLES
97{
98
99/**
100 NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
101 member function.
102
6b03a638
JS
103 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
104 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
105 activated, and switching the mode first time becomes somewhat slower.
106 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
1c4293cb 107
6b03a638
JS
108 NOTE: If you do plan not switching to non-categoric mode, or if
109 you don't plan to use categories at all, then using this style will result
110 in waste of resources.
1c4293cb
VZ
111*/
112wxPG_EX_INIT_NOCAT = 0x00001000,
113
6b03a638
JS
114/**
115 Extended window style that sets wxPropertyGridManager tool bar to not
1c4293cb
VZ
116 use flat style.
117*/
118wxPG_EX_NO_FLAT_TOOLBAR = 0x00002000,
119
6b03a638
JS
120/**
121 Shows alphabetic/categoric mode buttons from tool bar.
1c4293cb
VZ
122*/
123wxPG_EX_MODE_BUTTONS = 0x00008000,
124
6b03a638
JS
125/**
126 Show property help strings as tool tips instead as text on the status bar.
1c4293cb
VZ
127 You can set the help strings using SetPropertyHelpString member function.
128*/
129wxPG_EX_HELP_AS_TOOLTIPS = 0x00010000,
130
6b03a638
JS
131/**
132 Allows relying on native double-buffering.
1c4293cb
VZ
133*/
134wxPG_EX_NATIVE_DOUBLE_BUFFERING = 0x00080000,
135
6b03a638
JS
136/**
137 Set this style to let user have ability to set values of properties to
1c4293cb
VZ
138 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
139 all properties.
140*/
141wxPG_EX_AUTO_UNSPECIFIED_VALUES = 0x00200000,
142
6b03a638
JS
143/**
144 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
145 wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
146 they are not readable).
1c4293cb
VZ
147
148 Note that this option is global, and applies to all wxPG property containers.
149*/
150wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES = 0x00400000,
151
6b03a638
JS
152/**
153 Hides page selection buttons from tool bar.
1c4293cb
VZ
154*/
155wxPG_EX_HIDE_PAGE_BUTTONS = 0x01000000
156
157};
158
159/** Combines various styles.
160*/
161#define wxPG_DEFAULT_STYLE (0)
162
163/** Combines various styles.
164*/
165#define wxPGMAN_DEFAULT_STYLE (0)
166
167/** @}
168*/
169
170// -----------------------------------------------------------------------
171
6b03a638
JS
172/**
173 @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
1c4293cb
VZ
174 @{
175*/
176
177enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
178{
179
6b03a638
JS
180/**
181 Prevents user from leaving property unless value is valid. If this
1c4293cb
VZ
182 behavior flag is not used, then value change is instead cancelled.
183*/
184wxPG_VFB_STAY_IN_PROPERTY = 0x01,
185
6b03a638
JS
186/**
187 Calls wxBell() on validation failure.
1c4293cb
VZ
188*/
189wxPG_VFB_BEEP = 0x02,
190
6b03a638
JS
191/**
192 Cell with invalid value will be marked (with red colour).
1c4293cb
VZ
193*/
194wxPG_VFB_MARK_CELL = 0x04,
195
6b03a638
JS
196/**
197 Display customizable text message explaining the situation.
1c4293cb
VZ
198*/
199wxPG_VFB_SHOW_MESSAGE = 0x08,
200
6b03a638
JS
201/**
202 Defaults.
203*/
1c4293cb 204wxPG_VFB_DEFAULT = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
1c4293cb
VZ
205};
206
207/** @}
208*/
209
210typedef wxByte wxPGVFBFlags;
211
2a8312bc
JS
212/**
213 wxPGValidationInfo
214
215 Used to convey validation information to and from functions that
216 actually perform validation. Mostly used in custom property
217 classes.
218*/
219class wxPGValidationInfo
220{
221public:
222 /**
223 @return Returns failure behavior which is a combination of
224 @ref propgrid_vfbflags.
225 */
226 wxPGVFBFlags GetFailureBehavior();
227
228 /**
229 Returns current failure message.
230 */
231 const wxString& GetFailureMessage() const;
232
233 /**
234 Returns reference to pending value.
235 */
236 const wxVariant& GetValue() const;
237
238 /** Set validation failure behavior
239
240 @param failureBehavior
241 Mixture of @ref propgrid_vfbflags.
242 */
243 void SetFailureBehavior(wxPGVFBFlags failureBehavior);
244
245 /**
246 Set current failure message.
247 */
248 void SetFailureMessage(const wxString& message);
249};
250
1c4293cb
VZ
251// -----------------------------------------------------------------------
252
6b03a638
JS
253/**
254 @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
255 These are used with wxPropertyGrid::AddActionTrigger() and
256 wxPropertyGrid::ClearActionTriggers().
1c4293cb
VZ
257 @{
258*/
259
260enum wxPG_KEYBOARD_ACTIONS
261{
262 wxPG_ACTION_INVALID = 0,
263 wxPG_ACTION_NEXT_PROPERTY,
264 wxPG_ACTION_PREV_PROPERTY,
265 wxPG_ACTION_EXPAND_PROPERTY,
266 wxPG_ACTION_COLLAPSE_PROPERTY,
267 wxPG_ACTION_CANCEL_EDIT,
268 wxPG_ACTION_CUT,
269 wxPG_ACTION_COPY,
270 wxPG_ACTION_PASTE,
271 wxPG_ACTION_MAX
272};
273
274/** @}
275*/
276
277// -----------------------------------------------------------------------
278
279/** @class wxPropertyGrid
280
bba3f9b5
JS
281 wxPropertyGrid is a specialized grid for editing properties - in other
282 words name = value pairs. List of ready-to-use property classes include
6b03a638 283 strings, numbers, flag sets, fonts, colours and many others. It is possible,
bba3f9b5
JS
284 for example, to categorize properties, set up a complete tree-hierarchy,
285 add more than two columns, and set arbitrary per-property attributes.
1c4293cb 286
6b03a638
JS
287 Please note that most member functions are inherited and as such not
288 documented on this page. This means you will probably also want to read
289 wxPropertyGridInterface class reference.
1c4293cb
VZ
290
291 See also @ref overview_propgrid.
292
293 @section propgrid_window_styles_ Window Styles
294
295 See @ref propgrid_window_styles.
296
297 @section propgrid_event_handling Event Handling
298
6b03a638
JS
299 To process input from a property grid control, use these event handler macros
300 to direct input to member functions that take a wxPropertyGridEvent argument.
1c4293cb
VZ
301
302 @beginEventTable{wxPropertyGridEvent}
303 @event{EVT_PG_SELECTED (id, func)}
304 Respond to wxEVT_PG_SELECTED event, generated when property value
305 has been changed by user.
306 @event{EVT_PG_CHANGING(id, func)}
307 Respond to wxEVT_PG_CHANGING event, generated when property value
308 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
309 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
310 to prevent change from taking place, if necessary.
311 @event{EVT_PG_HIGHLIGHTED(id, func)}
312 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
313 moves over a property. Event's property is NULL if hovered area does
314 not belong to any property.
315 @event{EVT_PG_RIGHT_CLICK(id, func)}
316 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
317 clicked on with right mouse button.
318 @event{EVT_PG_DOUBLE_CLICK(id, func)}
319 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
6b03a638 320 double-clicked on with left mouse button.
1c4293cb
VZ
321 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
322 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
6b03a638 323 a property or category.
1c4293cb
VZ
324 @event{EVT_PG_ITEM_EXPANDED(id, func)}
325 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
6b03a638 326 a property or category.
1c4293cb
VZ
327 @endEventTable
328
329 @remarks
330
331 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
6b03a638
JS
332 will also delay sorting etc. miscellaneous calculations to the last
333 possible moment.
1c4293cb
VZ
334
335 @library{wxpropgrid}
336 @category{propgrid}
337*/
338class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
339{
340public:
341
6b03a638
JS
342 /**
343 Two step constructor. Call Create when this constructor is called to
344 build up the wxPropertyGrid
1c4293cb
VZ
345 */
346 wxPropertyGrid();
347
6b03a638
JS
348 /**
349 Constructor. The styles to be used are styles valid for
1c4293cb 350 the wxWindow and wxScrolledWindow.
6b03a638
JS
351
352 @see @ref propgrid_window_styles.
1c4293cb
VZ
353 */
354 wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
355 const wxPoint& pos = wxDefaultPosition,
356 const wxSize& size = wxDefaultSize,
357 long style = wxPG_DEFAULT_STYLE,
358 const wxChar* name = wxPropertyGridNameStr );
359
360 /** Destructor */
361 virtual ~wxPropertyGrid();
362
6b03a638
JS
363 /**
364 Adds given key combination to trigger given action.
365
1c4293cb 366 @param action
6b03a638
JS
367 Which action to trigger. See @ref propgrid_keyboard_actions.
368
369 @param keycode
370 Which keycode triggers the action.
371
372 @param modifiers
373 Which key event modifiers, in addition to keycode, are needed to
374 trigger the action.
1c4293cb
VZ
375 */
376 void AddActionTrigger( int action, int keycode, int modifiers = 0 );
377
6b03a638
JS
378 /**
379 This static function enables or disables automatic use of
380 wxGetTranslation() for following strings: wxEnumProperty list labels,
381 wxFlagsProperty child property labels.
382
1c4293cb
VZ
383 Default is false.
384 */
385 static void AutoGetTranslation( bool enable );
386
6b03a638
JS
387 /**
388 Changes value of a property, as if from an editor. Use this instead of
389 SetPropertyValue() if you need the value to run through validation
390 process, and also send the property change event.
1c4293cb 391
6b03a638 392 @return Returns true if value was successfully changed.
1c4293cb
VZ
393 */
394 bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
395
6b03a638
JS
396 /**
397 Centers the splitter. If argument is true, automatic splitter centering
398 is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
399 defined).
1c4293cb
VZ
400 */
401 void CenterSplitter( bool enable_auto_centering = false );
402
6b03a638
JS
403 /**
404 Deletes all properties.
1c4293cb
VZ
405 */
406 virtual void Clear();
407
6b03a638
JS
408 /**
409 Clears action triggers for given action.
410
1c4293cb 411 @param action
6b03a638 412 Which action to trigger. @ref propgrid_keyboard_actions.
1c4293cb
VZ
413 */
414 void ClearActionTriggers( int action );
415
6b03a638
JS
416 /**
417 Forces updating the value of property from the editor control.
418 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
419 ProcessEvent, meaning your event handlers will be called immediately.
1c4293cb 420
6b03a638 421 @return Returns @true if anything was changed.
1c4293cb
VZ
422 */
423 virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
424
6b03a638
JS
425 /**
426 Two step creation. Whenever the control is created without any
427 parameters, use Create to actually create it. Don't access the control's
428 public methods before this is called
429
430 @see @ref propgrid_window_styles.
1c4293cb
VZ
431 */
432 bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
433 const wxPoint& pos = wxDefaultPosition,
434 const wxSize& size = wxDefaultSize,
435 long style = wxPG_DEFAULT_STYLE,
436 const wxChar* name = wxPropertyGridNameStr );
437
6b03a638
JS
438 /**
439 Call when editor widget's contents is modified. For example, this is
440 called when changes text in wxTextCtrl (used in wxStringProperty and
441 wxIntProperty).
1c4293cb 442
6b03a638 443 @remarks This function should only be called by custom properties.
1c4293cb
VZ
444
445 @see wxPGProperty::OnEvent()
446 */
447 void EditorsValueWasModified() { m_iFlags |= wxPG_FL_VALUE_MODIFIED; }
448
6b03a638
JS
449 /**
450 Reverse of EditorsValueWasModified().
1c4293cb 451
6b03a638 452 @remarks This function should only be called by custom properties.
1c4293cb
VZ
453 */
454 void EditorsValueWasNotModified()
455 {
456 m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
457 }
458
6b03a638
JS
459 /**
460 Enables or disables (shows/hides) categories according to parameter
461 enable.
462 */
1c4293cb
VZ
463 bool EnableCategories( bool enable );
464
6b03a638
JS
465 /**
466 Scrolls and/or expands items to ensure that the given item is visible.
467
468 @return Returns @true if something was actually done.
1c4293cb
VZ
469 */
470 bool EnsureVisible( wxPGPropArg id );
471
6b03a638
JS
472 /**
473 Reduces column sizes to minimum possible, while still retaining
474 fully visible grid contents (labels, images).
1c4293cb 475
6b03a638 476 @return Minimum size for the grid to still display everything.
1c4293cb 477
6b03a638 478 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
1c4293cb 479
6b03a638
JS
480 This function only works properly if grid size prior to call was
481 already fairly large.
1c4293cb 482
6b03a638
JS
483 Note that you can also get calculated column widths by calling
484 GetState->GetColumnWidth() immediately after this function
485 returns.
1c4293cb 486 */
6b03a638 487 wxSize FitColumns();
1c4293cb 488
6b03a638
JS
489 /**
490 Returns wxWindow that the properties are painted on, and which should be
491 used as the parent for editor controls.
1c4293cb 492 */
6b03a638 493 wxPanel* GetPanel() const;
1c4293cb 494
6b03a638
JS
495 /**
496 Returns current category caption background colour.
497 */
498 wxColour GetCaptionBackgroundColour() const;
1c4293cb 499
6b03a638
JS
500 /**
501 Returns current category caption font.
502 */
503 wxFont& GetCaptionFont();
1c4293cb 504
6b03a638
JS
505 /**
506 Returns current category caption text colour.
507 */
508 wxColour GetCaptionForegroundColour() const;
1c4293cb 509
6b03a638
JS
510 /**
511 Returns current cell background colour.
512 */
513 wxColour GetCellBackgroundColour() const;
1c4293cb 514
6b03a638
JS
515 /**
516 Returns current cell text colour when disabled.
517 */
518 wxColour GetCellDisabledTextColour() const;
1c4293cb 519
6b03a638
JS
520 /**
521 Returns current cell text colour.
522 */
523 wxColour GetCellTextColour() const;
1c4293cb 524
6b03a638
JS
525 /**
526 Returns number of columns currently on grid.
527 */
528 int GetColumnCount() const;
1c4293cb 529
6b03a638
JS
530 /**
531 Returns colour of empty space below properties.
532 */
533 wxColour GetEmptySpaceColour() const;
1c4293cb 534
6b03a638
JS
535 /**
536 Returns height of highest characters of used font.
537 */
538 int GetFontHeight() const;
1c4293cb 539
6b03a638
JS
540 /**
541 Returns pointer to itself. Dummy function that enables same kind
1c4293cb
VZ
542 of code to use wxPropertyGrid and wxPropertyGridManager.
543 */
6b03a638
JS
544 wxPropertyGrid* GetGrid();
545
546 /**
547 Returns rectangle of custom paint image.
1c4293cb 548
6b03a638
JS
549 @param property
550 Return image rectangle for this property.
551
552 @param item
553 Which choice of property to use (each choice may have
554 different image).
1c4293cb 555 */
6b03a638
JS
556 wxRect GetImageRect( wxPGProperty* property, int item ) const;
557
558 /**
559 Returns size of the custom paint image in front of property.
1c4293cb 560
6b03a638
JS
561 @param property
562 Return image rectangle for this property.
563 If this argument is NULL, then preferred size is returned.
564
565 @param item
566 Which choice of property to use (each choice may have
567 different image).
1c4293cb 568 */
6b03a638
JS
569 wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
570
571 /**
572 Returns last item which could be iterated using given flags.
1c4293cb 573
1c4293cb 574 @param flags
6b03a638 575 See @ref propgrid_iterator_flags.
1c4293cb 576 */
6b03a638 577 wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );
1c4293cb 578
6b03a638
JS
579 /**
580 Returns colour of lines between cells.
581 */
582 wxColour GetLineColour() const;
1c4293cb 583
6b03a638
JS
584 /**
585 Returns background colour of margin.
586 */
587 wxColour GetMarginColour() const;
1c4293cb 588
6b03a638
JS
589 /**
590 Returns cell background colour of a property.
591 */
1c4293cb
VZ
592 wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const;
593
6b03a638
JS
594 /**
595 Returns cell background colour of a property.
596 */
1c4293cb
VZ
597 wxColour GetPropertyTextColour( wxPGPropArg id ) const;
598
6b03a638
JS
599 /**
600 Returns "root property". It does not have name, etc. and it is not
1c4293cb
VZ
601 visible. It is only useful for accessing its children.
602 */
6b03a638 603 wxPGProperty* GetRoot() const;
1c4293cb 604
6b03a638
JS
605 /**
606 Returns height of a single grid row (in pixels).
607 */
608 int GetRowHeight() const;
1c4293cb 609
6b03a638
JS
610 /**
611 Returns currently selected property.
612 */
613 wxPGProperty* GetSelectedProperty() const;
1c4293cb 614
6b03a638
JS
615 /**
616 Returns currently selected property.
617 */
618 wxPGProperty* GetSelection() const;
1c4293cb 619
6b03a638
JS
620 /**
621 Returns current selection background colour.
622 */
623 wxColour GetSelectionBackgroundColour() const;
1c4293cb 624
6b03a638
JS
625 /**
626 Returns current selection text colour.
627 */
628 wxColour GetSelectionForegroundColour() const;
1c4293cb 629
6b03a638
JS
630 /**
631 Returns current splitter x position.
632 */
633 int GetSplitterPosition() const;
1c4293cb 634
6b03a638
JS
635 /**
636 Returns wxTextCtrl active in currently selected property, if any. Takes
637 wxOwnerDrawnComboBox into account.
1c4293cb
VZ
638 */
639 wxTextCtrl* GetEditorTextCtrl() const;
640
6b03a638
JS
641 /**
642 Returns current vertical spacing.
643 */
1c4293cb
VZ
644 int GetVerticalSpacing() const { return (int)m_vspacing; }
645
6b03a638
JS
646 /**
647 Returns true if editor's value was marked modified.
1c4293cb 648 */
6b03a638 649 bool IsEditorsValueModified() const;
1c4293cb 650
6b03a638
JS
651 /**
652 Returns information about arbitrary position in the grid.
1c4293cb
VZ
653 */
654 wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
655
6b03a638
JS
656 /**
657 Returns true if any property has been modified by the user.
658 */
659 bool IsAnyModified() const;
1c4293cb 660
6b03a638
JS
661 /**
662 Returns true if updating is frozen (ie. Freeze() called but not
663 yet Thaw() ).
664 */
665 bool IsFrozen() const;
1c4293cb 666
6b03a638
JS
667 /**
668 Redraws given property.
1c4293cb
VZ
669 */
670 virtual void RefreshProperty( wxPGProperty* p );
671
6b03a638
JS
672 /**
673 Registers a new editor class.
674
675 @return Returns pointer to the editor class instance that should be used.
1c4293cb 676 */
6b03a638
JS
677 static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
678 const wxString& name,
1c4293cb
VZ
679 bool noDefCheck = false );
680
6b03a638
JS
681 /**
682 Resets all colours to the original system values.
1c4293cb
VZ
683 */
684 void ResetColours();
685
6b03a638
JS
686 /**
687 Selects a property. Editor widget is automatically created, but
688 not focused unless focus is true. This will generate wxEVT_PG_SELECT
689 event.
690
1c4293cb 691 @param id
6b03a638
JS
692 Property to select (name or pointer).
693
694 @param focus
695 If @true, move keyboard focus to the created editor right away.
696
697 @return returns @true if selection finished successfully. Usually only
698 fails if current value in editor is not valid.
699
700 @see wxPropertyGrid::ClearSelection()
1c4293cb 701 */
6b03a638
JS
702 bool SelectProperty( wxPGPropArg id, bool focus = false );
703
704 /**
705 Changes keyboard shortcut to push the editor button.
1c4293cb 706
6b03a638
JS
707 @remarks You can set default with keycode 0. Good value for the platform
708 is guessed, but don't expect it to be very accurate.
1c4293cb
VZ
709 */
710 void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
711
6b03a638
JS
712 /**
713 Sets category caption background colour.
714 */
1c4293cb
VZ
715 void SetCaptionBackgroundColour(const wxColour& col);
716
6b03a638
JS
717 /**
718 Sets category caption text colour.
719 */
1c4293cb
VZ
720 void SetCaptionTextColour(const wxColour& col);
721
6b03a638
JS
722 /**
723 Sets default cell background colour - applies to property cells.
1c4293cb
VZ
724 Note that appearance of editor widgets may not be affected.
725 */
726 void SetCellBackgroundColour(const wxColour& col);
727
6b03a638
JS
728 /**
729 Sets cell text colour for disabled properties.
1c4293cb
VZ
730 */
731 void SetCellDisabledTextColour(const wxColour& col);
732
6b03a638
JS
733 /**
734 Sets default cell text colour - applies to property name and value text.
1c4293cb
VZ
735 Note that appearance of editor widgets may not be affected.
736 */
737 void SetCellTextColour(const wxColour& col);
738
6b03a638
JS
739 /**
740 Set number of columns (2 or more).
1c4293cb 741 */
6b03a638 742 void SetColumnCount( int colCount );
1c4293cb 743
6b03a638
JS
744 /**
745 Sets the 'current' category - Append will add non-category properties
746 under it.
1c4293cb
VZ
747 */
748 void SetCurrentCategory( wxPGPropArg id );
749
6b03a638
JS
750 /**
751 Sets colour of empty space below properties.
752 */
1c4293cb
VZ
753 void SetEmptySpaceColour(const wxColour& col);
754
6b03a638
JS
755 /**
756 Sets colour of lines between cells.
757 */
1c4293cb
VZ
758 void SetLineColour(const wxColour& col);
759
6b03a638
JS
760 /**
761 Sets background colour of margin.
762 */
1c4293cb
VZ
763 void SetMarginColour(const wxColour& col);
764
6b03a638
JS
765 /**
766 Sets background colour of property and all its children. Colours of
1c4293cb
VZ
767 captions are not affected. Background brush cache is optimized for often
768 set colours to be set last.
769 */
770 void SetPropertyBackgroundColour( wxPGPropArg id, const wxColour& col );
771
6b03a638
JS
772 /**
773 Resets text and background colours of given property.
1c4293cb
VZ
774 */
775 void SetPropertyColoursToDefault( wxPGPropArg id );
776
6b03a638
JS
777 /**
778 Sets text colour of property and all its children.
1c4293cb 779 */
6b03a638
JS
780 void SetPropertyTextColour( wxPGPropArg id, const wxColour& col,
781 bool recursively = true );
1c4293cb 782
6b03a638
JS
783 /** Sets selection background colour - applies to selected property name
784 background. */
1c4293cb
VZ
785 void SetSelectionBackgroundColour(const wxColour& col);
786
6b03a638
JS
787 /** Sets selection foreground colour - applies to selected property name
788 text. */
1c4293cb
VZ
789 void SetSelectionTextColour(const wxColour& col);
790
791 /** Sets x coordinate of the splitter.
6b03a638
JS
792
793 @remarks Splitter position cannot exceed grid size, and therefore setting
794 it during form creation may fail as initial grid size is often
795 smaller than desired splitter position, especially when sizers
796 are being used.
1c4293cb 797 */
6b03a638 798 void SetSplitterPosition( int newxpos, int col = 0 );
1c4293cb 799
6b03a638
JS
800 /**
801 Moves splitter as left as possible, while still allowing all
1c4293cb 802 labels to be shown in full.
6b03a638
JS
803
804 @param privateChildrenToo
805 If @false, will still allow private children to be cropped.
1c4293cb 806 */
6b03a638 807 void SetSplitterLeft( bool privateChildrenToo = false )
1c4293cb
VZ
808 {
809 m_pState->SetSplitterLeft(subProps);
810 }
811
6b03a638
JS
812 /**
813 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1c4293cb 814 height. Value of 2 should be default on most platforms.
1c4293cb 815 */
6b03a638 816 void SetVerticalSpacing( int vspacing );
1c4293cb 817
6b03a638
JS
818 /**
819 Shows an brief error message that is related to a property.
820 */
821 void ShowPropertyError( wxPGPropArg id, const wxString& msg );
1c4293cb 822
6b03a638
JS
823 /**
824 Sorts all items at all levels (except private children).
825 */
1c4293cb
VZ
826 void Sort();
827
6b03a638
JS
828 /**
829 Sorts children of a property.
1c4293cb
VZ
830 */
831 void SortChildren( wxPGPropArg id );
832};
833
834
6b03a638
JS
835/**
836 @class wxPropertyGridEvent
1c4293cb 837
6b03a638 838 A property grid event holds information about events associated with
1c4293cb
VZ
839 wxPropertyGrid objects.
840
841 @library{wxpropgrid}
842 @category{propgrid}
843*/
844class wxPropertyGridEvent : public wxCommandEvent
845{
846public:
847
848 /** Constructor. */
849 wxPropertyGridEvent(wxEventType commandType=0, int id=0);
850
851 /** Copy constructor. */
852 wxPropertyGridEvent(const wxPropertyGridEvent& event);
853
854 /** Destructor. */
855 ~wxPropertyGridEvent();
856
6b03a638
JS
857 /**
858 Returns true if you can veto the action that the event is signaling.
859 */
860 bool CanVeto() const { return m_canVeto; }
861
1c4293cb
VZ
862 /** Copyer. */
863 virtual wxEvent* Clone() const;
864
6b03a638
JS
865 /**
866 Returns highest level non-category, non-root parent of property for
867 which event occurred. Useful when you have nested properties with
868 children.
1c4293cb 869
6b03a638
JS
870 @remarks If immediate parent is root or category, this will return the
871 property itself.
872 */
873 wxPGProperty* GetMainParent() const;
1c4293cb 874
6b03a638
JS
875 /**
876 Returns property associated with this event.
877 */
878 wxPGProperty* GetProperty() const;
1c4293cb 879
6b03a638
JS
880 /**
881 Returns current validation failure flags.
1c4293cb 882 */
6b03a638 883 wxPGVFBFlags GetValidationFailureBehavior() const;
1c4293cb 884
6b03a638
JS
885 /**
886 Returns value that is about to be set for wxEVT_PG_CHANGING.
1c4293cb 887 */
6b03a638 888 const wxVariant& GetValue() const;
1c4293cb 889
6b03a638
JS
890 /**
891 Set if event can be vetoed.
1c4293cb 892 */
6b03a638
JS
893 void SetCanVeto( bool canVeto );
894
895 /** Changes the property associated with this event. */
896 void SetProperty( wxPGProperty* p );
1c4293cb 897
6b03a638
JS
898 /**
899 Set override validation failure behavior. Only effective if Veto() was
900 also called, and only allowed if event type is wxEVT_PG_CHANGING.
1c4293cb 901 */
2a8312bc 902 void SetValidationFailureBehavior( wxPGVFBFlags flags );
1c4293cb 903
6b03a638
JS
904 /**
905 Sets custom failure message for this time only. Only applies if
1c4293cb
VZ
906 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
907 */
6b03a638 908 void SetValidationFailureMessage( const wxString& message );
1c4293cb 909
6b03a638
JS
910 /**
911 Call this from your event handler to veto action that the event is
912 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
913 returns true.
1c4293cb 914
6b03a638
JS
915 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
916 */
917 void Veto( bool veto = true );
1c4293cb 918
6b03a638
JS
919 /**
920 Returns @true if event was vetoed.
921 */
922 bool WasVetoed() const;
1c4293cb 923};