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
};
/**
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)
/** @}
*/
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()
@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
*/
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,
*/
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
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.
*/
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.
*/
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.
*/
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.
*/
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;
*/
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.
*/
*/
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).
@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 );
*/
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.
*/
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;
+
+ //@}
};
projects / wxWidgets.git / blobdiff