/////////////////////////////////////////////////////////////////////////////
// Name:        propgrid.h
// Purpose:     topic overview
// Author:      wxWidgets team
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**

@page overview_propgrid wxPropertyGrid Overview

@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

As seen here, wxPropertyGrid is constructed in the same way as
other wxWidgets controls:

@code

// Necessary header file
#include <wx/propgrid/propgrid.h>

...

    // Assumes code is in frame/dialog constructor

    // Construct wxPropertyGrid control
    wxPropertyGrid* pg = new wxPropertyGrid(
        this, // parent
        PGID, // id
        wxDefaultPosition, // position
        wxDefaultSize, // size
        // Here are just some of the supported window styles
        wxPG_AUTO_SORT | // Automatic sorting after items added
        wxPG_SPLITTER_AUTO_CENTER | // Automatically center splitter until user manually adjusts it
        // Default style
        wxPG_DEFAULT_STYLE );

    // Window style flags are at premium, so some less often needed ones are
    // available as extra window styles (wxPG_EX_xxx) which must be set using
    // SetExtraStyle member function. wxPG_EX_HELP_AS_TOOLTIPS, for instance,
    // allows displaying help strings as tool tips.
    pg->SetExtraStyle( wxPG_EX_HELP_AS_TOOLTIPS );

@endcode

  (for complete list of new window styles, see @ref propgrid_window_styles)

  wxPropertyGrid is usually populated with lines like this:

@code
    pg->Append( new wxStringProperty("Label", "Name", "Initial Value") );
@endcode

Naturally, wxStringProperty is a property class. Only the first function argument (label)
is mandatory. Second one, name, defaults to label and, third, the initial value, to
default value. If constant wxPG_LABEL is used as the name argument, then the label is
automatically used as a name as well (this is more efficient than manually defining both
as the same). Use of empty name is discouraged and will sometimes result in run-time error.
Note that all property class constructors have quite similar constructor argument list.

To demonstrate other common property classes, here's another code snippet:

@code

    // Add int property
    pg->Append( new wxIntProperty("IntProperty", wxPG_LABEL, 12345678) );

    // Add float property (value type is actually double)
    pg->Append( new wxFloatProperty("FloatProperty", wxPG_LABEL, 12345.678) );

    // Add a bool property
    pg->Append( new wxBoolProperty("BoolProperty", wxPG_LABEL, false) );

    // A string property that can be edited in a separate editor dialog.
    pg->Append( new wxLongStringProperty("LongStringProperty",
                                         wxPG_LABEL,
                                         "This is much longer string than the "
                                         "first one. Edit it by clicking the button."));

    // String editor with dir selector button.
    pg->Append( new wxDirProperty("DirProperty", wxPG_LABEL, ::wxGetUserHome()) );

    // wxArrayStringProperty embeds a wxArrayString.
    pg->Append( new wxArrayStringProperty("Label of ArrayStringProperty",
                                          "NameOfArrayStringProp"));

    // A file selector property.
    pg->Append( new wxFileProperty("FileProperty", wxPG_LABEL, wxEmptyString) );

    // Extra: set wild card for file property (format same as in wxFileDialog).
    pg->SetPropertyAttribute( "FileProperty",
                              wxPG_FILE_WILDCARD,
                              "All files (*.*)|*.*" );

@endcode

  Operations on properties are usually done by directly calling wxPGProperty's
or wxPropertyGridInterface's member functions. wxPropertyGridInterface is an
abstract base class for property containers such as wxPropertyGrid,
wxPropertyGridManager, and wxPropertyGridPage. Note however that wxPGProperty's
member functions generally do not refresh the grid.

  wxPropertyGridInterface's property operation member functions , such as
SetPropertyValue() and DisableProperty(), all accept a special wxPGPropArg id
argument, using which you can refer to properties either by their pointer
(for performance) or by their name (for convenience). For instance:

