// Name: propgrid.h
// Purpose: topic overview
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@page overview_propgrid wxPropertyGrid Overview
-Key Classes:
-@li wxPGProperty
-@li wxPropertyGrid
-@li wxPropertyGridEvent
-@li wxPropertyGridManager
-@li wxPropertyGridPage
-
- 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,
-add more than two columns, and set arbitrary per-property attributes.
-
- As this version of wxPropertyGrid has some backward-incompatible changes
-from version 1.4, everybody who need to maintain custom property classes
-should carefully read final section in @ref propgrid_compat.
-
-@li @ref propgrid_basics
-@li @ref propgrid_categories
-@li @ref propgrid_parentprops
-@li @ref propgrid_enumandflags
-@li @ref propgrid_advprops
-@li @ref propgrid_processingvalues
-@li @ref propgrid_iterating
-@li @ref propgrid_events
-@li @ref propgrid_tooltipandhint
-@li @ref propgrid_validating
-@li @ref propgrid_populating
-@li @ref propgrid_cellrender
-@li @ref propgrid_customizing
-@li @ref propgrid_usage2
-@li @ref propgrid_subclassing
-@li @ref propgrid_misc
-@li @ref propgrid_proplist
-@li @ref propgrid_compat
+@tableofcontents
+
+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, add more
+than two columns, and set arbitrary per-property attributes.
+
+As this version of wxPropertyGrid has some backward-incompatible changes from
+version 1.4, everybody who need to maintain custom property classes should
+carefully read final section in @ref propgrid_compat.
+
+@see wxPropertyGrid, wxPropertyGridEvent, wxPropertyGridManager,
+ wxPropertyGridPage, wxPGProperty
+
+
@section propgrid_basics Creating and Populating wxPropertyGrid
@code
// Add a file selector property.
- wxPGPropety* prop = pg->Append( new wxFileProperty("FileProperty",
- wxPG_LABEL,
- wxEmptyString) );
+ wxPGProperty* prop = pg->Append( new wxFileProperty("FileProperty",
+ wxPG_LABEL,
+ wxEmptyString) );
// Valid: Set wild card by name
pg->SetPropertyAttribute( "FileProperty",
return;
// Handle changes in values, as needed
- if ( property.GetName() == "MyStringProperty" )
+ if ( property->GetName() == "MyStringProperty" )
OnMyStringPropertyChanged(value.As<wxString>());
- else if ( property.GetName() == "MyColourProperty" )
+ else if ( property->GetName() == "MyColourProperty" )
OnMyColourPropertyChanged(value.As<wxColour>());
}
@endcode
-@beginWxPythonOnly
-PropertyGridInterface has some useful pythonic iterators as attributes.
-@c Properties lets you iterate through all items that are not category
-captions or private children. @c Items lets you iterate through everything
-except private children. Also, there are GetPyIterator() and GetPyVIterator(),
-which return pythonic iterators instead of normal wxPropertyGridIterator.
-
-If you need to use C++ style iterators in wxPython code, note that
-Instead of ++ operator, use Next() method, and instead of
-* operator, use GetProperty() method.
-@endWxPythonOnly
-
GetIterator() only works with wxPropertyGrid and the individual pages
of wxPropertyGridManager. In order to iterate through an arbitrary
property container (such as entire wxPropertyGridManager), you need to use
wxPGVIterator it;
- for ( it = manager->GetVIterator();
+ for ( it = manager->GetVIterator(wxPG_ITERATE_ALL);
!it.AtEnd();
it.Next() )
{
event.Veto();
event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
wxPG_VFB_BEEP |
- wxPG_VFB_SHOW_MESSAGE);
+ wxPG_VFB_SHOW_MESSAGEBOX);
}
}
}
In addition, it is possible to control these characteristics for
wxPGChoices list items. See wxPGChoices class reference for more info.
+@section propgrid_keyhandling Customizing Keyboard Handling
+
+There is probably one preference for keyboard handling for every developer
+out there, and as a conveniency control wxPropertyGrid tries to cater for
+that. By the default arrow keys are used for navigating between properties,
+and TAB key is used to move focus between the property editor and the
+first column. When the focus is in the editor, arrow keys usually no longer
+work for navigation since they are consumed by the editor.
+
+There are mainly two functions which you can use this customize things,
+wxPropertyGrid::AddActionTrigger() and wxPropertyGrid::DedicateKey().
+First one can be used to set a navigation event to occur on a specific key
+press and the second is used to divert a key from property editors, making it
+possible for the grid to use keys normally consumed by the focused editors.
+
+For example, let's say you want to have an ENTER-based editing scheme. That
+is, editor is focused on ENTER press and the next property is selected when
+the user finishes editing and presses ENTER again. Code like this would
+accomplish the task:
+
+@code
+ // Have property editor focus on Enter
+ propgrid->AddActionTrigger( wxPG_ACTION_EDIT, WXK_RETURN );
+
+ // Have Enter work as action trigger even when editor is focused
+ propgrid->DedicateKey( WXK_RETURN );
+
+ // Let Enter also navigate to the next property
+ propgrid->AddActionTrigger( wxPG_ACTION_NEXT_PROPERTY, WXK_RETURN );
+
+@endcode
+
+wxPG_ACTION_EDIT is prioritized above wxPG_ACTION_NEXT_PROPERTY so that the
+above code can work without conflicts. For a complete list of available
+actions, see @ref propgrid_keyboard_actions.
+
+Here's another trick. Normally the up and down cursor keys are consumed by
+the focused wxTextCtrl editor and as such can't be used for navigating between
+properties when that editor is focused. However, using DedicateKey() we can
+change this so that instead of the cursor keys moving the caret inside the
+wxTextCtrl, they navigate between adjacent properties. As such:
+
+@code
+ propgrid->DedicateKey(WXK_UP);
+ propgrid->DedicateKey(WXK_DOWN);
+@endcode
+
@section propgrid_customizing Customizing Properties (without sub-classing)
In this section are presented miscellaneous ways to have custom appearance
-and behavior for your properties without all the necessary hassle
+and behaviour for your properties without all the necessary hassle
of sub-classing a property class etc.
@subsection propgrid_customimage Setting Value Image
the sizer setup and SetSize calls!</b> (ie. usually at the end of the
frame/dialog constructor)
- Splitter centering behavior can be customized using
+ Splitter centering behaviour can be customized using
wxPropertyGridInterface::SetColumnProportion(). Usually it is used to set
non-equal column proportions, which in essence stops the splitter(s) from
being 'centered' as such, and instead just auto-resized.
incompatible changes from version 1.4, which had a stable API and will remain
as the last separate branch.
-Note that in general any behavior-breaking changes should not compile or run
+Note that in general any behaviour-breaking changes should not compile or run
without warnings or errors.
@subsection propgrid_compat_general General Changes
with keyboard. This change allowed fixing broken tab traversal on wxGTK
(which is open issue in wxPropertyGrid 1.4).
+ - wxPG_EX_UNFOCUS_ON_ENTER style is removed and is now default behaviour.
+ That is, when enter is pressed, editing is considered done and focus
+ moves back to the property grid from the editor control.
+
- A few member functions were removed from wxPropertyGridInterface.
Please use wxPGProperty's counterparts from now on.
- - wxPGChoices now has proper Copy-On-Write behavior.
+ - wxPGChoices now has proper Copy-On-Write behaviour.
- wxPGChoices::SetExclusive() was renamed to AllocExclusive().
now use wxPropertyGridInterface::GetEditableState() instead.
- wxPG_EX_DISABLE_TLP_TRACKING is now enabled by default. To get the old
- behavior (recommended if you don't use a system that reparents the grid
+ behaviour (recommended if you don't use a system that reparents the grid
on its own), use the wxPG_EX_ENABLE_TLP_TRACKING extra style.
- Extended window style wxPG_EX_LEGACY_VALIDATORS was removed.
+ - Default property validation failure behaviour has been changed to
+ (wxPG_VFB_MARK_CELL | wxPG_VFB_SHOW_MESSAGEBOX), which means that the
+ cell is marked red and wxMessageBox is shown. This is more user-friendly
+ than the old behaviour, which simply beeped and prevented leaving the
+ property editor until a valid value was entered.
+
- wxPropertyGridManager now has same Get/SetSelection() semantics as
wxPropertyGrid.
- Various wxPropertyGridManager page-related functions now return pointer
to the page object instead of index.
+ - wxArrayEditorDialog used by wxArrayStringProperty and some sample
+ properties has been renamed to wxPGArrayEditorDialog. Also, it now uses
+ wxEditableListBox for editing.
+
- Instead of calling wxPropertyGrid::SetButtonShortcut(), use
wxPropertyGrid::SetActionTrigger(wxPG_ACTION_PRESS_BUTTON).
- wxPropertyGrid::CanClose() has been removed. Call
wxPropertyGridInterface::EditorValidate() instead.
+ - wxPGProperty::SetFlag() has been moved to private API. This was done to
+ underline the fact that it was not the preferred method to change a
+ property's state since it never had any desired side-effects. ChangeFlag()
+ still exists for those who really need to achieve the same effect.
+
+ - wxArrayStringProperty default delimiter is now comma (','), and it can
+ be changed by setting the new "Delimiter" attribute.
+
@subsection propgrid_compat_propdev Property and Editor Sub-classing Changes
- Confusing custom property macros have been eliminated.
projects / wxWidgets.git / blobdiff