// Name: propgrid.h
// Purpose: interface of wxPropertyGrid
// Author: wxWidgets team
-// RCS-ID: $Id:
+// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
*/
wxPG_HIDE_CATEGORIES = 0x00000020,
-/*
+/**
This style combines non-categoric mode and automatic sorting.
*/
wxPG_ALPHABETIC_MODE = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
*/
wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES = 0x00400000,
-/**
- With this style Validators on properties will work same as in wxPropertyGrid
- 1.2.
-*/
-wxPG_EX_LEGACY_VALIDATORS = 0x00800000,
-
/**
Hides page selection buttons from tool bar.
*/
typedef wxByte wxPGVFBFlags;
+/**
+ wxPGValidationInfo
+
+ Used to convey validation information to and from functions that
+ actually perform validation. Mostly used in custom property classes.
+*/
+class wxPGValidationInfo
+{
+public:
+ /**
+ @return Returns failure behavior which is a combination of
+ @ref propgrid_vfbflags.
+ */
+ wxPGVFBFlags GetFailureBehavior();
+
+ /**
+ Returns current failure message.
+ */
+ const wxString& GetFailureMessage() const;
+
+ /**
+ Returns reference to pending value.
+ */
+ const wxVariant& GetValue() const;
+
+ /** Set validation failure behavior
+
+ @param failureBehavior
+ Mixture of @ref propgrid_vfbflags.
+ */
+ void SetFailureBehavior(wxPGVFBFlags failureBehavior);
+
+ /**
+ Set current failure message.
+ */
+ void SetFailureMessage(const wxString& message);
+};
+
// -----------------------------------------------------------------------
/**
@section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
+
These are used with wxPropertyGrid::AddActionTrigger() and
wxPropertyGrid::ClearActionTriggers().
@{
wxPG_ACTION_EXPAND_PROPERTY,
wxPG_ACTION_COLLAPSE_PROPERTY,
wxPG_ACTION_CANCEL_EDIT,
- wxPG_ACTION_CUT,
- wxPG_ACTION_COPY,
- wxPG_ACTION_PASTE,
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);
+
// -----------------------------------------------------------------------
-/** @class wxPropertyGrid
+/**
+ @class wxPropertyGrid
- wxPropertyGrid is a specialized grid for editing properties - in other
+ wxPropertyGrid is a specialized grid for editing properties - in other
words name = value pairs. List of ready-to-use property classes include
strings, numbers, flag sets, fonts, colours and many others. It is possible,
for example, to categorize properties, set up a complete tree-hierarchy,
@endEventTable
@remarks
-
- - Use Freeze() and Thaw() respectively to disable and enable drawing. This
- will also delay sorting etc. miscellaneous calculations to the last
- possible moment.
+ Use Freeze() and Thaw() respectively to disable and enable drawing.
+ This will also delay sorting etc. miscellaneous calculations to the last
+ possible moment.
@library{wxpropgrid}
@category{propgrid}
+ @appearance{propertygrid.png}
*/
class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
{
public:
-
- /**
- Two step constructor. Call Create when this constructor is called to
- build up the wxPropertyGrid
- */
+ /**
+ Two step constructor.
+ Call Create() when this constructor is called to build up the wxPropertyGrid
+ */
wxPropertyGrid();
/**
- Constructor. The styles to be used are styles valid for
- the wxWindow and wxScrolledWindow.
+ Constructor.
+ The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
@see @ref propgrid_window_styles.
*/
wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
- const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = wxPG_DEFAULT_STYLE,
- const wxChar* name = wxPropertyGridNameStr );
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ long style = wxPG_DEFAULT_STYLE,
+ const wxChar* name = wxPropertyGridNameStr );
/** Destructor */
virtual ~wxPropertyGrid();
@param action
Which action to trigger. See @ref propgrid_keyboard_actions.
-
@param keycode
Which keycode triggers the action.
-
@param modifiers
Which key event modifiers, in addition to keycode, are needed to
trigger the action.
@see @ref propgrid_window_styles.
*/
bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
- const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = wxPG_DEFAULT_STYLE,
- const wxChar* name = wxPropertyGridNameStr );
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ long style = wxPG_DEFAULT_STYLE,
+ const wxChar* name = wxPropertyGridNameStr );
/**
Call when editor widget's contents is modified. For example, this is
@see wxPGProperty::OnEvent()
*/
- void EditorsValueWasModified() { m_iFlags |= wxPG_FL_VALUE_MODIFIED; }
+ void EditorsValueWasModified();
/**
Reverse of EditorsValueWasModified().
@remarks This function should only be called by custom properties.
*/
- void EditorsValueWasNotModified()
- {
- m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
- }
+ void EditorsValueWasNotModified();
/**
Enables or disables (shows/hides) categories according to parameter
enable.
+
+ @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.
*/
bool EnableCategories( bool enable );
/**
Returns number of columns currently on grid.
*/
- int GetColumnCount() const;
+ unsigned int GetColumnCount() const;
/**
Returns colour of empty space below properties.
wxColour GetMarginColour() const;
/**
- Returns cell background colour of a property.
- */
- wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const;
-
- /**
- Returns cell background colour of a property.
+ 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.
*/
- wxColour GetPropertyTextColour( wxPGPropArg id ) const;
+ wxVariant GetUncommittedPropertyValue();
/**
Returns "root property". It does not have name, etc. and it is not
*/
wxColour GetSelectionForegroundColour() const;
+ /**
+ Returns the property sort function (default is @NULL).
+
+ @see SetSortFunction
+ */
+ wxPGSortCallback GetSortFunction() const;
+
/**
Returns current splitter x position.
*/
/**
Returns current vertical spacing.
*/
- int GetVerticalSpacing() const { return (int)m_vspacing; }
+ int GetVerticalSpacing() const;
/**
Returns true if editor's value was marked modified.
*/
bool IsFrozen() const;
+ /**
+ Refreshes any active editor control.
+ */
+ void RefreshEditor();
+
/**
Redraws given property.
*/
void SetMarginColour(const wxColour& col);
/**
- Sets background colour of property and all its children. Colours of
- captions are not affected. Background brush cache is optimized for often
- set colours to be set last.
+ Sets selection background colour - applies to selected property name
+ background.
*/
- void SetPropertyBackgroundColour( wxPGPropArg id, const wxColour& col );
+ void SetSelectionBackgroundColour(const wxColour& col);
/**
- Resets text and background colours of given property.
+ Sets selection foreground colour - applies to selected property name text.
*/
- void SetPropertyColoursToDefault( wxPGPropArg id );
+ void SetSelectionTextColour(const wxColour& col);
+
/**
- Sets text colour of property and all its children.
- */
- void SetPropertyTextColour( wxPGPropArg id, const wxColour& col,
- bool recursively = true );
+ Sets the property sorting function.
- /** Sets selection background colour - applies to selected property name
- background. */
- void SetSelectionBackgroundColour(const wxColour& col);
+ @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:
- /** Sets selection foreground colour - applies to selected property name
- text. */
- void SetSelectionTextColour(const wxColour& col);
+ @code
+ int MyPropertySortFunction(wxPropertyGrid* propGrid,
+ wxPGProperty* p1,
+ wxPGProperty* p2)
+ {
+ return p1->GetBaseName().compare( p2->GetBaseName() );
+ }
+ @endcode
- /** Sets x coordinate of the splitter.
+ @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.
@remarks Splitter position cannot exceed grid size, and therefore setting
it during form creation may fail as initial grid size is often
*/
void SetSplitterPosition( int newxpos, int col = 0 );
- /**
- Sets name of a property.
-
- @param id
- Name or pointer of property which name to change.
-
- @param newname
- New name.
- */
- void SetPropertyName( wxPGPropArg id, const wxString& newname );
-
/**
Moves splitter as left as possible, while still allowing all
labels to be shown in full.
@param privateChildrenToo
If @false, will still allow private children to be cropped.
*/
- void SetSplitterLeft( bool privateChildrenToo = false )
- {
- m_pState->SetSplitterLeft(subProps);
- }
+ void SetSplitterLeft( bool privateChildrenToo = false );
/**
Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
Shows an brief error message that is related to a property.
*/
void ShowPropertyError( wxPGPropArg id, const wxString& msg );
-
- /**
- Sorts all items at all levels (except private children).
- */
- void Sort();
-
- /**
- Sorts children of a property.
- */
- void SortChildren( wxPGPropArg id );
};
/**
Returns true if you can veto the action that the event is signaling.
*/
- bool CanVeto() const { return m_canVeto; }
-
- /** Copyer. */
- virtual wxEvent* Clone() const;
+ bool CanVeto() const;
/**
Returns highest level non-category, non-root parent of property for
Set if event can be vetoed.
*/
void SetCanVeto( bool canVeto );
-
+
/** Changes the property associated with this event. */
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.
*/
- void SetValidationFailureBehavior( int flags );
+ void SetValidationFailureBehavior( wxPGVFBFlags flags );
/**
Sets custom failure message for this time only. Only applies if
projects / wxWidgets.git / blobdiff