@code
    // Add a file selector property.
    wxPGProperty* prop = pg->Append( new wxFileProperty("FileProperty",
                                     wxPG_LABEL,
                                     wxEmptyString) );

    // Valid: Set wild card by name
    pg->SetPropertyAttribute( "FileProperty",
                              wxPG_FILE_WILDCARD,
                              "All files (*.*)|*.*" );

    // Also Valid: Set wild card by property pointer
    pg->SetPropertyAttribute( prop,
                              wxPG_FILE_WILDCARD,
                              "All files (*.*)|*.*" );
@endcode

  Using pointer is faster, since it doesn't require hash map lookup. Anyway,
you can always get property pointer (wxPGProperty*) as return value from Append()
or Insert(), or by calling wxPropertyGridInterface::GetPropertyByName() or
just plain GetProperty().

@section propgrid_categories Categories

  wxPropertyGrid has a hierarchic property storage and display model, which
allows property categories to hold child properties and even other
categories. Other than that, from the programmer's point of view, categories
can be treated exactly the same as "other" properties. For example, despite
its name, GetPropertyByName() also returns a category by name. Note however
that sometimes the label of a property category may be referred as caption
(for example, there is wxPropertyGrid::SetCaptionTextColour() method
that sets text colour of property category labels).

  When category is added at the top (i.e. root) level of the hierarchy,
it becomes a *current category*. This means that all other (non-category)
properties after it are automatically appended to it. You may add
properties to specific categories by using wxPropertyGridInterface::Insert
or wxPropertyGridInterface::AppendIn.

  Category code sample:

@code

    // One way to add category (similar to how other properties are added)
    pg->Append( new wxPropertyCategory("Main") );

    // All these are added to "Main" category
    pg->Append( new wxStringProperty("Name") );
    pg->Append( new wxIntProperty("Age",wxPG_LABEL,25) );
    pg->Append( new wxIntProperty("Height",wxPG_LABEL,180) );
    pg->Append( new wxIntProperty("Weight") );

    // Another one
    pg->Append( new wxPropertyCategory("Attributes") );

    // All these are added to "Attributes" category
    pg->Append( new wxIntProperty("Intelligence") );
    pg->Append( new wxIntProperty("Agility") );
    pg->Append( new wxIntProperty("Strength") );

@endcode


@section propgrid_parentprops Tree-like Property Structure

  Basically any property can have children. There are few limitations, however.

@remarks
- Names of properties with non-category, non-root parents are not stored in global
  hash map. Instead, they can be accessed with strings like "Parent.Child".
  For instance, in the sample below, child property named "Max. Speed (mph)"
  can be accessed by global name "Car.Speeds.Max Speed (mph)".
- If you want to property's value to be a string composed of the child property values,
  you must use wxStringProperty as parent and use magic string "<composed>" as its
  value.
- Events (eg. change of value) that occur in parent do not propagate to children. Events
  that occur in children will propagate to parents, but only if they are wxStringProperties
  with "<composed>" value.

Sample:

@code
    wxPGProperty* carProp = pg->Append(new wxStringProperty("Car",
                                         wxPG_LABEL,
                                         "<composed>"));

    pg->AppendIn(carProp, new wxStringProperty("Model",
                                                wxPG_LABEL,
                                                "Lamborghini Diablo SV"));

    pg->AppendIn(carProp, new wxIntProperty("Engine Size (cc)",
                                            wxPG_LABEL,
                                            5707) );

    wxPGProperty* speedsProp = pg->AppendIn(carProp,
                                            new wxStringProperty("Speeds",
                                              wxPG_LABEL,
                                              "<composed>"));

    pg->AppendIn( speedsProp, new wxIntProperty("Max. Speed (mph)",
                                                wxPG_LABEL,290) );
    pg->AppendIn( speedsProp, new wxFloatProperty("0-100 mph (sec)",
                                                  wxPG_LABEL,3.9) );
    pg->AppendIn( speedsProp, new wxFloatProperty("1/4 mile (sec)",
                                                  wxPG_LABEL,8.6) );

    // This is how child property can be referred to by name
    pg->SetPropertyValue( "Car.Speeds.Max. Speed (mph)", 300 );

    pg->AppendIn(carProp, new wxIntProperty("Price ($)",
                                            wxPG_LABEL,
                                            300000) );

    // Displayed value of "Car" property is now very close to this:
    // "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"

