X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/433969811ec21a6036347f1be157e08f8f4720ec..4017f5ca49e153e04ffd1c49bc93afd31c1cdf87:/interface/wx/propgrid/propgrid.h diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h index 16c785c43d..665674620b 100644 --- a/interface/wx/propgrid/propgrid.h +++ b/interface/wx/propgrid/propgrid.h @@ -89,7 +89,11 @@ 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 +*/ +wxPG_NO_INTERNAL_BORDER = 0x00004000 }; @@ -152,17 +156,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) /** @} */ @@ -318,10 +356,13 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid, 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 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_CHANGING(id, func)} Respond to wxEVT_PG_CHANGING event, generated when property value is about to be changed by user. Use wxPropertyGridEvent::GetValue() @@ -343,6 +384,14 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid, @event{EVT_PG_ITEM_EXPANDED(id, func)} Respond to 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. + @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. @endEventTable @remarks @@ -391,6 +440,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, @@ -400,6 +463,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 column = 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 @@ -451,24 +529,6 @@ public: long style = wxPG_DEFAULT_STYLE, const wxChar* 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). - - @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(); - /** Enables or disables (shows/hides) categories according to parameter enable. @@ -479,6 +539,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. @@ -503,6 +574,11 @@ 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. @@ -603,14 +679,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. @@ -665,13 +733,14 @@ public: */ int GetVerticalSpacing() const; - /** - Returns true if editor's value was marked modified. - */ - bool IsEditorsValueModified() const; - /** Returns information about arbitrary position in the grid. + + @param pt + Coordinates in the virtual grid space. You may need to use + wxScrolledWindow::CalcScrolledPosition() for translating + wxPropertyGrid client coordinates into something this member + function can use. */ wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const; @@ -680,12 +749,42 @@ 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() ). */ bool IsFrozen() const; + /** + Makes given column editable by user. + + @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. + + @param newTLP + New top-level parent that is about to be set. Old top-level parent + window should still exist as the current one. + + @remarks This function is automatically called from wxPropertyGrid:: + Reparent() and wxPropertyGridManager::Reparent(). You only + need to use it if you reparent wxPropertyGrid indirectly. + */ + void OnTLPChanging( wxWindow* newTLP ); + /** Refreshes any active editor control. */ @@ -710,10 +809,15 @@ public: */ void ResetColours(); + /** + 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). @@ -724,7 +828,13 @@ public: @return returns @true if selection finished successfully. Usually only fails if current value in editor is not valid. - @see wxPropertyGrid::ClearSelection() + @remarks In wxPropertyGrid 1.4, this member function used to generate + wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer + does that. + + @remarks This clears any previous selection. + + @see wxPropertyGridInterface::ClearSelection() */ bool SelectProperty( wxPGPropArg id, bool focus = false ); @@ -789,6 +899,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. @@ -852,10 +967,64 @@ public: */ void SetVerticalSpacing( int vspacing ); + + /** + @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. + */ + 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; + + //@} };