X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1621f192d95b44c5909a788b8f1fe9e9c381df72..50d4763f1710f6e45ac6af7112d1ce9effe93bc4:/interface/wx/propgrid/propgrid.h diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h index de580e6384..3ab534149f 100644 --- a/interface/wx/propgrid/propgrid.h +++ b/interface/wx/propgrid/propgrid.h @@ -3,7 +3,7 @@ // Purpose: interface of wxPropertyGrid // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -45,7 +45,7 @@ wxPG_BOLD_MODIFIED = 0x00000040, /** When wxPropertyGrid is resized, splitter moves to the center. This - behavior stops once the user manually moves the splitter. + behaviour stops once the user manually moves the splitter. */ wxPG_SPLITTER_AUTO_CENTER = 0x00000080, @@ -89,7 +89,12 @@ wxPG_TOOLBAR = 0x00001000, wxPropertyGridManager only: Show adjustable text box showing description or help text, if available, for currently selected property. */ -wxPG_DESCRIPTION = 0x00002000 +wxPG_DESCRIPTION = 0x00002000, + +/** wxPropertyGridManager only: don't show an internal border around the + property grid. Recommended if you use a header. +*/ +wxPG_NO_INTERNAL_BORDER = 0x00004000 }; @@ -152,17 +157,51 @@ wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES = 0x00400000, /** Hides page selection buttons from tool bar. */ -wxPG_EX_HIDE_PAGE_BUTTONS = 0x01000000 +wxPG_EX_HIDE_PAGE_BUTTONS = 0x01000000, + +/** Allows multiple properties to be selected by user (by pressing SHIFT + when clicking on a property, or by dragging with left mouse button + down). + + You can get array of selected properties with + wxPropertyGridInterface::GetSelectedProperties(). In multiple selection + mode wxPropertyGridInterface::GetSelection() returns + property which has editor active (usually the first one + selected). Other useful member functions are ClearSelection(), + AddToSelection() and RemoveFromSelection(). +*/ +wxPG_EX_MULTIPLE_SELECTION = 0x02000000, + +/** + This enables top-level window tracking which allows wxPropertyGrid to + notify the application of last-minute property value changes by user. + + This style is not enabled by default because it may cause crashes when + wxPropertyGrid is used in with wxAUI or similar system. + + @remarks If you are not in fact using any system that may change + wxPropertyGrid's top-level parent window on its own, then you + are recommended to enable this style. +*/ +wxPG_EX_ENABLE_TLP_TRACKING = 0x04000000, + +/** Don't show divider above toolbar, on Windows. +*/ +wxPG_EX_NO_TOOLBAR_DIVIDER = 0x04000000, + +/** Show a separator below the toolbar. +*/ +wxPG_EX_TOOLBAR_SEPARATOR = 0x08000000 }; /** Combines various styles. */ -#define wxPG_DEFAULT_STYLE (0) +#define wxPG_DEFAULT_STYLE (0) /** Combines various styles. */ -#define wxPGMAN_DEFAULT_STYLE (0) +#define wxPGMAN_DEFAULT_STYLE (0) /** @} */ @@ -170,7 +209,7 @@ wxPG_EX_HIDE_PAGE_BUTTONS = 0x01000000 // ----------------------------------------------------------------------- /** - @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags + @section propgrid_vfbflags wxPropertyGrid Validation Failure behaviour Flags @{ */ @@ -179,7 +218,7 @@ enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS /** Prevents user from leaving property unless value is valid. If this - behavior flag is not used, then value change is instead cancelled. + behaviour flag is not used, then value change is instead cancelled. */ wxPG_VFB_STAY_IN_PROPERTY = 0x01, @@ -194,14 +233,35 @@ wxPG_VFB_BEEP = 0x02, wxPG_VFB_MARK_CELL = 0x04, /** - Display customizable text message explaining the situation. + Display a text message explaining the situation. + + To customize the way the message is displayed, you need to + reimplement wxPropertyGrid::DoShowPropertyError() in a + derived class. Default behaviour is to display the text on + the top-level frame's status bar, if present, and otherwise + using wxMessageBox. */ wxPG_VFB_SHOW_MESSAGE = 0x08, +/** + Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the + message using wxMessageBox. +*/ +wxPG_VFB_SHOW_MESSAGEBOX = 0x10, + +/** + Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the + message on the status bar (when present - you can reimplement + wxPropertyGrid::GetStatusBar() in a derived class to specify + this yourself). +*/ +wxPG_VFB_SHOW_MESSAGE_ON_STATUSBAR = 0x20, + /** Defaults. */ -wxPG_VFB_DEFAULT = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP, +wxPG_VFB_DEFAULT = wxPG_VFB_MARK_CELL | + wxPG_VFB_SHOW_MESSAGEBOX, }; /** @} @@ -219,7 +279,7 @@ class wxPGValidationInfo { public: /** - @return Returns failure behavior which is a combination of + @return Returns failure behaviour which is a combination of @ref propgrid_vfbflags. */ wxPGVFBFlags GetFailureBehavior(); @@ -232,9 +292,9 @@ public: /** Returns reference to pending value. */ - const wxVariant& GetValue() const; + wxVariant& GetValue(); - /** Set validation failure behavior + /** Set validation failure behaviour @param failureBehavior Mixture of @ref propgrid_vfbflags. @@ -260,17 +320,59 @@ public: enum wxPG_KEYBOARD_ACTIONS { wxPG_ACTION_INVALID = 0, + + /** Select the next property. */ wxPG_ACTION_NEXT_PROPERTY, + + /** Select the previous property. */ wxPG_ACTION_PREV_PROPERTY, + + /** Expand the selected property, if it has child items. */ wxPG_ACTION_EXPAND_PROPERTY, + + /** Collapse the selected property, if it has child items. */ wxPG_ACTION_COLLAPSE_PROPERTY, + + /** Cancel and undo any editing done in the currently active property + editor. + */ wxPG_ACTION_CANCEL_EDIT, + + /** Move focus to the editor control of the currently selected + property. + */ + wxPG_ACTION_EDIT, + + /** Causes editor's button (if any) to be pressed. */ + wxPG_ACTION_PRESS_BUTTON, + wxPG_ACTION_MAX }; /** @} */ +/** This callback function is used for sorting properties. + + Call wxPropertyGrid::SetSortFunction() to set it. + + Sort function should return a value greater than 0 if position of p1 is + after p2. So, for instance, when comparing property names, you can use + following implementation: + + @code + int MyPropertySortFunction(wxPropertyGrid* propGrid, + wxPGProperty* p1, + wxPGProperty* p2) + { + return p1->GetBaseName().compare( p2->GetBaseName() ); + } + @endcode +*/ +typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid, + wxPGProperty* p1, + wxPGProperty* p2); + // ----------------------------------------------------------------------- /** @@ -297,31 +399,56 @@ enum wxPG_KEYBOARD_ACTIONS To process input from a property grid control, use these event handler macros to direct input to member functions that take a wxPropertyGridEvent argument. - @beginEventTable{wxPropertyGridEvent} + @beginEventEmissionTable{wxPropertyGridEvent} @event{EVT_PG_SELECTED (id, func)} - Respond to wxEVT_PG_SELECTED event, generated when property value - has been changed by user. + Respond to @c wxEVT_PG_SELECTED event, generated when a property selection + has been changed, either by user action or by indirect program + function. For instance, collapsing a parent property programmatically + causes any selected child property to become unselected, and may + therefore cause this event to be generated. + @event{EVT_PG_CHANGED(id, func)} + Respond to @c wxEVT_PG_CHANGED event, generated when property value + has been changed by the user. @event{EVT_PG_CHANGING(id, func)} - Respond to wxEVT_PG_CHANGING event, generated when property value + Respond to @c wxEVT_PG_CHANGING event, generated when property value is about to be changed by user. Use wxPropertyGridEvent::GetValue() to take a peek at the pending value, and wxPropertyGridEvent::Veto() to prevent change from taking place, if necessary. @event{EVT_PG_HIGHLIGHTED(id, func)} - Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse + Respond to @c wxEVT_PG_HIGHLIGHTED event, which occurs when mouse moves over a property. Event's property is NULL if hovered area does not belong to any property. @event{EVT_PG_RIGHT_CLICK(id, func)} - Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is + Respond to @c wxEVT_PG_RIGHT_CLICK event, which occurs when property is clicked on with right mouse button. @event{EVT_PG_DOUBLE_CLICK(id, func)} - Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is + Respond to @c wxEVT_PG_DOUBLE_CLICK event, which occurs when property is double-clicked on with left mouse button. @event{EVT_PG_ITEM_COLLAPSED(id, func)} - Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses + Respond to @c wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses a property or category. @event{EVT_PG_ITEM_EXPANDED(id, func)} - Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands + Respond to @c wxEVT_PG_ITEM_EXPANDED event, generated when user expands a property or category. + @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)} + Respond to @c wxEVT_PG_LABEL_EDIT_BEGIN event, generated when user is + about to begin editing a property label. You can veto this event to + prevent the action. + @event{EVT_PG_LABEL_EDIT_ENDING(id, func)} + Respond to @c wxEVT_PG_LABEL_EDIT_ENDING event, generated when user is + about to end editing of a property label. You can veto this event to + prevent the action. + @event{EVT_PG_COL_BEGIN_DRAG(id, func)} + Respond to @c wxEVT_PG_COL_BEGIN_DRAG event, generated when user + starts resizing a column - can be vetoed. + @event{EVT_PG_COL_DRAGGING,(id, func)} + Respond to @c wxEVT_PG_COL_DRAGGING, event, generated when a + column resize by user is in progress. This event is also generated + when user double-clicks the splitter in order to recenter + it. + @event{EVT_PG_COL_END_DRAG(id, func)} + Respond to @c wxEVT_PG_COL_END_DRAG event, generated after column + resize by user has finished. @endEventTable @remarks @@ -333,7 +460,9 @@ enum wxPG_KEYBOARD_ACTIONS @category{propgrid} @appearance{propertygrid.png} */ -class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface +class wxPropertyGrid : public wxControl, + public wxScrollHelper, + public wxPropertyGridInterface { public: /** @@ -344,7 +473,7 @@ public: /** Constructor. - The styles to be used are styles valid for the wxWindow and wxScrolledWindow. + The styles to be used are styles valid for the wxWindow. @see @ref propgrid_window_styles. */ @@ -352,7 +481,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxPG_DEFAULT_STYLE, - const wxChar* name = wxPropertyGridNameStr ); + const wxString& name = wxPropertyGridNameStr ); /** Destructor */ virtual ~wxPropertyGrid(); @@ -360,6 +489,15 @@ public: /** Adds given key combination to trigger given action. + Here is a sample code to make Enter key press move focus to + the next property. + + @code + propGrid->AddActionTrigger(wxPG_ACTION_NEXT_PROPERTY, + WXK_RETURN); + propGrid->DedicateKey(WXK_RETURN); + @endcode + @param action Which action to trigger. See @ref propgrid_keyboard_actions. @param keycode @@ -370,6 +508,20 @@ public: */ void AddActionTrigger( int action, int keycode, int modifiers = 0 ); + /** + Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION + extra style is not used, then this has same effect as + calling SelectProperty(). + + @remarks Multiple selection is not supported for categories. This + means that if you have properties selected, you cannot + add category to selection, and also if you have category + selected, you cannot add other properties to selection. + This member function will fail silently in these cases, + even returning true. + */ + bool AddToSelection( wxPGPropArg id ); + /** This static function enables or disables automatic use of wxGetTranslation() for following strings: wxEnumProperty list labels, @@ -379,6 +531,21 @@ public: */ static void AutoGetTranslation( bool enable ); + /** + Creates label editor wxTextCtrl for given column, for property + that is currently selected. When multiple selection is + enabled, this applies to whatever property GetSelection() + returns. + + @param colIndex + Which column's label to edit. Note that you should not + use value 1, which is reserved for property value + column. + + @see EndLabelEdit(), MakeColumnEditable() + */ + void BeginLabelEdit( unsigned int colIndex = 0 ); + /** Changes value of a property, as if from an editor. Use this instead of SetPropertyValue() if you need the value to run through validation @@ -389,11 +556,13 @@ public: bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue ); /** - Centers the splitter. If argument is true, automatic splitter centering - is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was - defined). + Centers the splitter. + + @param enableAutoResizing + If @true, automatic column resizing is enabled (only applicapple + if window style wxPG_SPLITTER_AUTO_CENTER is used). */ - void CenterSplitter( bool enable_auto_centering = false ); + void CenterSplitter( bool enableAutoResizing = false ); /** Deletes all properties. @@ -410,7 +579,7 @@ public: /** Forces updating the value of property from the editor control. - Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using + Note that @c wxEVT_PG_CHANGING and @c wxEVT_PG_CHANGED are dispatched using ProcessEvent, meaning your event handlers will be called immediately. @return Returns @true if anything was changed. @@ -428,25 +597,17 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxPG_DEFAULT_STYLE, - const wxChar* name = wxPropertyGridNameStr ); + const wxString& name = wxPropertyGridNameStr ); /** - Call when editor widget's contents is modified. For example, this is - called when changes text in wxTextCtrl (used in wxStringProperty and - wxIntProperty). + Dedicates a specific keycode to wxPropertyGrid. This means that such + key presses will not be redirected to editor controls. - @remarks This function should only be called by custom properties. - - @see wxPGProperty::OnEvent() + Using this function allows, for example, navigation between + properties using arrow keys even when the focus is in the editor + control. */ - void EditorsValueWasModified(); - - /** - Reverse of EditorsValueWasModified(). - - @remarks This function should only be called by custom properties. - */ - void EditorsValueWasNotModified(); + void DedicateKey( int keycode ); /** Enables or disables (shows/hides) categories according to parameter @@ -458,6 +619,17 @@ public: */ bool EnableCategories( bool enable ); + /** + Destroys label editor wxTextCtrl, if any. + + @param commit + Use @true (default) to store edited label text in + property cell data. + + @see BeginLabelEdit(), MakeColumnEditable() + */ + void EndLabelEdit( bool commit = true ); + /** Scrolls and/or expands items to ensure that the given item is visible. @@ -482,11 +654,16 @@ public: */ wxSize FitColumns(); + /** + Returns currently active label editor, NULL if none. + */ + wxTextCtrl* GetLabelEditor() const; + /** Returns wxWindow that the properties are painted on, and which should be used as the parent for editor controls. */ - wxPanel* GetPanel() const; + wxWindow* GetPanel(); /** Returns current category caption background colour. @@ -582,14 +759,6 @@ public: */ wxColour GetMarginColour() const; - /** - Returns most up-to-date value of selected property. This will return - value different from GetSelectedProperty()->GetValue() only when text - editor is activate and string edited by user represents valid, - uncommitted property value. - */ - wxVariant GetUncommittedPropertyValue(); - /** Returns "root property". It does not have name, etc. and it is not visible. It is only useful for accessing its children. @@ -621,10 +790,17 @@ public: */ wxColour GetSelectionForegroundColour() const; + /** + Returns the property sort function (default is @NULL). + + @see SetSortFunction + */ + wxPGSortCallback GetSortFunction() const; + /** Returns current splitter x position. */ - int GetSplitterPosition() const; + int GetSplitterPosition( unsigned int splitterIndex = 0 ) const; /** Returns wxTextCtrl active in currently selected property, if any. Takes @@ -633,17 +809,33 @@ public: wxTextCtrl* GetEditorTextCtrl() const; /** - Returns current vertical spacing. + Returns current appearance of unspecified value cells. + + @see SetUnspecifiedValueAppearance() */ - int GetVerticalSpacing() const; + const wxPGCell& GetUnspecifiedValueAppearance() const; /** - Returns true if editor's value was marked modified. + Returns (visual) text representation of the unspecified + property value. + + @param argFlags For internal use only. */ - bool IsEditorsValueModified() const; + wxString GetUnspecifiedValueText( int argFlags = 0 ) const; + + /** + Returns current vertical spacing. + */ + int GetVerticalSpacing() const; /** Returns information about arbitrary position in the grid. + + @param pt + Coordinates in the virtual grid space. You may need to use + wxScrolled::CalcScrolledPosition() for translating + wxPropertyGrid client coordinates into something this member + function can use. */ wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const; @@ -652,6 +844,11 @@ public: */ bool IsAnyModified() const; + /** + Returns @true if a property editor control has focus. + */ + bool IsEditorFocused() const; + /** Returns true if updating is frozen (ie. Freeze() called but not yet Thaw() ). @@ -659,32 +856,52 @@ public: bool IsFrozen() const; /** - When creating custom property editors, connect required editor events to - this function. For instance: + Makes given column editable by user. - @code - control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED, - wxEventHandler(wxPropertyGrid::OnCustomEditorEvent), - NULL, propgrid); - @endcode + @param column + The index of the column to make editable. + @param editable + Using @false here will disable column from being editable. + + @see BeginLabelEdit(), EndLabelEdit() + */ + void MakeColumnEditable( unsigned int column, bool editable = true ); + + /** + It is recommended that you call this function any time your code causes + wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle() + handler should be able to detect most changes, but it is not perfect. - @remarks You should never need to call this function directly! + @param newTLP + New top-level parent that is about to be set. Old top-level parent + window should still exist as the current one. - @see wxPGEditor::CreateControls(), wxEvtHandler::Connect() + @remarks This function is automatically called from wxPropertyGrid:: + Reparent() and wxPropertyGridManager::Reparent(). You only + need to use it if you reparent wxPropertyGrid indirectly. */ - void OnCustomEditorEvent( wxEvent &event ); + void OnTLPChanging( wxWindow* newTLP ); + + /** + Refreshes any active editor control. + */ + void RefreshEditor(); /** Redraws given property. */ virtual void RefreshProperty( wxPGProperty* p ); + + /** Forwards to DoRegisterEditorClass with empty name. */ + static wxPGEditor* RegisterEditorClass( wxPGEditor* editor, + bool noDefCheck = false ); /** Registers a new editor class. @return Returns pointer to the editor class instance that should be used. */ - static wxPGEditor* RegisterEditorClass( wxPGEditor* editor, + static wxPGEditor* DoRegisterEditorClass( wxPGEditor* editor, const wxString& name, bool noDefCheck = false ); @@ -693,10 +910,26 @@ public: */ void ResetColours(); + /** + Resets column sizes and splitter positions, based on proportions. + + @param enableAutoResizing + If @true, automatic column resizing is enabled (only applicapple + if window style wxPG_SPLITTER_AUTO_CENTER is used). + + @see wxPropertyGridInterface::SetColumnProportion() + */ + void ResetColumnSizes( bool enableAutoResizing = false ); + + /** + Removes given property from selection. If property is not selected, + an assertion failure will occur. + */ + bool RemoveFromSelection( wxPGPropArg id ); + /** Selects a property. Editor widget is automatically created, but - not focused unless focus is true. This will generate wxEVT_PG_SELECT - event. + not focused unless focus is true. @param id Property to select (name or pointer). @@ -707,17 +940,15 @@ public: @return returns @true if selection finished successfully. Usually only fails if current value in editor is not valid. - @see wxPropertyGrid::ClearSelection() - */ - bool SelectProperty( wxPGPropArg id, bool focus = false ); + @remarks In wxPropertyGrid 1.4, this member function used to generate + @c wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer + does that. - /** - Changes keyboard shortcut to push the editor button. + @remarks This clears any previous selection. - @remarks You can set default with keycode 0. Good value for the platform - is guessed, but don't expect it to be very accurate. + @see wxPropertyGridInterface::ClearSelection() */ - void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false ); + bool SelectProperty( wxPGPropArg id, bool focus = false ); /** Sets category caption background colour. @@ -772,6 +1003,11 @@ public: */ void SetMarginColour(const wxColour& col); + /** + Set entire new selection from given list of properties. + */ + void SetSelection( const wxArrayPGProperty& newSelection ); + /** Sets selection background colour - applies to selected property name background. @@ -783,6 +1019,33 @@ public: */ void SetSelectionTextColour(const wxColour& col); + + /** + Sets the property sorting function. + + @param sortFunction + The sorting function to be used. It should return a value greater + than 0 if position of p1 is after p2. So, for instance, when + comparing property names, you can use following implementation: + + @code + int MyPropertySortFunction(wxPropertyGrid* propGrid, + wxPGProperty* p1, + wxPGProperty* p2) + { + return p1->GetBaseName().compare( p2->GetBaseName() ); + } + @endcode + + @remarks + Default property sort function sorts properties by their labels + (case-insensitively). + + @see GetSortFunction, wxPropertyGridInterface::Sort, + wxPropertyGridInterface::SortChildren + */ + void SetSortFunction( wxPGSortCallback sortFunction ); + /** Sets x coordinate of the splitter. @@ -802,6 +1065,19 @@ public: */ void SetSplitterLeft( bool privateChildrenToo = false ); + /** + Sets appearance of value cells representing an unspecified property + value. Default appearance is blank. + + @remarks If you set the unspecified value to have any + textual representation, then that will override + "InlineHelp" attribute. + + @see wxPGProperty::SetValueToUnspecified(), + wxPGProperty::IsValueUnspecified() + */ + void SetUnspecifiedValueAppearance( const wxPGCell& cell ); + /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font height. Value of 2 should be default on most platforms. @@ -809,27 +1085,102 @@ public: void SetVerticalSpacing( int vspacing ); /** - Shows an brief error message that is related to a property. + @name wxPropertyGrid customization + + Reimplement these member functions in derived class for better + control over wxPropertyGrid behaviour. */ - void ShowPropertyError( wxPGPropArg id, const wxString& msg ); + //@{ /** - Sorts all items at all levels (except private children). + Override in derived class to display error messages in custom manner + (these message usually only result from validation failure). - @remarks This functions deselects selected property, if any. Validation - failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. - selection is cleared even if editor had invalid value. + @remarks If you implement this, then you also need to implement + DoHidePropertyError() - possibly to do nothing, if error + does not need hiding (e.g. it was logged or shown in a + message box). + + @see DoHidePropertyError() */ - void Sort(); + virtual void DoShowPropertyError( wxPGProperty* property, + const wxString& msg ); /** - Sorts children of a property. + Override in derived class to hide an error displayed by + DoShowPropertyError(). - @remarks This functions deselects selected property, if any. Validation - failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. - selection is cleared even if editor had invalid value. + @see DoShowPropertyError() + */ + virtual void DoHidePropertyError( wxPGProperty* property ); + + /** + Return wxStatusBar that is used by this wxPropertyGrid. You can + reimplement this member function in derived class to override + the default behaviour of using the top-level wxFrame's status + bar, if any. + */ + virtual wxStatusBar* GetStatusBar(); + + //@} + + /** + @name Property development functions + + These member functions are usually only called when creating custom + user properties. + */ + //@{ + + /** + Call when editor widget's contents is modified. For example, this is + called when changes text in wxTextCtrl (used in wxStringProperty and + wxIntProperty). + + @remarks This function should only be called by custom properties. + + @see wxPGProperty::OnEvent() + */ + void EditorsValueWasModified(); + + /** + Reverse of EditorsValueWasModified(). + + @remarks This function should only be called by custom properties. + */ + void EditorsValueWasNotModified(); + + /** + Returns most up-to-date value of selected property. This will return + value different from GetSelectedProperty()->GetValue() only when text + editor is activate and string edited by user represents valid, + uncommitted property value. */ - void SortChildren( wxPGPropArg id ); + wxVariant GetUncommittedPropertyValue(); + + /** + Returns true if editor's value was marked modified. + */ + bool IsEditorsValueModified() const; + + /** + Shows an brief error message that is related to a property. + */ + void ShowPropertyError( wxPGPropArg id, const wxString& msg ); + + /** + You can use this member function, for instance, to detect in + wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was + already called in wxPGEditor::OnEvent(). It really only detects + if was value was changed using wxPGProperty::SetValueInEvent(), which + is usually used when a 'picker' dialog is displayed. If value was + written by "normal means" in wxPGProperty::StringToValue() or + IntToValue(), then this function will return false (on the other hand, + wxPGProperty::OnEvent() is not even called in those cases). + */ + bool WasValueChangedInEvent() const; + + //@} }; @@ -860,8 +1211,12 @@ public: */ bool CanVeto() const; - /** Copyer. */ - virtual wxEvent* Clone() const; + /** + Returns the column index associated with this event. + For the column dragging events, it is the column to the left + of the splitter being dragged + */ + unsigned int GetColumn() const; /** Returns highest level non-category, non-root parent of property for @@ -875,6 +1230,11 @@ public: /** Returns property associated with this event. + + @remarks You should assume that this property can always be NULL. + For instance, @c wxEVT_PG_SELECTED is emitted not only when + a new property is selected, but also when selection is + cleared by user activity. */ wxPGProperty* GetProperty() const; @@ -884,9 +1244,30 @@ public: wxPGVFBFlags GetValidationFailureBehavior() const; /** - Returns value that is about to be set for wxEVT_PG_CHANGING. + Returns name of the associated property. + + @remarks Property name is stored in event, so it remains + accessible even after the associated property or + the property grid has been deleted. + */ + wxString GetPropertyName() const; + + /** + Returns value of the associated property. Works for all event + types, but for @c wxEVT_PG_CHANGING this member function returns + the value that is pending, so you can call Veto() if the + value is not satisfactory. + + @remarks Property value is stored in event, so it remains + accessible even after the associated property or + the property grid has been deleted. + */ + wxVariant GetPropertyValue() const + + /** + @see GetPropertyValue() */ - const wxVariant& GetValue() const; + wxVariant GetValue() const; /** Set if event can be vetoed. @@ -897,8 +1278,8 @@ public: void SetProperty( wxPGProperty* p ); /** - Set override validation failure behavior. Only effective if Veto() was - also called, and only allowed if event type is wxEVT_PG_CHANGING. + Set override validation failure behaviour. Only effective if Veto() was + also called, and only allowed if event type is @c wxEVT_PG_CHANGING. */ void SetValidationFailureBehavior( wxPGVFBFlags flags ); @@ -913,7 +1294,7 @@ public: signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto() returns true. - @remarks Currently only wxEVT_PG_CHANGING supports vetoing. + @remarks Currently only @c wxEVT_PG_CHANGING supports vetoing. */ void Veto( bool veto = true );