@endcode

@section propgrid_enumandflags wxEnumProperty and wxFlagsProperty

  wxEnumProperty is used when you want property's (integer or string) value
to be selected from a popup list of choices.

  Creating wxEnumProperty is slightly more complex than those described
earlier. You have to provide list of constant labels, and optionally relevant
values (if label indexes are not sufficient).

@remarks

- Value wxPG_INVALID_VALUE (equals INT_MAX) is not allowed as list
  item value.

A very simple example:

@code

    //
    // Using wxArrayString
    //
    wxArrayString arrDiet;
    arr.Add("Herbivore");
    arr.Add("Carnivore");
    arr.Add("Omnivore");

    pg->Append( new wxEnumProperty("Diet",
                                   wxPG_LABEL,
                                   arrDiet) );

    //
    // Using wxChar* array
    //
    const wxChar* arrayDiet[] =
    { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };

    pg->Append( new wxEnumProperty("Diet",
                                   wxPG_LABEL,
                                   arrayDiet) );

@endcode

Here's extended example using values as well:

@code

    //
    // Using wxArrayString and wxArrayInt
    //
    wxArrayString arrDiet;
    arr.Add("Herbivore");
    arr.Add("Carnivore");
    arr.Add("Omnivore");

    wxArrayInt arrIds;
    arrIds.Add(40);
    arrIds.Add(45);
    arrIds.Add(50);

    // Note that the initial value (the last argument) is the actual value,
    // not index or anything like that. Thus, our value selects "Omnivore".
    pg->Append( new wxEnumProperty("Diet",
                                   wxPG_LABEL,
                                   arrDiet,
                                   arrIds,
                                   50));

@endcode

  wxPGChoices is a class where wxEnumProperty, and other properties which
  require storage for list of items, actually stores strings and values. It is
  used to facilitate reference counting, and therefore recommended way of
  adding items when multiple properties share the same set.

  You can use wxPGChoices directly as well, filling it and then passing it
  to the constructor. In fact, if you wish to display bitmaps next to labels,
  your best choice is to use this approach.

@code

    wxPGChoices chs;
    chs.Add("Herbivore", 40);
    chs.Add("Carnivore", 45);
    chs.Add("Omnivore", 50);

    // Let's add an item with bitmap, too
    chs.Add("None of the above", wxBitmap(), 60);

    pg->Append( new wxEnumProperty("Primary Diet",
                                   wxPG_LABEL,
                                   chs) );

    // Add same choices to another property as well - this is efficient due
    // to reference counting
    pg->Append( new wxEnumProperty("Secondary Diet",
                                   wxPG_LABEL,
                                   chs) );
@endcode

You can later change choices of property by using wxPGProperty::AddChoice(),
wxPGProperty::InsertChoice(), wxPGProperty::DeleteChoice(), and
wxPGProperty::SetChoices().

<b>wxEditEnumProperty</b> works exactly like wxEnumProperty, except
is uses non-read-only combo box as default editor, and value is stored as
string when it is not any of the choices.

wxFlagsProperty has similar construction:

@code

    const wxChar* flags_prop_labels[] = { wxT("wxICONIZE"),
        wxT("wxCAPTION"), wxT("wxMINIMIZE_BOX"), wxT("wxMAXIMIZE_BOX"), NULL };

    // this value array would be optional if values matched string indexes
    long flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX,
        wxMAXIMIZE_BOX };

    pg->Append( new wxFlagsProperty("Window Style",
                                    wxPG_LABEL,
                                    flags_prop_labels,
                                    flags_prop_values,
                                    wxDEFAULT_FRAME_STYLE) );

