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