X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/863d1ce7c2736b7a1cceb56a547741ac2f3993d2..ccef4c3ad16fe5bf4365569c431f1208d79eb0ef:/docs/doxygen/overviews/propgrid.h diff --git a/docs/doxygen/overviews/propgrid.h b/docs/doxygen/overviews/propgrid.h index 75565ee9d5..97677f7f2d 100644 --- a/docs/doxygen/overviews/propgrid.h +++ b/docs/doxygen/overviews/propgrid.h @@ -2,49 +2,29 @@ // 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 @@ -144,9 +124,9 @@ argument, using which you can refer to properties either by their pointer @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", @@ -470,9 +450,9 @@ void MyWindowClass::OnPropertyGridChanged(wxPropertyGridEvent& event) return; // Handle changes in values, as needed - if ( property.GetName() == "MyStringProperty" ) + if ( property->GetName() == "MyStringProperty" ) OnMyStringPropertyChanged(value.As()); - else if ( property.GetName() == "MyColourProperty" ) + else if ( property->GetName() == "MyColourProperty" ) OnMyColourPropertyChanged(value.As()); } @@ -555,18 +535,6 @@ This example reverse-iterates through all visible items: @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 @@ -577,7 +545,7 @@ iterator is limited to forward iteration. wxPGVIterator it; - for ( it = manager->GetVIterator(); + for ( it = manager->GetVIterator(wxPG_ITERATE_ALL); !it.AtEnd(); it.Next() ) { @@ -725,7 +693,7 @@ message. event.Veto(); event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY | wxPG_VFB_BEEP | - wxPG_VFB_SHOW_MESSAGE); + wxPG_VFB_SHOW_MESSAGEBOX); } } } @@ -742,11 +710,58 @@ wxPGProperty::SetCell() for this purpose. 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 @@ -909,7 +924,7 @@ wxPropertyGrid::CenterSplitter() method. However, be sure to call it after the sizer setup and SetSize calls! (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. @@ -946,7 +961,7 @@ Version of wxPropertyGrid bundled with wxWidgets 2.9+ has various backward- 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 @@ -957,10 +972,14 @@ without warnings or errors. 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(). @@ -974,17 +993,27 @@ without warnings or errors. 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). @@ -1001,6 +1030,14 @@ without warnings or errors. - 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.