@endcode

wxFlagsProperty can use wxPGChoices just the same way as wxEnumProperty
<b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
you will need to use wxPGProperty::SetChoices() to replace all choices
at once - otherwise implicit child properties will not get updated properly.

@section propgrid_advprops Specialized Properties

  This section describes the use of less often needed property classes.
To use them, you have to include <wx/propgrid/advprops.h>.

@code

// Necessary extra header file
#include <wx/propgrid/advprops.h>

...

    // Date property.
    pg->Append( new wxDateProperty("MyDateProperty",
                                   wxPG_LABEL,
                                   wxDateTime::Now()) );

    // Image file property. Wild card is auto-generated from available
    // image handlers, so it is not set this time.
    pg->Append( new wxImageFileProperty("Label of ImageFileProperty",
                                        "NameOfImageFileProp") );

    // Font property has sub-properties. Note that we give window's font as
    // initial value.
    pg->Append( new wxFontProperty("Font",
                                   wxPG_LABEL,
                                   GetFont()) );

    // Colour property with arbitrary colour.
    pg->Append( new wxColourProperty("My Colour 1",
                                     wxPG_LABEL,
                                     wxColour(242,109,0) ) );

    // System colour property.
    pg->Append( new wxSystemColourProperty("My SysColour 1",
                                           wxPG_LABEL,
                                           wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );

    // System colour property with custom colour.
    pg->Append( new wxSystemColourProperty("My SysColour 2",
                                           wxPG_LABEL,
                                           wxColour(0,200,160) ) );

    // Cursor property
    pg->Append( new wxCursorProperty("My Cursor",
                                     wxPG_LABEL,
                                     wxCURSOR_ARROW));

@endcode


@section propgrid_processingvalues Processing Property Values

Properties store their values internally as wxVariant, but is also possible to
obtain them as wxAny, using implicit conversion. You can get property
values with wxPGProperty::GetValue() and
wxPropertyGridInterface::GetPropertyValue().

Below is a code example which handles wxEVT_PG_CHANGED event:

@code

void MyWindowClass::OnPropertyGridChanged(wxPropertyGridEvent& event)
{
    wxPGProperty* property = event.GetProperty();

    // Do nothing if event did not have associated property
    if ( !property )
        return;

    // GetValue() returns wxVariant, but it is converted transparently to
    // wxAny
    wxAny value = property->GetValue();

    // Also, handle the case where property value is unspecified
    if ( value.IsNull() )
        return;

    // Handle changes in values, as needed
    if ( property->GetName() == "MyStringProperty" )
        OnMyStringPropertyChanged(value.As<wxString>());
    else if ( property->GetName() == "MyColourProperty" )
        OnMyColourPropertyChanged(value.As<wxColour>());
}

@endcode

You can get a string-representation of property's value using
wxPGProperty::GetValueAsString() or
wxPropertyGridInterface::GetPropertyValueAsString(). This particular function
is very safe to use with any kind of property.

@note There is a one case in which you may want to take extra care when
      dealing with raw wxVariant values. That is, integer-type properties,
      such as wxIntProperty and wxUIntProperty, store value internally as
      wx(U)LongLong when number doesn't fit into standard long type. Using
      << operator to get wx(U)LongLong from wxVariant is customized to work
      quite safely with various types of variant data. However, you can also
      bypass this problem by using wxAny in your code instead of wxVariant.

Note that in some cases property value can be Null variant, which means
that property value is unspecified. This usually occurs only when
wxPG_EX_AUTO_UNSPECIFIED_VALUES extra window style is defined or when you
manually set property value to Null (or unspecified).


@section propgrid_iterating Iterating through a property container

You can use somewhat STL'ish iterator classes to iterate through the grid.
Here is a simple example of forward iterating through all individual
properties (not categories nor private child properties that are normally
'transparent' to application code):

@code

    wxPropertyGridIterator it;

    for ( it = pg->GetIterator();
          !it.AtEnd();
          it++ )
    {
        wxPGProperty* p = *it;
        // Do something with the property
    }

@endcode

As expected there is also a const iterator:

@code

    wxPropertyGridConstIterator it;

    for ( it = pg->GetIterator();
          !it.AtEnd();
          it++ )
    {
        const wxPGProperty* p = *it;
        // Do something with the property
    }

@endcode

You can give some arguments to GetIterator to determine which properties
get automatically filtered out. For complete list of options, see
@ref propgrid_iterator_flags. GetIterator() also accepts other arguments.
See wxPropertyGridInterface::GetIterator() for details.

This example reverse-iterates through all visible items:

@code

    wxPropertyGridIterator it;

    for ( it = pg->GetIterator(wxPG_ITERATE_VISIBLE, wxBOTTOM);
          !it.AtEnd();
          it-- )
    {
        wxPGProperty* p = *it;
        // Do something with the property
    }

@endcode

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
wxPropertyGridInterface::GetVIterator(). Note however that this virtual
iterator is limited to forward iteration.

@code

    wxPGVIterator it;

    for ( it = manager->GetVIterator(wxPG_ITERATE_ALL);
          !it.AtEnd();
          it.Next() )
    {
        wxPGProperty* p = it.GetProperty();
        // Do something with the property
    }

@endcode

@section propgrid_populating Populating wxPropertyGrid Automatically

@subsection propgrid_fromvariants Populating from List of wxVariants

Example of populating an empty wxPropertyGrid from a values stored
in an arbitrary list of wxVariants.

@code

    // This is a static method that initializes *all* built-in type handlers
    // available, including those for wxColour and wxFont. Refers to *all*
    // included properties, so when compiling with static library, this
    // method may increase the executable size noticeably.
    pg->InitAllTypeHandlers();

    // Get contents of the grid as a wxVariant list
    wxVariant all_values = pg->GetPropertyValues();

    // Populate the list with values. If a property with appropriate
    // name is not found, it is created according to the type of variant.
    pg->SetPropertyValues( my_list_variant );

@endcode

@subsection propgrid_fromfile Loading Population from a Text-based Storage

Class wxPropertyGridPopulator may be helpful when writing code that
loads properties from a text-source. In fact, the wxPropertyGrid xrc-handler
(which may not be currently included in wxWidgets, but probably will be in
near future) uses it.

@subsection editablestate Saving and Restoring User-Editable State

You can use wxPropertyGridInterface::SaveEditableState() and
wxPropertyGridInterface::RestoreEditableState() to save and restore
user-editable state (selected property, expanded/collapsed properties,
selected page, scrolled position, and splitter positions).

@section propgrid_events Event Handling

Probably the most important event is the Changed event which occurs when
value of any property is changed by the user. Use EVT_PG_CHANGED(id,func)
in your event table to use it.

For complete list of event types, see wxPropertyGrid class reference.

However, one type of event that might need focused attention is EVT_PG_CHANGING,
which occurs just prior property value is being changed by user. You can
acquire pending value using wxPropertyGridEvent::GetValue(), and if it is
not acceptable, call wxPropertyGridEvent::Veto() to prevent the value change
from taking place.

@code

void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
{
    wxPGProperty* property = event.GetProperty();

    if ( property == m_pWatchThisProperty )
    {
        // GetValue() returns the pending value, but is only
        // supported by wxEVT_PG_CHANGING.
        if ( event.GetValue().GetString() == g_pThisTextIsNotAllowed )
        {
            event.Veto();
            return;
        }
    }
}

@endcode

@remarks On Child Property Event Handling
- For properties which have private, implicit children (wxFontProperty and
  wxFlagsProperty), events occur for the main parent property only.
  For other properties events occur for the children themselves. See
  @ref propgrid_parentprops.

- When property's child gets changed, you can use wxPropertyGridEvent::GetMainParent()
  to obtain its topmost non-category parent (useful, if you have deeply nested
  properties).

@section propgrid_tooltipandhint Help String, Hint and Tool Tips

For each property you can specify two different types of help text. First,
you can use wxPropertyGridInterface::SetPropertyHelpString() or
wxPGProperty::SetHelpString() to set property's help text. Second, you
can use wxPGProperty::SetAttribute() to set property's "Hint" attribute.

Difference between hint and help string is that the hint is shown in an empty
property value cell, while help string is shown either in the description text
box, as a tool tip, or on the status bar, whichever of these is available.

To enable display of help string as tool tips, you must explicitly use
the wxPG_EX_HELP_AS_TOOLTIPS extra window style.

@section propgrid_validating Validating Property Values

There are various ways to make sure user enters only correct values. First, you
can use wxValidators similar to as you would with ordinary controls. Use
wxPropertyGridInterface::SetPropertyValidator() to assign wxValidator to
property.

Second, you can subclass a property and override wxPGProperty::ValidateValue(),
or handle wxEVT_PG_CHANGING for the same effect. Both of these ways do not
actually prevent user from temporarily entering invalid text, but they do give
you an opportunity to warn the user and block changed value from being committed
in a property.

Various validation failure options can be controlled globally with
wxPropertyGrid::SetValidationFailureBehavior(), or on an event basis by
calling wxEvent::SetValidationFailureBehavior(). Here's a code snippet of
how to handle wxEVT_PG_CHANGING, and to set custom failure behaviour and
message.

@code
    void MyFrame::OnPropertyGridChanging(wxPropertyGridEvent& event)
    {
        wxPGProperty* property = event.GetProperty();

        // You must use wxPropertyGridEvent::GetValue() to access
        // the value to be validated.
        wxVariant pendingValue = event.GetValue();

        if ( property->GetName() == "Font" )
        {
            // Make sure value is not unspecified
            if ( !pendingValue.IsNull() )
            {
                wxFont font;
                font << pendingValue;

                // Let's just allow Arial font
                if ( font.GetFaceName() != "Arial" )
                {
                    event.Veto();
                    event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
                                                       wxPG_VFB_BEEP |
                                                       wxPG_VFB_SHOW_MESSAGEBOX);
                }
            }
        }
    }
