X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/68174df30e9dd2dc0d3b257cb2218d01f80630d4..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/propgrid/propgrid.h?ds=sidebyside diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h index c9bc3dfc0a..bfda113baf 100644 --- a/interface/wx/propgrid/propgrid.h +++ b/interface/wx/propgrid/propgrid.h @@ -2,8 +2,7 @@ // Name: propgrid.h // Purpose: interface of wxPropertyGrid // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -45,7 +44,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, @@ -209,7 +208,7 @@ wxPG_EX_TOOLBAR_SEPARATOR = 0x08000000 // ----------------------------------------------------------------------- /** - @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags + @section propgrid_vfbflags wxPropertyGrid Validation Failure behaviour Flags @{ */ @@ -218,7 +217,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, @@ -233,14 +232,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, }; /** @} @@ -258,7 +278,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(); @@ -273,7 +293,7 @@ public: */ wxVariant& GetValue(); - /** Set validation failure behavior + /** Set validation failure behaviour @param failureBehavior Mixture of @ref propgrid_vfbflags. @@ -299,11 +319,32 @@ 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 }; @@ -359,50 +400,53 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid, @beginEventEmissionTable{wxPropertyGridEvent} @event{EVT_PG_SELECTED (id, func)} - Respond to wxEVT_PG_SELECTED event, generated when a property selection + 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 wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to - begin editing a property label. You can veto this event to prevent the - action. + 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 wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to - end editing of a property label. You can veto this event to prevent the - action. + 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 wxEVT_PG_COL_BEGIN_DRAG event, generated when user + 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 wxEVT_PG_COL_DRAGGING, event, generated when a + 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 wxEVT_PG_COL_END_DRAG event, generated after column + Respond to @c wxEVT_PG_COL_END_DRAG event, generated after column resize by user has finished. @endEventTable @@ -413,9 +457,11 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid, @library{wxpropgrid} @category{propgrid} - @appearance{propertygrid.png} + @appearance{propertygrid} */ -class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface +class wxPropertyGrid : public wxControl, + public wxScrollHelper, + public wxPropertyGridInterface { public: /** @@ -426,7 +472,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. */ @@ -434,7 +480,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(); @@ -442,6 +488,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 @@ -488,7 +543,7 @@ public: @see EndLabelEdit(), MakeColumnEditable() */ - void BeginLabelEdit( unsigned int column = 0 ); + void BeginLabelEdit( unsigned int colIndex = 0 ); /** Changes value of a property, as if from an editor. Use this instead of @@ -500,11 +555,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. @@ -521,7 +578,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. @@ -539,7 +596,17 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxPG_DEFAULT_STYLE, - const wxChar* name = wxPropertyGridNameStr ); + const wxString& name = wxPropertyGridNameStr ); + + /** + Dedicates a specific keycode to wxPropertyGrid. This means that such + key presses will not be redirected to editor controls. + + Using this function allows, for example, navigation between + properties using arrow keys even when the focus is in the editor + control. + */ + void DedicateKey( int keycode ); /** Enables or disables (shows/hides) categories according to parameter @@ -732,7 +799,7 @@ public: /** 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 @@ -740,6 +807,13 @@ public: */ wxTextCtrl* GetEditorTextCtrl() const; + /** + Returns current appearance of unspecified value cells. + + @see SetUnspecifiedValueAppearance() + */ + const wxPGCell& GetUnspecifiedValueAppearance() const; + /** Returns (visual) text representation of the unspecified property value. @@ -758,7 +832,7 @@ public: @param pt Coordinates in the virtual grid space. You may need to use - wxScrolledWindow::CalcScrolledPosition() for translating + wxScrolled::CalcScrolledPosition() for translating wxPropertyGrid client coordinates into something this member function can use. */ @@ -783,6 +857,8 @@ public: /** Makes given column editable by user. + @param column + The index of the column to make editable. @param editable Using @false here will disable column from being editable. @@ -815,12 +891,16 @@ public: */ 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 ); @@ -829,6 +909,17 @@ 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. @@ -849,7 +940,7 @@ public: fails if current value in editor is not valid. @remarks In wxPropertyGrid 1.4, this member function used to generate - wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer + @c wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer does that. @remarks This clears any previous selection. @@ -858,14 +949,6 @@ public: */ bool SelectProperty( wxPGPropArg id, bool focus = false ); - /** - Changes keyboard shortcut to push the editor button. - - @remarks You can set default with keycode 0. Good value for the platform - is guessed, but don't expect it to be very accurate. - */ - void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false ); - /** Sets category caption background colour. */ @@ -981,12 +1064,64 @@ 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. */ void SetVerticalSpacing( int vspacing ); + /** + @name wxPropertyGrid customization + + Reimplement these member functions in derived class for better + control over wxPropertyGrid behaviour. + */ + //@{ + + /** + Override in derived class to display error messages in custom manner + (these message usually only result from validation failure). + + @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() + */ + virtual void DoShowPropertyError( wxPGProperty* property, + const wxString& msg ); + + /** + Override in derived class to hide an error displayed by + DoShowPropertyError(). + + @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 @@ -1094,6 +1229,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; @@ -1113,7 +1253,7 @@ public: /** Returns value of the associated property. Works for all event - types, but for wxEVT_PG_CHANGING this member function returns + 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. @@ -1137,8 +1277,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 ); @@ -1153,7 +1293,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 );