| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: propgrid.h |
| 3 | // Purpose: interface of wxPropertyGrid |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | |
| 10 | /** |
| 11 | @section propgrid_window_styles wxPropertyGrid Window Styles |
| 12 | |
| 13 | SetWindowStyleFlag method can be used to modify some of these at run-time. |
| 14 | @{ |
| 15 | */ |
| 16 | enum wxPG_WINDOW_STYLES |
| 17 | { |
| 18 | |
| 19 | /** |
| 20 | This will cause Sort() automatically after an item is added. |
| 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 | */ |
| 25 | wxPG_AUTO_SORT = 0x00000010, |
| 26 | |
| 27 | /** |
| 28 | Categories are not initially shown (even if added). |
| 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 | */ |
| 33 | wxPG_HIDE_CATEGORIES = 0x00000020, |
| 34 | |
| 35 | /** |
| 36 | This style combines non-categoric mode and automatic sorting. |
| 37 | */ |
| 38 | wxPG_ALPHABETIC_MODE = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT), |
| 39 | |
| 40 | /** |
| 41 | Modified values are shown in bold font. Changing this requires Refresh() |
| 42 | to show changes. |
| 43 | */ |
| 44 | wxPG_BOLD_MODIFIED = 0x00000040, |
| 45 | |
| 46 | /** |
| 47 | When wxPropertyGrid is resized, splitter moves to the center. This |
| 48 | behaviour stops once the user manually moves the splitter. |
| 49 | */ |
| 50 | wxPG_SPLITTER_AUTO_CENTER = 0x00000080, |
| 51 | |
| 52 | /** |
| 53 | Display tool tips for cell text that cannot be shown completely. If |
| 54 | wxUSE_TOOLTIPS is 0, then this doesn't have any effect. |
| 55 | */ |
| 56 | wxPG_TOOLTIPS = 0x00000100, |
| 57 | |
| 58 | /** |
| 59 | Disables margin and hides all expand/collapse buttons that would appear |
| 60 | outside the margin (for sub-properties). Toggling this style automatically |
| 61 | expands all collapsed items. |
| 62 | */ |
| 63 | wxPG_HIDE_MARGIN = 0x00000200, |
| 64 | |
| 65 | /** |
| 66 | This style prevents user from moving the splitter. |
| 67 | */ |
| 68 | wxPG_STATIC_SPLITTER = 0x00000400, |
| 69 | |
| 70 | /** |
| 71 | Combination of other styles that make it impossible for user to modify |
| 72 | the layout. |
| 73 | */ |
| 74 | wxPG_STATIC_LAYOUT = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER), |
| 75 | |
| 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. |
| 80 | */ |
| 81 | wxPG_LIMITED_EDITING = 0x00000800, |
| 82 | |
| 83 | /** |
| 84 | wxPropertyGridManager only: Show tool bar for mode and page selection. |
| 85 | */ |
| 86 | wxPG_TOOLBAR = 0x00001000, |
| 87 | |
| 88 | /** |
| 89 | wxPropertyGridManager only: Show adjustable text box showing description |
| 90 | or help text, if available, for currently selected property. |
| 91 | */ |
| 92 | wxPG_DESCRIPTION = 0x00002000, |
| 93 | |
| 94 | /** wxPropertyGridManager only: don't show an internal border around the |
| 95 | property grid. Recommended if you use a header. |
| 96 | */ |
| 97 | wxPG_NO_INTERNAL_BORDER = 0x00004000 |
| 98 | |
| 99 | }; |
| 100 | |
| 101 | enum wxPG_EX_WINDOW_STYLES |
| 102 | { |
| 103 | |
| 104 | /** |
| 105 | NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle() |
| 106 | member function. |
| 107 | |
| 108 | Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if |
| 109 | wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not |
| 110 | activated, and switching the mode first time becomes somewhat slower. |
| 111 | wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away. |
| 112 | |
| 113 | NOTE: If you do plan not switching to non-categoric mode, or if |
| 114 | you don't plan to use categories at all, then using this style will result |
| 115 | in waste of resources. |
| 116 | */ |
| 117 | wxPG_EX_INIT_NOCAT = 0x00001000, |
| 118 | |
| 119 | /** |
| 120 | Extended window style that sets wxPropertyGridManager tool bar to not |
| 121 | use flat style. |
| 122 | */ |
| 123 | wxPG_EX_NO_FLAT_TOOLBAR = 0x00002000, |
| 124 | |
| 125 | /** |
| 126 | Shows alphabetic/categoric mode buttons from tool bar. |
| 127 | */ |
| 128 | wxPG_EX_MODE_BUTTONS = 0x00008000, |
| 129 | |
| 130 | /** |
| 131 | Show property help strings as tool tips instead as text on the status bar. |
| 132 | You can set the help strings using SetPropertyHelpString member function. |
| 133 | */ |
| 134 | wxPG_EX_HELP_AS_TOOLTIPS = 0x00010000, |
| 135 | |
| 136 | /** |
| 137 | Allows relying on native double-buffering. |
| 138 | */ |
| 139 | wxPG_EX_NATIVE_DOUBLE_BUFFERING = 0x00080000, |
| 140 | |
| 141 | /** |
| 142 | Set this style to let user have ability to set values of properties to |
| 143 | unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for |
| 144 | all properties. |
| 145 | */ |
| 146 | wxPG_EX_AUTO_UNSPECIFIED_VALUES = 0x00200000, |
| 147 | |
| 148 | /** |
| 149 | If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and |
| 150 | wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus |
| 151 | they are not readable). |
| 152 | |
| 153 | Note that this option is global, and applies to all wxPG property containers. |
| 154 | */ |
| 155 | wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES = 0x00400000, |
| 156 | |
| 157 | /** |
| 158 | Hides page selection buttons from tool bar. |
| 159 | */ |
| 160 | wxPG_EX_HIDE_PAGE_BUTTONS = 0x01000000, |
| 161 | |
| 162 | /** Allows multiple properties to be selected by user (by pressing SHIFT |
| 163 | when clicking on a property, or by dragging with left mouse button |
| 164 | down). |
| 165 | |
| 166 | You can get array of selected properties with |
| 167 | wxPropertyGridInterface::GetSelectedProperties(). In multiple selection |
| 168 | mode wxPropertyGridInterface::GetSelection() returns |
| 169 | property which has editor active (usually the first one |
| 170 | selected). Other useful member functions are ClearSelection(), |
| 171 | AddToSelection() and RemoveFromSelection(). |
| 172 | */ |
| 173 | wxPG_EX_MULTIPLE_SELECTION = 0x02000000, |
| 174 | |
| 175 | /** |
| 176 | This enables top-level window tracking which allows wxPropertyGrid to |
| 177 | notify the application of last-minute property value changes by user. |
| 178 | |
| 179 | This style is not enabled by default because it may cause crashes when |
| 180 | wxPropertyGrid is used in with wxAUI or similar system. |
| 181 | |
| 182 | @remarks If you are not in fact using any system that may change |
| 183 | wxPropertyGrid's top-level parent window on its own, then you |
| 184 | are recommended to enable this style. |
| 185 | */ |
| 186 | wxPG_EX_ENABLE_TLP_TRACKING = 0x04000000, |
| 187 | |
| 188 | /** Don't show divider above toolbar, on Windows. |
| 189 | */ |
| 190 | wxPG_EX_NO_TOOLBAR_DIVIDER = 0x04000000, |
| 191 | |
| 192 | /** Show a separator below the toolbar. |
| 193 | */ |
| 194 | wxPG_EX_TOOLBAR_SEPARATOR = 0x08000000 |
| 195 | |
| 196 | }; |
| 197 | |
| 198 | /** Combines various styles. |
| 199 | */ |
| 200 | #define wxPG_DEFAULT_STYLE (0) |
| 201 | |
| 202 | /** Combines various styles. |
| 203 | */ |
| 204 | #define wxPGMAN_DEFAULT_STYLE (0) |
| 205 | |
| 206 | /** @} |
| 207 | */ |
| 208 | |
| 209 | // ----------------------------------------------------------------------- |
| 210 | |
| 211 | /** |
| 212 | @section propgrid_vfbflags wxPropertyGrid Validation Failure behaviour Flags |
| 213 | @{ |
| 214 | */ |
| 215 | |
| 216 | enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS |
| 217 | { |
| 218 | |
| 219 | /** |
| 220 | Prevents user from leaving property unless value is valid. If this |
| 221 | behaviour flag is not used, then value change is instead cancelled. |
| 222 | */ |
| 223 | wxPG_VFB_STAY_IN_PROPERTY = 0x01, |
| 224 | |
| 225 | /** |
| 226 | Calls wxBell() on validation failure. |
| 227 | */ |
| 228 | wxPG_VFB_BEEP = 0x02, |
| 229 | |
| 230 | /** |
| 231 | Cell with invalid value will be marked (with red colour). |
| 232 | */ |
| 233 | wxPG_VFB_MARK_CELL = 0x04, |
| 234 | |
| 235 | /** |
| 236 | Display a text message explaining the situation. |
| 237 | |
| 238 | To customize the way the message is displayed, you need to |
| 239 | reimplement wxPropertyGrid::DoShowPropertyError() in a |
| 240 | derived class. Default behaviour is to display the text on |
| 241 | the top-level frame's status bar, if present, and otherwise |
| 242 | using wxMessageBox. |
| 243 | */ |
| 244 | wxPG_VFB_SHOW_MESSAGE = 0x08, |
| 245 | |
| 246 | /** |
| 247 | Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the |
| 248 | message using wxMessageBox. |
| 249 | */ |
| 250 | wxPG_VFB_SHOW_MESSAGEBOX = 0x10, |
| 251 | |
| 252 | /** |
| 253 | Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the |
| 254 | message on the status bar (when present - you can reimplement |
| 255 | wxPropertyGrid::GetStatusBar() in a derived class to specify |
| 256 | this yourself). |
| 257 | */ |
| 258 | wxPG_VFB_SHOW_MESSAGE_ON_STATUSBAR = 0x20, |
| 259 | |
| 260 | /** |
| 261 | Defaults. |
| 262 | */ |
| 263 | wxPG_VFB_DEFAULT = wxPG_VFB_MARK_CELL | |
| 264 | wxPG_VFB_SHOW_MESSAGEBOX, |
| 265 | }; |
| 266 | |
| 267 | /** @} |
| 268 | */ |
| 269 | |
| 270 | typedef wxByte wxPGVFBFlags; |
| 271 | |
| 272 | /** |
| 273 | wxPGValidationInfo |
| 274 | |
| 275 | Used to convey validation information to and from functions that |
| 276 | actually perform validation. Mostly used in custom property classes. |
| 277 | */ |
| 278 | class wxPGValidationInfo |
| 279 | { |
| 280 | public: |
| 281 | /** |
| 282 | @return Returns failure behaviour which is a combination of |
| 283 | @ref propgrid_vfbflags. |
| 284 | */ |
| 285 | wxPGVFBFlags GetFailureBehavior(); |
| 286 | |
| 287 | /** |
| 288 | Returns current failure message. |
| 289 | */ |
| 290 | const wxString& GetFailureMessage() const; |
| 291 | |
| 292 | /** |
| 293 | Returns reference to pending value. |
| 294 | */ |
| 295 | wxVariant& GetValue(); |
| 296 | |
| 297 | /** Set validation failure behaviour |
| 298 | |
| 299 | @param failureBehavior |
| 300 | Mixture of @ref propgrid_vfbflags. |
| 301 | */ |
| 302 | void SetFailureBehavior(wxPGVFBFlags failureBehavior); |
| 303 | |
| 304 | /** |
| 305 | Set current failure message. |
| 306 | */ |
| 307 | void SetFailureMessage(const wxString& message); |
| 308 | }; |
| 309 | |
| 310 | // ----------------------------------------------------------------------- |
| 311 | |
| 312 | /** |
| 313 | @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers |
| 314 | |
| 315 | These are used with wxPropertyGrid::AddActionTrigger() and |
| 316 | wxPropertyGrid::ClearActionTriggers(). |
| 317 | @{ |
| 318 | */ |
| 319 | |
| 320 | enum wxPG_KEYBOARD_ACTIONS |
| 321 | { |
| 322 | wxPG_ACTION_INVALID = 0, |
| 323 | |
| 324 | /** Select the next property. */ |
| 325 | wxPG_ACTION_NEXT_PROPERTY, |
| 326 | |
| 327 | /** Select the previous property. */ |
| 328 | wxPG_ACTION_PREV_PROPERTY, |
| 329 | |
| 330 | /** Expand the selected property, if it has child items. */ |
| 331 | wxPG_ACTION_EXPAND_PROPERTY, |
| 332 | |
| 333 | /** Collapse the selected property, if it has child items. */ |
| 334 | wxPG_ACTION_COLLAPSE_PROPERTY, |
| 335 | |
| 336 | /** Cancel and undo any editing done in the currently active property |
| 337 | editor. |
| 338 | */ |
| 339 | wxPG_ACTION_CANCEL_EDIT, |
| 340 | |
| 341 | /** Move focus to the editor control of the currently selected |
| 342 | property. |
| 343 | */ |
| 344 | wxPG_ACTION_EDIT, |
| 345 | |
| 346 | /** Causes editor's button (if any) to be pressed. */ |
| 347 | wxPG_ACTION_PRESS_BUTTON, |
| 348 | |
| 349 | wxPG_ACTION_MAX |
| 350 | }; |
| 351 | |
| 352 | /** @} |
| 353 | */ |
| 354 | |
| 355 | /** This callback function is used for sorting properties. |
| 356 | |
| 357 | Call wxPropertyGrid::SetSortFunction() to set it. |
| 358 | |
| 359 | Sort function should return a value greater than 0 if position of p1 is |
| 360 | after p2. So, for instance, when comparing property names, you can use |
| 361 | following implementation: |
| 362 | |
| 363 | @code |
| 364 | int MyPropertySortFunction(wxPropertyGrid* propGrid, |
| 365 | wxPGProperty* p1, |
| 366 | wxPGProperty* p2) |
| 367 | { |
| 368 | return p1->GetBaseName().compare( p2->GetBaseName() ); |
| 369 | } |
| 370 | @endcode |
| 371 | */ |
| 372 | typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid, |
| 373 | wxPGProperty* p1, |
| 374 | wxPGProperty* p2); |
| 375 | |
| 376 | // ----------------------------------------------------------------------- |
| 377 | |
| 378 | /** |
| 379 | @class wxPropertyGrid |
| 380 | |
| 381 | wxPropertyGrid is a specialized grid for editing properties - in other |
| 382 | words name = value pairs. List of ready-to-use property classes include |
| 383 | strings, numbers, flag sets, fonts, colours and many others. It is possible, |
| 384 | for example, to categorize properties, set up a complete tree-hierarchy, |
| 385 | add more than two columns, and set arbitrary per-property attributes. |
| 386 | |
| 387 | Please note that most member functions are inherited and as such not |
| 388 | documented on this page. This means you will probably also want to read |
| 389 | wxPropertyGridInterface class reference. |
| 390 | |
| 391 | See also @ref overview_propgrid. |
| 392 | |
| 393 | @section propgrid_window_styles_ Window Styles |
| 394 | |
| 395 | See @ref propgrid_window_styles. |
| 396 | |
| 397 | @section propgrid_event_handling Event Handling |
| 398 | |
| 399 | To process input from a property grid control, use these event handler macros |
| 400 | to direct input to member functions that take a wxPropertyGridEvent argument. |
| 401 | |
| 402 | @beginEventEmissionTable{wxPropertyGridEvent} |
| 403 | @event{EVT_PG_SELECTED (id, func)} |
| 404 | Respond to @c wxEVT_PG_SELECTED event, generated when a property selection |
| 405 | has been changed, either by user action or by indirect program |
| 406 | function. For instance, collapsing a parent property programmatically |
| 407 | causes any selected child property to become unselected, and may |
| 408 | therefore cause this event to be generated. |
| 409 | @event{EVT_PG_CHANGED(id, func)} |
| 410 | Respond to @c wxEVT_PG_CHANGED event, generated when property value |
| 411 | has been changed by the user. |
| 412 | @event{EVT_PG_CHANGING(id, func)} |
| 413 | Respond to @c wxEVT_PG_CHANGING event, generated when property value |
| 414 | is about to be changed by user. Use wxPropertyGridEvent::GetValue() |
| 415 | to take a peek at the pending value, and wxPropertyGridEvent::Veto() |
| 416 | to prevent change from taking place, if necessary. |
| 417 | @event{EVT_PG_HIGHLIGHTED(id, func)} |
| 418 | Respond to @c wxEVT_PG_HIGHLIGHTED event, which occurs when mouse |
| 419 | moves over a property. Event's property is NULL if hovered area does |
| 420 | not belong to any property. |
| 421 | @event{EVT_PG_RIGHT_CLICK(id, func)} |
| 422 | Respond to @c wxEVT_PG_RIGHT_CLICK event, which occurs when property is |
| 423 | clicked on with right mouse button. |
| 424 | @event{EVT_PG_DOUBLE_CLICK(id, func)} |
| 425 | Respond to @c wxEVT_PG_DOUBLE_CLICK event, which occurs when property is |
| 426 | double-clicked on with left mouse button. |
| 427 | @event{EVT_PG_ITEM_COLLAPSED(id, func)} |
| 428 | Respond to @c wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses |
| 429 | a property or category. |
| 430 | @event{EVT_PG_ITEM_EXPANDED(id, func)} |
| 431 | Respond to @c wxEVT_PG_ITEM_EXPANDED event, generated when user expands |
| 432 | a property or category. |
| 433 | @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)} |
| 434 | Respond to @c wxEVT_PG_LABEL_EDIT_BEGIN event, generated when user is |
| 435 | about to begin editing a property label. You can veto this event to |
| 436 | prevent the action. |
| 437 | @event{EVT_PG_LABEL_EDIT_ENDING(id, func)} |
| 438 | Respond to @c wxEVT_PG_LABEL_EDIT_ENDING event, generated when user is |
| 439 | about to end editing of a property label. You can veto this event to |
| 440 | prevent the action. |
| 441 | @event{EVT_PG_COL_BEGIN_DRAG(id, func)} |
| 442 | Respond to @c wxEVT_PG_COL_BEGIN_DRAG event, generated when user |
| 443 | starts resizing a column - can be vetoed. |
| 444 | @event{EVT_PG_COL_DRAGGING,(id, func)} |
| 445 | Respond to @c wxEVT_PG_COL_DRAGGING, event, generated when a |
| 446 | column resize by user is in progress. This event is also generated |
| 447 | when user double-clicks the splitter in order to recenter |
| 448 | it. |
| 449 | @event{EVT_PG_COL_END_DRAG(id, func)} |
| 450 | Respond to @c wxEVT_PG_COL_END_DRAG event, generated after column |
| 451 | resize by user has finished. |
| 452 | @endEventTable |
| 453 | |
| 454 | @remarks |
| 455 | Use Freeze() and Thaw() respectively to disable and enable drawing. |
| 456 | This will also delay sorting etc. miscellaneous calculations to the last |
| 457 | possible moment. |
| 458 | |
| 459 | @library{wxpropgrid} |
| 460 | @category{propgrid} |
| 461 | @appearance{propertygrid} |
| 462 | */ |
| 463 | class wxPropertyGrid : public wxControl, |
| 464 | public wxScrollHelper, |
| 465 | public wxPropertyGridInterface |
| 466 | { |
| 467 | public: |
| 468 | /** |
| 469 | Two step constructor. |
| 470 | Call Create() when this constructor is called to build up the wxPropertyGrid |
| 471 | */ |
| 472 | wxPropertyGrid(); |
| 473 | |
| 474 | /** |
| 475 | Constructor. |
| 476 | The styles to be used are styles valid for the wxWindow. |
| 477 | |
| 478 | @see @ref propgrid_window_styles. |
| 479 | */ |
| 480 | wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY, |
| 481 | const wxPoint& pos = wxDefaultPosition, |
| 482 | const wxSize& size = wxDefaultSize, |
| 483 | long style = wxPG_DEFAULT_STYLE, |
| 484 | const wxString& name = wxPropertyGridNameStr ); |
| 485 | |
| 486 | /** Destructor */ |
| 487 | virtual ~wxPropertyGrid(); |
| 488 | |
| 489 | /** |
| 490 | Adds given key combination to trigger given action. |
| 491 | |
| 492 | Here is a sample code to make Enter key press move focus to |
| 493 | the next property. |
| 494 | |
| 495 | @code |
| 496 | propGrid->AddActionTrigger(wxPG_ACTION_NEXT_PROPERTY, |
| 497 | WXK_RETURN); |
| 498 | propGrid->DedicateKey(WXK_RETURN); |
| 499 | @endcode |
| 500 | |
| 501 | @param action |
| 502 | Which action to trigger. See @ref propgrid_keyboard_actions. |
| 503 | @param keycode |
| 504 | Which keycode triggers the action. |
| 505 | @param modifiers |
| 506 | Which key event modifiers, in addition to keycode, are needed to |
| 507 | trigger the action. |
| 508 | */ |
| 509 | void AddActionTrigger( int action, int keycode, int modifiers = 0 ); |
| 510 | |
| 511 | /** |
| 512 | Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION |
| 513 | extra style is not used, then this has same effect as |
| 514 | calling SelectProperty(). |
| 515 | |
| 516 | @remarks Multiple selection is not supported for categories. This |
| 517 | means that if you have properties selected, you cannot |
| 518 | add category to selection, and also if you have category |
| 519 | selected, you cannot add other properties to selection. |
| 520 | This member function will fail silently in these cases, |
| 521 | even returning true. |
| 522 | */ |
| 523 | bool AddToSelection( wxPGPropArg id ); |
| 524 | |
| 525 | /** |
| 526 | This static function enables or disables automatic use of |
| 527 | wxGetTranslation() for following strings: wxEnumProperty list labels, |
| 528 | wxFlagsProperty child property labels. |
| 529 | |
| 530 | Default is false. |
| 531 | */ |
| 532 | static void AutoGetTranslation( bool enable ); |
| 533 | |
| 534 | /** |
| 535 | Creates label editor wxTextCtrl for given column, for property |
| 536 | that is currently selected. When multiple selection is |
| 537 | enabled, this applies to whatever property GetSelection() |
| 538 | returns. |
| 539 | |
| 540 | @param colIndex |
| 541 | Which column's label to edit. Note that you should not |
| 542 | use value 1, which is reserved for property value |
| 543 | column. |
| 544 | |
| 545 | @see EndLabelEdit(), MakeColumnEditable() |
| 546 | */ |
| 547 | void BeginLabelEdit( unsigned int colIndex = 0 ); |
| 548 | |
| 549 | /** |
| 550 | Changes value of a property, as if from an editor. Use this instead of |
| 551 | SetPropertyValue() if you need the value to run through validation |
| 552 | process, and also send the property change event. |
| 553 | |
| 554 | @return Returns true if value was successfully changed. |
| 555 | */ |
| 556 | bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue ); |
| 557 | |
| 558 | /** |
| 559 | Centers the splitter. |
| 560 | |
| 561 | @param enableAutoResizing |
| 562 | If @true, automatic column resizing is enabled (only applicapple |
| 563 | if window style wxPG_SPLITTER_AUTO_CENTER is used). |
| 564 | */ |
| 565 | void CenterSplitter( bool enableAutoResizing = false ); |
| 566 | |
| 567 | /** |
| 568 | Deletes all properties. |
| 569 | */ |
| 570 | virtual void Clear(); |
| 571 | |
| 572 | /** |
| 573 | Clears action triggers for given action. |
| 574 | |
| 575 | @param action |
| 576 | Which action to trigger. @ref propgrid_keyboard_actions. |
| 577 | */ |
| 578 | void ClearActionTriggers( int action ); |
| 579 | |
| 580 | /** |
| 581 | Forces updating the value of property from the editor control. |
| 582 | Note that @c wxEVT_PG_CHANGING and @c wxEVT_PG_CHANGED are dispatched using |
| 583 | ProcessEvent, meaning your event handlers will be called immediately. |
| 584 | |
| 585 | @return Returns @true if anything was changed. |
| 586 | */ |
| 587 | virtual bool CommitChangesFromEditor( wxUint32 flags = 0 ); |
| 588 | |
| 589 | /** |
| 590 | Two step creation. Whenever the control is created without any |
| 591 | parameters, use Create to actually create it. Don't access the control's |
| 592 | public methods before this is called |
| 593 | |
| 594 | @see @ref propgrid_window_styles. |
| 595 | */ |
| 596 | bool Create( wxWindow *parent, wxWindowID id = wxID_ANY, |
| 597 | const wxPoint& pos = wxDefaultPosition, |
| 598 | const wxSize& size = wxDefaultSize, |
| 599 | long style = wxPG_DEFAULT_STYLE, |
| 600 | const wxString& name = wxPropertyGridNameStr ); |
| 601 | |
| 602 | /** |
| 603 | Dedicates a specific keycode to wxPropertyGrid. This means that such |
| 604 | key presses will not be redirected to editor controls. |
| 605 | |
| 606 | Using this function allows, for example, navigation between |
| 607 | properties using arrow keys even when the focus is in the editor |
| 608 | control. |
| 609 | */ |
| 610 | void DedicateKey( int keycode ); |
| 611 | |
| 612 | /** |
| 613 | Enables or disables (shows/hides) categories according to parameter |
| 614 | enable. |
| 615 | |
| 616 | @remarks This functions deselects selected property, if any. Validation |
| 617 | failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. |
| 618 | selection is cleared even if editor had invalid value. |
| 619 | */ |
| 620 | bool EnableCategories( bool enable ); |
| 621 | |
| 622 | /** |
| 623 | Destroys label editor wxTextCtrl, if any. |
| 624 | |
| 625 | @param commit |
| 626 | Use @true (default) to store edited label text in |
| 627 | property cell data. |
| 628 | |
| 629 | @see BeginLabelEdit(), MakeColumnEditable() |
| 630 | */ |
| 631 | void EndLabelEdit( bool commit = true ); |
| 632 | |
| 633 | /** |
| 634 | Scrolls and/or expands items to ensure that the given item is visible. |
| 635 | |
| 636 | @return Returns @true if something was actually done. |
| 637 | */ |
| 638 | bool EnsureVisible( wxPGPropArg id ); |
| 639 | |
| 640 | /** |
| 641 | Reduces column sizes to minimum possible, while still retaining |
| 642 | fully visible grid contents (labels, images). |
| 643 | |
| 644 | @return Minimum size for the grid to still display everything. |
| 645 | |
| 646 | @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style. |
| 647 | |
| 648 | This function only works properly if grid size prior to call was |
| 649 | already fairly large. |
| 650 | |
| 651 | Note that you can also get calculated column widths by calling |
| 652 | GetState->GetColumnWidth() immediately after this function |
| 653 | returns. |
| 654 | */ |
| 655 | wxSize FitColumns(); |
| 656 | |
| 657 | /** |
| 658 | Returns currently active label editor, NULL if none. |
| 659 | */ |
| 660 | wxTextCtrl* GetLabelEditor() const; |
| 661 | |
| 662 | /** |
| 663 | Returns wxWindow that the properties are painted on, and which should be |
| 664 | used as the parent for editor controls. |
| 665 | */ |
| 666 | wxWindow* GetPanel(); |
| 667 | |
| 668 | /** |
| 669 | Returns current category caption background colour. |
| 670 | */ |
| 671 | wxColour GetCaptionBackgroundColour() const; |
| 672 | |
| 673 | /** |
| 674 | Returns current category caption font. |
| 675 | */ |
| 676 | wxFont& GetCaptionFont(); |
| 677 | |
| 678 | /** |
| 679 | Returns current category caption text colour. |
| 680 | */ |
| 681 | wxColour GetCaptionForegroundColour() const; |
| 682 | |
| 683 | /** |
| 684 | Returns current cell background colour. |
| 685 | */ |
| 686 | wxColour GetCellBackgroundColour() const; |
| 687 | |
| 688 | /** |
| 689 | Returns current cell text colour when disabled. |
| 690 | */ |
| 691 | wxColour GetCellDisabledTextColour() const; |
| 692 | |
| 693 | /** |
| 694 | Returns current cell text colour. |
| 695 | */ |
| 696 | wxColour GetCellTextColour() const; |
| 697 | |
| 698 | /** |
| 699 | Returns number of columns currently on grid. |
| 700 | */ |
| 701 | unsigned int GetColumnCount() const; |
| 702 | |
| 703 | /** |
| 704 | Returns colour of empty space below properties. |
| 705 | */ |
| 706 | wxColour GetEmptySpaceColour() const; |
| 707 | |
| 708 | /** |
| 709 | Returns height of highest characters of used font. |
| 710 | */ |
| 711 | int GetFontHeight() const; |
| 712 | |
| 713 | /** |
| 714 | Returns pointer to itself. Dummy function that enables same kind |
| 715 | of code to use wxPropertyGrid and wxPropertyGridManager. |
| 716 | */ |
| 717 | wxPropertyGrid* GetGrid(); |
| 718 | |
| 719 | /** |
| 720 | Returns rectangle of custom paint image. |
| 721 | |
| 722 | @param property |
| 723 | Return image rectangle for this property. |
| 724 | |
| 725 | @param item |
| 726 | Which choice of property to use (each choice may have |
| 727 | different image). |
| 728 | */ |
| 729 | wxRect GetImageRect( wxPGProperty* property, int item ) const; |
| 730 | |
| 731 | /** |
| 732 | Returns size of the custom paint image in front of property. |
| 733 | |
| 734 | @param property |
| 735 | Return image rectangle for this property. |
| 736 | If this argument is NULL, then preferred size is returned. |
| 737 | |
| 738 | @param item |
| 739 | Which choice of property to use (each choice may have |
| 740 | different image). |
| 741 | */ |
| 742 | wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const; |
| 743 | |
| 744 | /** |
| 745 | Returns last item which could be iterated using given flags. |
| 746 | |
| 747 | @param flags |
| 748 | See @ref propgrid_iterator_flags. |
| 749 | */ |
| 750 | wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT ); |
| 751 | |
| 752 | /** |
| 753 | Returns colour of lines between cells. |
| 754 | */ |
| 755 | wxColour GetLineColour() const; |
| 756 | |
| 757 | /** |
| 758 | Returns background colour of margin. |
| 759 | */ |
| 760 | wxColour GetMarginColour() const; |
| 761 | |
| 762 | /** |
| 763 | Returns "root property". It does not have name, etc. and it is not |
| 764 | visible. It is only useful for accessing its children. |
| 765 | */ |
| 766 | wxPGProperty* GetRoot() const; |
| 767 | |
| 768 | /** |
| 769 | Returns height of a single grid row (in pixels). |
| 770 | */ |
| 771 | int GetRowHeight() const; |
| 772 | |
| 773 | /** |
| 774 | Returns currently selected property. |
| 775 | */ |
| 776 | wxPGProperty* GetSelectedProperty() const; |
| 777 | |
| 778 | /** |
| 779 | Returns currently selected property. |
| 780 | */ |
| 781 | wxPGProperty* GetSelection() const; |
| 782 | |
| 783 | /** |
| 784 | Returns current selection background colour. |
| 785 | */ |
| 786 | wxColour GetSelectionBackgroundColour() const; |
| 787 | |
| 788 | /** |
| 789 | Returns current selection text colour. |
| 790 | */ |
| 791 | wxColour GetSelectionForegroundColour() const; |
| 792 | |
| 793 | /** |
| 794 | Returns the property sort function (default is @NULL). |
| 795 | |
| 796 | @see SetSortFunction |
| 797 | */ |
| 798 | wxPGSortCallback GetSortFunction() const; |
| 799 | |
| 800 | /** |
| 801 | Returns current splitter x position. |
| 802 | */ |
| 803 | int GetSplitterPosition( unsigned int splitterIndex = 0 ) const; |
| 804 | |
| 805 | /** |
| 806 | Returns wxTextCtrl active in currently selected property, if any. Takes |
| 807 | wxOwnerDrawnComboBox into account. |
| 808 | */ |
| 809 | wxTextCtrl* GetEditorTextCtrl() const; |
| 810 | |
| 811 | /** |
| 812 | Returns current appearance of unspecified value cells. |
| 813 | |
| 814 | @see SetUnspecifiedValueAppearance() |
| 815 | */ |
| 816 | const wxPGCell& GetUnspecifiedValueAppearance() const; |
| 817 | |
| 818 | /** |
| 819 | Returns (visual) text representation of the unspecified |
| 820 | property value. |
| 821 | |
| 822 | @param argFlags For internal use only. |
| 823 | */ |
| 824 | wxString GetUnspecifiedValueText( int argFlags = 0 ) const; |
| 825 | |
| 826 | /** |
| 827 | Returns current vertical spacing. |
| 828 | */ |
| 829 | int GetVerticalSpacing() const; |
| 830 | |
| 831 | /** |
| 832 | Returns information about arbitrary position in the grid. |
| 833 | |
| 834 | @param pt |
| 835 | Coordinates in the virtual grid space. You may need to use |
| 836 | wxScrolled<T>::CalcScrolledPosition() for translating |
| 837 | wxPropertyGrid client coordinates into something this member |
| 838 | function can use. |
| 839 | */ |
| 840 | wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const; |
| 841 | |
| 842 | /** |
| 843 | Returns true if any property has been modified by the user. |
| 844 | */ |
| 845 | bool IsAnyModified() const; |
| 846 | |
| 847 | /** |
| 848 | Returns @true if a property editor control has focus. |
| 849 | */ |
| 850 | bool IsEditorFocused() const; |
| 851 | |
| 852 | /** |
| 853 | Returns true if updating is frozen (ie. Freeze() called but not |
| 854 | yet Thaw() ). |
| 855 | */ |
| 856 | bool IsFrozen() const; |
| 857 | |
| 858 | /** |
| 859 | Makes given column editable by user. |
| 860 | |
| 861 | @param column |
| 862 | The index of the column to make editable. |
| 863 | @param editable |
| 864 | Using @false here will disable column from being editable. |
| 865 | |
| 866 | @see BeginLabelEdit(), EndLabelEdit() |
| 867 | */ |
| 868 | void MakeColumnEditable( unsigned int column, bool editable = true ); |
| 869 | |
| 870 | /** |
| 871 | It is recommended that you call this function any time your code causes |
| 872 | wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle() |
| 873 | handler should be able to detect most changes, but it is not perfect. |
| 874 | |
| 875 | @param newTLP |
| 876 | New top-level parent that is about to be set. Old top-level parent |
| 877 | window should still exist as the current one. |
| 878 | |
| 879 | @remarks This function is automatically called from wxPropertyGrid:: |
| 880 | Reparent() and wxPropertyGridManager::Reparent(). You only |
| 881 | need to use it if you reparent wxPropertyGrid indirectly. |
| 882 | */ |
| 883 | void OnTLPChanging( wxWindow* newTLP ); |
| 884 | |
| 885 | /** |
| 886 | Refreshes any active editor control. |
| 887 | */ |
| 888 | void RefreshEditor(); |
| 889 | |
| 890 | /** |
| 891 | Redraws given property. |
| 892 | */ |
| 893 | virtual void RefreshProperty( wxPGProperty* p ); |
| 894 | |
| 895 | |
| 896 | /** Forwards to DoRegisterEditorClass with empty name. */ |
| 897 | static wxPGEditor* RegisterEditorClass( wxPGEditor* editor, |
| 898 | bool noDefCheck = false ); |
| 899 | /** |
| 900 | Registers a new editor class. |
| 901 | |
| 902 | @return Returns pointer to the editor class instance that should be used. |
| 903 | */ |
| 904 | static wxPGEditor* DoRegisterEditorClass( wxPGEditor* editor, |
| 905 | const wxString& name, |
| 906 | bool noDefCheck = false ); |
| 907 | |
| 908 | /** |
| 909 | Resets all colours to the original system values. |
| 910 | */ |
| 911 | void ResetColours(); |
| 912 | |
| 913 | /** |
| 914 | Resets column sizes and splitter positions, based on proportions. |
| 915 | |
| 916 | @param enableAutoResizing |
| 917 | If @true, automatic column resizing is enabled (only applicapple |
| 918 | if window style wxPG_SPLITTER_AUTO_CENTER is used). |
| 919 | |
| 920 | @see wxPropertyGridInterface::SetColumnProportion() |
| 921 | */ |
| 922 | void ResetColumnSizes( bool enableAutoResizing = false ); |
| 923 | |
| 924 | /** |
| 925 | Removes given property from selection. If property is not selected, |
| 926 | an assertion failure will occur. |
| 927 | */ |
| 928 | bool RemoveFromSelection( wxPGPropArg id ); |
| 929 | |
| 930 | /** |
| 931 | Selects a property. Editor widget is automatically created, but |
| 932 | not focused unless focus is true. |
| 933 | |
| 934 | @param id |
| 935 | Property to select (name or pointer). |
| 936 | |
| 937 | @param focus |
| 938 | If @true, move keyboard focus to the created editor right away. |
| 939 | |
| 940 | @return returns @true if selection finished successfully. Usually only |
| 941 | fails if current value in editor is not valid. |
| 942 | |
| 943 | @remarks In wxPropertyGrid 1.4, this member function used to generate |
| 944 | @c wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer |
| 945 | does that. |
| 946 | |
| 947 | @remarks This clears any previous selection. |
| 948 | |
| 949 | @see wxPropertyGridInterface::ClearSelection() |
| 950 | */ |
| 951 | bool SelectProperty( wxPGPropArg id, bool focus = false ); |
| 952 | |
| 953 | /** |
| 954 | Sets category caption background colour. |
| 955 | */ |
| 956 | void SetCaptionBackgroundColour(const wxColour& col); |
| 957 | |
| 958 | /** |
| 959 | Sets category caption text colour. |
| 960 | */ |
| 961 | void SetCaptionTextColour(const wxColour& col); |
| 962 | |
| 963 | /** |
| 964 | Sets default cell background colour - applies to property cells. |
| 965 | Note that appearance of editor widgets may not be affected. |
| 966 | */ |
| 967 | void SetCellBackgroundColour(const wxColour& col); |
| 968 | |
| 969 | /** |
| 970 | Sets cell text colour for disabled properties. |
| 971 | */ |
| 972 | void SetCellDisabledTextColour(const wxColour& col); |
| 973 | |
| 974 | /** |
| 975 | Sets default cell text colour - applies to property name and value text. |
| 976 | Note that appearance of editor widgets may not be affected. |
| 977 | */ |
| 978 | void SetCellTextColour(const wxColour& col); |
| 979 | |
| 980 | /** |
| 981 | Set number of columns (2 or more). |
| 982 | */ |
| 983 | void SetColumnCount( int colCount ); |
| 984 | |
| 985 | /** |
| 986 | Sets the 'current' category - Append will add non-category properties |
| 987 | under it. |
| 988 | */ |
| 989 | void SetCurrentCategory( wxPGPropArg id ); |
| 990 | |
| 991 | /** |
| 992 | Sets colour of empty space below properties. |
| 993 | */ |
| 994 | void SetEmptySpaceColour(const wxColour& col); |
| 995 | |
| 996 | /** |
| 997 | Sets colour of lines between cells. |
| 998 | */ |
| 999 | void SetLineColour(const wxColour& col); |
| 1000 | |
| 1001 | /** |
| 1002 | Sets background colour of margin. |
| 1003 | */ |
| 1004 | void SetMarginColour(const wxColour& col); |
| 1005 | |
| 1006 | /** |
| 1007 | Set entire new selection from given list of properties. |
| 1008 | */ |
| 1009 | void SetSelection( const wxArrayPGProperty& newSelection ); |
| 1010 | |
| 1011 | /** |
| 1012 | Sets selection background colour - applies to selected property name |
| 1013 | background. |
| 1014 | */ |
| 1015 | void SetSelectionBackgroundColour(const wxColour& col); |
| 1016 | |
| 1017 | /** |
| 1018 | Sets selection foreground colour - applies to selected property name text. |
| 1019 | */ |
| 1020 | void SetSelectionTextColour(const wxColour& col); |
| 1021 | |
| 1022 | |
| 1023 | /** |
| 1024 | Sets the property sorting function. |
| 1025 | |
| 1026 | @param sortFunction |
| 1027 | The sorting function to be used. It should return a value greater |
| 1028 | than 0 if position of p1 is after p2. So, for instance, when |
| 1029 | comparing property names, you can use following implementation: |
| 1030 | |
| 1031 | @code |
| 1032 | int MyPropertySortFunction(wxPropertyGrid* propGrid, |
| 1033 | wxPGProperty* p1, |
| 1034 | wxPGProperty* p2) |
| 1035 | { |
| 1036 | return p1->GetBaseName().compare( p2->GetBaseName() ); |
| 1037 | } |
| 1038 | @endcode |
| 1039 | |
| 1040 | @remarks |
| 1041 | Default property sort function sorts properties by their labels |
| 1042 | (case-insensitively). |
| 1043 | |
| 1044 | @see GetSortFunction, wxPropertyGridInterface::Sort, |
| 1045 | wxPropertyGridInterface::SortChildren |
| 1046 | */ |
| 1047 | void SetSortFunction( wxPGSortCallback sortFunction ); |
| 1048 | |
| 1049 | /** |
| 1050 | Sets x coordinate of the splitter. |
| 1051 | |
| 1052 | @remarks Splitter position cannot exceed grid size, and therefore setting |
| 1053 | it during form creation may fail as initial grid size is often |
| 1054 | smaller than desired splitter position, especially when sizers |
| 1055 | are being used. |
| 1056 | */ |
| 1057 | void SetSplitterPosition( int newxpos, int col = 0 ); |
| 1058 | |
| 1059 | /** |
| 1060 | Moves splitter as left as possible, while still allowing all |
| 1061 | labels to be shown in full. |
| 1062 | |
| 1063 | @param privateChildrenToo |
| 1064 | If @false, will still allow private children to be cropped. |
| 1065 | */ |
| 1066 | void SetSplitterLeft( bool privateChildrenToo = false ); |
| 1067 | |
| 1068 | /** |
| 1069 | Sets appearance of value cells representing an unspecified property |
| 1070 | value. Default appearance is blank. |
| 1071 | |
| 1072 | @remarks If you set the unspecified value to have any |
| 1073 | textual representation, then that will override |
| 1074 | "InlineHelp" attribute. |
| 1075 | |
| 1076 | @see wxPGProperty::SetValueToUnspecified(), |
| 1077 | wxPGProperty::IsValueUnspecified() |
| 1078 | */ |
| 1079 | void SetUnspecifiedValueAppearance( const wxPGCell& cell ); |
| 1080 | |
| 1081 | /** |
| 1082 | Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font |
| 1083 | height. Value of 2 should be default on most platforms. |
| 1084 | */ |
| 1085 | void SetVerticalSpacing( int vspacing ); |
| 1086 | |
| 1087 | /** |
| 1088 | @name wxPropertyGrid customization |
| 1089 | |
| 1090 | Reimplement these member functions in derived class for better |
| 1091 | control over wxPropertyGrid behaviour. |
| 1092 | */ |
| 1093 | //@{ |
| 1094 | |
| 1095 | /** |
| 1096 | Override in derived class to display error messages in custom manner |
| 1097 | (these message usually only result from validation failure). |
| 1098 | |
| 1099 | @remarks If you implement this, then you also need to implement |
| 1100 | DoHidePropertyError() - possibly to do nothing, if error |
| 1101 | does not need hiding (e.g. it was logged or shown in a |
| 1102 | message box). |
| 1103 | |
| 1104 | @see DoHidePropertyError() |
| 1105 | */ |
| 1106 | virtual void DoShowPropertyError( wxPGProperty* property, |
| 1107 | const wxString& msg ); |
| 1108 | |
| 1109 | /** |
| 1110 | Override in derived class to hide an error displayed by |
| 1111 | DoShowPropertyError(). |
| 1112 | |
| 1113 | @see DoShowPropertyError() |
| 1114 | */ |
| 1115 | virtual void DoHidePropertyError( wxPGProperty* property ); |
| 1116 | |
| 1117 | /** |
| 1118 | Return wxStatusBar that is used by this wxPropertyGrid. You can |
| 1119 | reimplement this member function in derived class to override |
| 1120 | the default behaviour of using the top-level wxFrame's status |
| 1121 | bar, if any. |
| 1122 | */ |
| 1123 | virtual wxStatusBar* GetStatusBar(); |
| 1124 | |
| 1125 | //@} |
| 1126 | |
| 1127 | /** |
| 1128 | @name Property development functions |
| 1129 | |
| 1130 | These member functions are usually only called when creating custom |
| 1131 | user properties. |
| 1132 | */ |
| 1133 | //@{ |
| 1134 | |
| 1135 | /** |
| 1136 | Call when editor widget's contents is modified. For example, this is |
| 1137 | called when changes text in wxTextCtrl (used in wxStringProperty and |
| 1138 | wxIntProperty). |
| 1139 | |
| 1140 | @remarks This function should only be called by custom properties. |
| 1141 | |
| 1142 | @see wxPGProperty::OnEvent() |
| 1143 | */ |
| 1144 | void EditorsValueWasModified(); |
| 1145 | |
| 1146 | /** |
| 1147 | Reverse of EditorsValueWasModified(). |
| 1148 | |
| 1149 | @remarks This function should only be called by custom properties. |
| 1150 | */ |
| 1151 | void EditorsValueWasNotModified(); |
| 1152 | |
| 1153 | /** |
| 1154 | Returns most up-to-date value of selected property. This will return |
| 1155 | value different from GetSelectedProperty()->GetValue() only when text |
| 1156 | editor is activate and string edited by user represents valid, |
| 1157 | uncommitted property value. |
| 1158 | */ |
| 1159 | wxVariant GetUncommittedPropertyValue(); |
| 1160 | |
| 1161 | /** |
| 1162 | Returns true if editor's value was marked modified. |
| 1163 | */ |
| 1164 | bool IsEditorsValueModified() const; |
| 1165 | |
| 1166 | /** |
| 1167 | Shows an brief error message that is related to a property. |
| 1168 | */ |
| 1169 | void ShowPropertyError( wxPGPropArg id, const wxString& msg ); |
| 1170 | |
| 1171 | /** |
| 1172 | You can use this member function, for instance, to detect in |
| 1173 | wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was |
| 1174 | already called in wxPGEditor::OnEvent(). It really only detects |
| 1175 | if was value was changed using wxPGProperty::SetValueInEvent(), which |
| 1176 | is usually used when a 'picker' dialog is displayed. If value was |
| 1177 | written by "normal means" in wxPGProperty::StringToValue() or |
| 1178 | IntToValue(), then this function will return false (on the other hand, |
| 1179 | wxPGProperty::OnEvent() is not even called in those cases). |
| 1180 | */ |
| 1181 | bool WasValueChangedInEvent() const; |
| 1182 | |
| 1183 | //@} |
| 1184 | }; |
| 1185 | |
| 1186 | |
| 1187 | /** |
| 1188 | @class wxPropertyGridEvent |
| 1189 | |
| 1190 | A property grid event holds information about events associated with |
| 1191 | wxPropertyGrid objects. |
| 1192 | |
| 1193 | @library{wxpropgrid} |
| 1194 | @category{propgrid} |
| 1195 | */ |
| 1196 | class wxPropertyGridEvent : public wxCommandEvent |
| 1197 | { |
| 1198 | public: |
| 1199 | |
| 1200 | /** Constructor. */ |
| 1201 | wxPropertyGridEvent(wxEventType commandType=0, int id=0); |
| 1202 | |
| 1203 | /** Copy constructor. */ |
| 1204 | wxPropertyGridEvent(const wxPropertyGridEvent& event); |
| 1205 | |
| 1206 | /** Destructor. */ |
| 1207 | ~wxPropertyGridEvent(); |
| 1208 | |
| 1209 | /** |
| 1210 | Returns true if you can veto the action that the event is signaling. |
| 1211 | */ |
| 1212 | bool CanVeto() const; |
| 1213 | |
| 1214 | /** |
| 1215 | Returns the column index associated with this event. |
| 1216 | For the column dragging events, it is the column to the left |
| 1217 | of the splitter being dragged |
| 1218 | */ |
| 1219 | unsigned int GetColumn() const; |
| 1220 | |
| 1221 | /** |
| 1222 | Returns highest level non-category, non-root parent of property for |
| 1223 | which event occurred. Useful when you have nested properties with |
| 1224 | children. |
| 1225 | |
| 1226 | @remarks If immediate parent is root or category, this will return the |
| 1227 | property itself. |
| 1228 | */ |
| 1229 | wxPGProperty* GetMainParent() const; |
| 1230 | |
| 1231 | /** |
| 1232 | Returns property associated with this event. |
| 1233 | |
| 1234 | @remarks You should assume that this property can always be NULL. |
| 1235 | For instance, @c wxEVT_PG_SELECTED is emitted not only when |
| 1236 | a new property is selected, but also when selection is |
| 1237 | cleared by user activity. |
| 1238 | */ |
| 1239 | wxPGProperty* GetProperty() const; |
| 1240 | |
| 1241 | /** |
| 1242 | Returns current validation failure flags. |
| 1243 | */ |
| 1244 | wxPGVFBFlags GetValidationFailureBehavior() const; |
| 1245 | |
| 1246 | /** |
| 1247 | Returns name of the associated property. |
| 1248 | |
| 1249 | @remarks Property name is stored in event, so it remains |
| 1250 | accessible even after the associated property or |
| 1251 | the property grid has been deleted. |
| 1252 | */ |
| 1253 | wxString GetPropertyName() const; |
| 1254 | |
| 1255 | /** |
| 1256 | Returns value of the associated property. Works for all event |
| 1257 | types, but for @c wxEVT_PG_CHANGING this member function returns |
| 1258 | the value that is pending, so you can call Veto() if the |
| 1259 | value is not satisfactory. |
| 1260 | |
| 1261 | @remarks Property value is stored in event, so it remains |
| 1262 | accessible even after the associated property or |
| 1263 | the property grid has been deleted. |
| 1264 | */ |
| 1265 | wxVariant GetPropertyValue() const |
| 1266 | |
| 1267 | /** |
| 1268 | @see GetPropertyValue() |
| 1269 | */ |
| 1270 | wxVariant GetValue() const; |
| 1271 | |
| 1272 | /** |
| 1273 | Set if event can be vetoed. |
| 1274 | */ |
| 1275 | void SetCanVeto( bool canVeto ); |
| 1276 | |
| 1277 | /** Changes the property associated with this event. */ |
| 1278 | void SetProperty( wxPGProperty* p ); |
| 1279 | |
| 1280 | /** |
| 1281 | Set override validation failure behaviour. Only effective if Veto() was |
| 1282 | also called, and only allowed if event type is @c wxEVT_PG_CHANGING. |
| 1283 | */ |
| 1284 | void SetValidationFailureBehavior( wxPGVFBFlags flags ); |
| 1285 | |
| 1286 | /** |
| 1287 | Sets custom failure message for this time only. Only applies if |
| 1288 | wxPG_VFB_SHOW_MESSAGE is set in validation failure flags. |
| 1289 | */ |
| 1290 | void SetValidationFailureMessage( const wxString& message ); |
| 1291 | |
| 1292 | /** |
| 1293 | Call this from your event handler to veto action that the event is |
| 1294 | signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto() |
| 1295 | returns true. |
| 1296 | |
| 1297 | @remarks Currently only @c wxEVT_PG_CHANGING supports vetoing. |
| 1298 | */ |
| 1299 | void Veto( bool veto = true ); |
| 1300 | |
| 1301 | /** |
| 1302 | Returns @true if event was vetoed. |
| 1303 | */ |
| 1304 | bool WasVetoed() const; |
| 1305 | }; |