@endcode


@section propgrid_cellrender Customizing Individual Cell Appearance

You can control text colour, background colour, and attached image of
each cell in the property grid. Use wxPropertyGridInterface::SetPropertyCell() or
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 behaviour for your properties without all the necessary hassle
of sub-classing a property class etc.

@subsection propgrid_customimage Setting Value Image

Every property can have a small value image placed in front of the
actual value text. Built-in example of this can be seen with
wxColourProperty and wxImageFileProperty, but for others it can
be set using wxPropertyGrid::SetPropertyImage method.

@subsection propgrid_customeditor Setting Property's Editor Control(s)

You can set editor control (or controls, in case of a control and button),
of any property using wxPropertyGrid::SetPropertyEditor. Editors are passed
as wxPGEditor_EditorName, and valid built-in EditorNames are
TextCtrl, Choice, ComboBox, CheckBox, TextCtrlAndButton, ChoiceAndButton,
SpinCtrl, and DatePickerCtrl. Two last mentioned ones require call to
static member function wxPropertyGrid::RegisterAdditionalEditors().

Following example changes wxColourProperty's editor from default Choice
to TextCtrlAndButton. wxColourProperty has its internal event handling set
up so that button click events of the button will be used to trigger
colour selection dialog.

@code

    wxPGProperty* colProp = new wxColourProperty("Text Colour");
    pg->Append(colProp);
    pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);

@endcode

Naturally, creating and setting custom editor classes is a possibility as
well. For more information, see wxPGEditor class reference.

@subsection propgrid_editorattrs Property Attributes Recognized by Editors

<b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step" and
"Wrap" attributes.

@subsection propgrid_multiplebuttons Adding Multiple Buttons Next to an Editor

See wxPGMultiButton class reference.

@subsection propgrid_customeventhandling Handling Events Passed from Properties

<b>wxEVT_COMMAND_BUTTON_CLICKED </b>(corresponds to event table macro EVT_BUTTON):
Occurs when editor button click is not handled by the property itself
(as is the case, for example, if you set property's editor to TextCtrlAndButton
from the original TextCtrl).

@subsection propgrid_attributes Property Attributes

Miscellaneous values, often specific to a property type, can be set
using wxPropertyGridInterface::SetPropertyAttribute() and
wxPropertyGridInterface::SetPropertyAttributeAll() methods.

Attribute names are strings and values wxVariant. Arbitrary names are allowed
in order to store values that are relevant to application only and not
property grid. Constant equivalents of all attribute string names are
provided. Some of them are defined as cached strings, so using these constants
can provide for smaller binary size.

For complete list of attributes, see @ref propgrid_property_attributes.


@section propgrid_usage2 Using wxPropertyGridManager

wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
which can optionally have tool bar for mode and page selection, and a help text
box. For more information, see wxPropertyGridManager class reference.

@subsection propgrid_propgridpage wxPropertyGridPage

wxPropertyGridPage is holder of properties for one page in manager. It is derived from
wxEvtHandler, so you can subclass it to process page-specific property grid events. Hand
over your page instance in wxPropertyGridManager::AddPage().

Please note that the wxPropertyGridPage itself only sports subset of wxPropertyGrid API
(but unlike manager, this include item iteration). Naturally it inherits from
wxPropertyGridInterface.

For more information, see wxPropertyGridPage class reference.


@section propgrid_subclassing Sub-classing wxPropertyGrid and wxPropertyGridManager

Few things to note:

- Only a small percentage of member functions are virtual. If you need more,
  just e-mail to wx-dev mailing list.

- Data manipulation is done in wxPropertyGridPageState class. So, instead of
  overriding wxPropertyGrid::Insert(), you'll probably want to override
  wxPropertyGridPageState::DoInsert(). See header file for details.

- Override wxPropertyGrid::CreateState() to instantiate your derivate
  wxPropertyGridPageState. For wxPropertyGridManager, you'll need to subclass
  wxPropertyGridPage instead (since it is derived from wxPropertyGridPageState),
  and hand over instances in wxPropertyGridManager::AddPage() calls.

- You can use a derivate wxPropertyGrid with manager by overriding
  wxPropertyGridManager::CreatePropertyGrid() member function.


@section propgrid_misc Miscellaneous Topics

@subsection propgrid_namescope Property Name Scope

  All properties which parent is category or root can be accessed
directly by their base name (ie. name given for property in its constructor).
Other properties can be accessed via "ParentsName.BaseName" notation,
Naturally, all property names should be unique.

@subsection propgrid_nonuniquelabels Non-unique Labels

  It is possible to have properties with identical label under same parent.
However, care must be taken to ensure that each property still has
unique (base) name.

@subsection propgrid_boolproperty wxBoolProperty

  There are few points about wxBoolProperty that require further discussion:
  - wxBoolProperty can be shown as either normal combo box or as a check box.
    Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this.
    For example, if you have a wxFlagsProperty, you can
    set its all items to use check box using the following:
    @code
        pg->SetPropertyAttribute("MyFlagsProperty", wxPG_BOOL_USE_CHECKBOX, true, wxPG_RECURSE);
    @endcode

    Following will set all individual bool properties in your control to
    use check box:

    @code
        pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
    @endcode

  - Default item names for wxBoolProperty are ["False", "True"]. This can be
    changed using static function wxPropertyGrid::SetBoolChoices(trueChoice,
    falseChoice).

@subsection propgrid_textctrlupdates Updates from wxTextCtrl Based Editor

  Changes from wxTextCtrl based property editors are committed (ie.
wxEVT_PG_CHANGED is sent etc.) *only* when (1) user presser enter, (2)
user moves to edit another property, or (3) when focus leaves
the grid.

  Because of this, you may find it useful, in some apps, to call
wxPropertyGrid::CommitChangesFromEditor() just before you need to do any
computations based on property grid values. Note that CommitChangesFromEditor()
will dispatch wxEVT_PG_CHANGED with ProcessEvent, so any of your event handlers
will be called immediately.

@subsection propgrid_splittercentering Centering the Splitter

  If you need to center the splitter, but only once when the program starts,
then do <b>not</b> use the wxPG_SPLITTER_AUTO_CENTER window style, but the
wxPropertyGrid::CenterSplitter() method. <b>However, be sure to call it after
the sizer setup and SetSize calls!</b> (ie. usually at the end of the
frame/dialog constructor)

  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.

@subsection propgrid_splittersetting Setting Splitter Position When Creating Property Grid

Splitter position cannot exceed grid size, and therefore setting it during
form creation may fail as initial grid size is often smaller than desired
splitter position, especially when sizers are being used.

@subsection propgrid_colourproperty wxColourProperty and wxSystemColourProperty

Through sub-classing, these two property classes provide substantial customization
features. Subclass wxSystemColourProperty if you want to use wxColourPropertyValue
(which features colour type in addition to wxColour), and wxColourProperty if plain
wxColour is enough.

Override wxSystemColourProperty::ColourToString() to redefine how colours are
printed as strings.

Override wxSystemColourProperty::GetCustomColourIndex() to redefine location of
the item that triggers colour picker dialog (default is last).

Override wxSystemColourProperty::GetColour() to determine which colour matches
which choice entry.

@section propgrid_proplist Property Class Descriptions

See @ref pgproperty_properties

@section propgrid_compat Changes from wxPropertyGrid 1.4

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 behaviour-breaking changes should not compile or run
without warnings or errors.

@subsection propgrid_compat_general General Changes

  - Tab-traversal can no longer be used to travel between properties. Now
    it only causes focus to move from main grid to editor of selected property.
    Arrow keys are now your primary means of navigating between properties,
    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 behaviour.

  - wxPGChoices::SetExclusive() was renamed to AllocExclusive().

  - wxPGProperty::SetPropertyChoicesExclusive() was removed. Instead, use
    GetChoices().AllocExclusive().

  - wxPGProperty::ClearModifiedStatus() is removed. Please use
    SetModifiedStatus() instead.

  - wxPropertyGridInterface::GetExpandedProperties() is removed. You should
    now use wxPropertyGridInterface::GetEditableState() instead.

  - wxPG_EX_DISABLE_TLP_TRACKING is now enabled by default. To get the old
    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).

  - wxPGProperty::GetCell() now returns a reference. AcquireCell() was removed.

  - wxPGMultiButton::FinalizePosition() has been renamed to Finalize(),
    and it has slightly different argument list.

  - wxPropertyGridEvent::HasProperty() is removed. You can use GetProperty()
    as immediate replacement when checking if event has a property.

  - "InlineHelp" property has been replaced with "Hint".

  - 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.

  - Implement wxPGProperty::ValueToString() instead of GetValueAsString().

  - wxPGProperty::ChildChanged() must now return the modified value of
    whole property instead of writing it back into 'thisValue' argument.

  - Removed wxPropertyGrid::PrepareValueForDialogEditing(). Use
    wxPropertyGrid::GetPendingEditedValue() instead.

  - wxPGProperty::GetChoiceInfo() is removed, as all properties now carry
    wxPGChoices instance (protected wxPGProperty::m_choices).

  - Connect() should no longer be called in implementations of
    wxPGEditor::CreateControls(). wxPropertyGrid automatically passes all
    events from editor to wxPGEditor::OnEvent() and wxPGProperty::OnEvent(),
    as appropriate.

  - wxPython: Previously some of the reimplemented member functions needed a
    'Py' prefix. This is no longer necessary. For instance, if you previously
    implemented PyStringToValue() for your custom property, you should now
    just implement StringToValue().
*/