4db94043cb
Files correlati : Commento : Spostamento in libraries delle librerie esterne di Campo per una maggiore pulizia e organizzazione git-svn-id: svn://10.65.10.50/branches/R_10_00@24150 c028cbd2-c16b-5b4b-a496-9718f37d4682
1689 lines
64 KiB
C++
1689 lines
64 KiB
C++
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: pg_dox_mainpage.h
|
|
// Purpose: wxPropertyGrid Doxygen Documentation
|
|
// Author: Jaakko Salli
|
|
// Modified by:
|
|
// Created: Oct-08-2004
|
|
// RCS-ID: $Id:
|
|
// Copyright: (c) Jaakko Salli
|
|
// Licence: wxWindows license
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
#ifndef __WX_PG_DOX_MAINPAGE_H__
|
|
#define __WX_PG_DOX_MAINPAGE_H__
|
|
|
|
/**
|
|
@mainpage wxPropertyGrid 1.4.13 Overview
|
|
|
|
wxPropertyGrid is a specialized for editing properties such as strings, numbers,
|
|
flagsets, fonts, and colours. It allows hierarchial, collapsible properties (via
|
|
so-called categories that can hold child properties), sub-properties, and has strong
|
|
wxVariant support.
|
|
|
|
<b>Documentation for wxPython bindings:</b> For a tutorial see the accompanied
|
|
wxPython readme file and the test_propgrid.py sample. Otherwise, individual
|
|
member functions should work very much the same as with the C++ wxWidgets,
|
|
so you'll probably find wxPropertyGrid and wxPropertyGridManager class references handy.
|
|
|
|
Key Classes:\n
|
|
wxPropertyGrid\n
|
|
wxPropertyGridManager\n
|
|
wxPropertyGridEvent\n
|
|
|
|
Header files:\n
|
|
<b>wx/propgrid/propgrid.h:</b> Mandatory when using wxPropertyGrid.\n
|
|
<b>wx/propgrid/advprops.h:</b> For less often used property classes.\n
|
|
<b>wx/propgrid/manager.h:</b> Mandatory when using wxPropertyGridManager.\n
|
|
<b>wx/propgrid/propdev.h:</b> Mandatory when implementing custom property classes.\n
|
|
|
|
@ref whatsnew\n
|
|
@ref basics\n
|
|
@ref categories\n
|
|
@ref parentprops\n
|
|
@ref enumandflags\n
|
|
@ref advprops\n
|
|
@ref iterating\n
|
|
@ref operations\n
|
|
@ref events\n
|
|
@ref validating\n
|
|
@ref populating\n
|
|
@ref cellrender\n
|
|
@ref customizing\n
|
|
@ref usage2\n
|
|
@ref subclassing\n
|
|
@ref misc\n
|
|
@ref proplist\n
|
|
@ref userhelp\n
|
|
@ref notes\n
|
|
@ref newprops\n
|
|
@ref neweditors\n
|
|
|
|
@section whatsnew What's new in wxPropertyGrid 1.4?
|
|
|
|
For comprehensive list of changes and new features, please see the changelog.
|
|
|
|
For people implementing custom property classes the differences are extensive,
|
|
so if you are coming from wxPropertyGrid 1.2.x, it is recommended that you take a look.
|
|
|
|
|
|
@section 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
|
|
// Some specific window styles - for all additional styles,
|
|
// see Modules->PropertyGrid 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 tooltips.
|
|
pg->SetExtraStyle( wxPG_EX_HELP_AS_TOOLTIPS );
|
|
|
|
@endcode
|
|
|
|
(for complete list of new window styles: @link wndflags Additional Window Styles@endlink)
|
|
|
|
wxPropertyGrid is usually populated with lines like this:
|
|
|
|
@code
|
|
pg->Append( new wxStringProperty(wxT("Label"),wxT("Name"),wxT("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(wxT("IntProperty"), wxPG_LABEL, 12345678) );
|
|
|
|
// Add float property (value type is actually double)
|
|
pg->Append( new wxFloatProperty(wxT("FloatProperty"), wxPG_LABEL, 12345.678) );
|
|
|
|
// Add a bool property
|
|
pg->Append( new wxBoolProperty(wxT("BoolProperty"), wxPG_LABEL, false) );
|
|
|
|
// A string property that can be edited in a separate editor dialog.
|
|
pg->Append( new wxLongStringProperty(wxT("LongStringProperty"),
|
|
wxPG_LABEL,
|
|
wxT("This is much longer string than the ")
|
|
wxT("first one. Edit it by clicking the button.")));
|
|
|
|
// String editor with dir selector button.
|
|
pg->Append( new wxDirProperty(wxT("DirProperty"), wxPG_LABEL, ::wxGetUserHome()) );
|
|
|
|
// wxArrayStringProperty embeds a wxArrayString.
|
|
pg->Append( new wxArrayStringProperty(wxT("Label of ArrayStringProperty"),
|
|
wxT("NameOfArrayStringProp")));
|
|
|
|
// A file selector property.
|
|
pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) );
|
|
|
|
// Extra: set wildcard for file property (format same as in wxFileDialog).
|
|
pg->SetPropertyAttribute( wxT("FileProperty"),
|
|
wxPG_FILE_WILDCARD,
|
|
wxT("All files (*.*)|*.*") );
|
|
|
|
@endcode
|
|
|
|
Operations on properties should be done either via wxPropertyGrid's
|
|
(or wxPropertyGridManager's) methods, or by acquiring pointer to a property
|
|
(Append returns a wxPGProperty* or wxPGId, which is typedef for same), and then
|
|
calling its method. Note however that property's methods generally do not
|
|
automatically update grid graphics.
|
|
|
|
Property container functions operating on properties, such as SetPropertyValue or
|
|
DisableProperty, all accept a special wxPGPropArg, argument which can automatically
|
|
convert name of a property to a pointer. For instance:
|
|
|
|
@code
|
|
// A file selector property.
|
|
wxPGPropety* p = pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) );
|
|
|
|
// Valid: Set wildcard by name
|
|
pg->SetPropertyAttribute( wxT("FileProperty"),
|
|
wxPG_FILE_WILDCARD,
|
|
wxT("All files (*.*)|*.*") );
|
|
|
|
// Also Valid: Set wildcard by ptr
|
|
pg->SetPropertyAttribute( p,
|
|
wxPG_FILE_WILDCARD,
|
|
wxT("All files (*.*)|*.*") );
|
|
@endcode
|
|
|
|
Using pointer is faster, since it doesn't require hash map lookup. Anyway, you can allways
|
|
get property pointer (wxPGProperty*) as Append/Insert return value, or by calling
|
|
GetPropertyByName.
|
|
|
|
Below are samples for using some of the more commong operations. See
|
|
wxPropertyGridInterface and wxPropertyGrid class references for complete list.
|
|
|
|
@code
|
|
|
|
// wxPGId is a short-hand for wxPGProperty*. Let's use it this time.
|
|
wxPGId id = pg->GetPropertyByName( wxT("MyProperty") );
|
|
|
|
// There are many overloaded versions of this method, of which each accept
|
|
// different type of value.
|
|
pg->SetPropertyValue( wxT("MyProperty"), 200 );
|
|
|
|
// Setting a string works for all properties - conversion is done
|
|
// automatically.
|
|
pg->SetPropertyValue( id, wxT("400") );
|
|
|
|
// Getting property value as wxVariant.
|
|
wxVariant value = pg->GetPropertyValue( wxT("MyProperty") );
|
|
|
|
// Getting property value as String (again, works for all typs).
|
|
wxString value = pg->GetPropertyValueAsString( id );
|
|
|
|
// Getting property value as int. Provokes a run-time error
|
|
// if used with property which value type is not "long".
|
|
long value = pg->GetPropertyValueAsLong( wxT("MyProperty") );
|
|
|
|
// Set new name.
|
|
pg->SetPropertyName( wxT("MyProperty"), wxT("X") );
|
|
|
|
// Set new label - we need to use the new name.
|
|
pg->SetPropertyLabel( wxT("X"), wxT("New Label") );
|
|
|
|
// Disable the property. It's text will appear greyed.
|
|
// This is probably the closest you can get if you want
|
|
// a "read-only" property.
|
|
pg->DisableProperty( id );
|
|
|
|
@endcode
|
|
|
|
|
|
@section categories Categories
|
|
|
|
wxPropertyGrid has a hierarchial 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, and SetPropertyLabel
|
|
also sets label of a category. Note however that sometimes the label of a
|
|
property category may be referred as caption (for example, there is
|
|
SetCaptionForegroundColour method that sets text colour of a property category's label).
|
|
|
|
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 added to it. You may add
|
|
properties to specific categories by using wxPropertyGrid::Insert or wxPropertyGrid::AppendIn.
|
|
|
|
Category code sample:
|
|
|
|
@code
|
|
|
|
// One way to add category (similar to how other properties are added)
|
|
pg->Append( new wxPropertyCategory(wxT("Main")) );
|
|
|
|
// All these are added to "Main" category
|
|
pg->Append( new wxStringProperty(wxT("Name")) );
|
|
pg->Append( new wxIntProperty(wxT("Age"),wxPG_LABEL,25) );
|
|
pg->Append( new wxIntProperty(wxT("Height"),wxPG_LABEL,180) );
|
|
pg->Append( new wxIntProperty(wxT("Weight")) );
|
|
|
|
// Another one
|
|
pg->Append( new wxPropertyCategory(wxT("Attrikbutes")) );
|
|
|
|
// All these are added to "Attributes" category
|
|
pg->Append( new wxIntProperty(wxT("Intelligence")) );
|
|
pg->Append( new wxIntProperty(wxT("Agility")) );
|
|
pg->Append( new wxIntProperty(wxT("Strength")) );
|
|
|
|
@endcode
|
|
|
|
|
|
@section parentprops Tree-like Property Structure
|
|
|
|
As a new feature in version 1.3.1, basicly any property can have children. There
|
|
are few limitations, however.
|
|
|
|
@remarks
|
|
- Names of properties with non-category, non-root parents are not stored in 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 based on the values of
|
|
child properties, you must use wxStringProperty as parent and use value "<composed>".
|
|
- 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.
|
|
- Old wxParentProperty class is deprecated, and remains as a typedef of wxStringProperty.
|
|
If you want old value behavior, you must specify "<composed>" as wxStringProperty's
|
|
value.
|
|
|
|
Sample:
|
|
|
|
@code
|
|
wxPGId pid = pg->Append( new wxStringProperty(wxT("Car"),wxPG_LABEL,wxT("<composed>")) );
|
|
|
|
pg->AppendIn( pid, new wxStringProperty(wxT("Model"),
|
|
wxPG_LABEL,
|
|
wxT("Lamborghini Diablo SV")) );
|
|
|
|
pg->AppendIn( pid, new wxIntProperty(wxT("Engine Size (cc)"),
|
|
wxPG_LABEL,
|
|
5707) );
|
|
|
|
wxPGId speedId = pg->AppendIn( pid, new wxStringProperty(wxT("Speeds"),wxPG_LABEL,wxT("<composed>")) );
|
|
pg->AppendIn( speedId, new wxIntProperty(wxT("Max. Speed (mph)"),wxPG_LABEL,290) );
|
|
pg->AppendIn( speedId, new wxFloatProperty(wxT("0-100 mph (sec)"),wxPG_LABEL,3.9) );
|
|
pg->AppendIn( speedId, new wxFloatProperty(wxT("1/4 mile (sec)"),wxPG_LABEL,8.6) );
|
|
|
|
// Make sure the child properties can be accessed correctly
|
|
pg->SetPropertyValue( wxT("Car.Speeds.Max. Speed (mph)"), 300 );
|
|
|
|
pg->AppendIn( pid, new wxIntProperty(wxT("Price ($)"),
|
|
wxPG_LABEL,
|
|
300000) );
|
|
// Displayed value of "Car" property is now:
|
|
// "Lamborghini Diablo SV; [300; 3.9; 8.6]; 300000"
|
|
|
|
@endcode
|
|
|
|
@section 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 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 2147483647 which usually equals INT_MAX) is not
|
|
allowed as value.
|
|
|
|
A very simple example:
|
|
|
|
@code
|
|
|
|
//
|
|
// Using wxArrayString
|
|
//
|
|
wxArrayString arrDiet;
|
|
arr.Add(wxT("Herbivore"));
|
|
arr.Add(wxT("Carnivore"));
|
|
arr.Add(wxT("Omnivore"));
|
|
|
|
pg->Append( new wxEnumProperty(wxT("Diet"),
|
|
wxPG_LABEL,
|
|
arrDiet) );
|
|
|
|
|
|
|
|
//
|
|
// Using wxChar* array
|
|
//
|
|
const wxChar* arrayDiet[] =
|
|
{ wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
|
|
|
|
pg->Append( new wxEnumProperty(wxT("Diet"),
|
|
wxPG_LABEL,
|
|
arrayDiet) );
|
|
|
|
|
|
@endcode
|
|
|
|
Here's extended example using values as well:
|
|
|
|
@code
|
|
|
|
//
|
|
// Using wxArrayString and wxArrayInt
|
|
//
|
|
wxArrayString arrDiet;
|
|
arr.Add(wxT("Herbivore"));
|
|
arr.Add(wxT("Carnivore"));
|
|
arr.Add(wxT("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(wxT("Diet"),
|
|
wxPG_LABEL,
|
|
arrDiet,
|
|
arrIds,
|
|
50));
|
|
|
|
|
|
//
|
|
// Using wxChar* and long arrays
|
|
//
|
|
const wxChar* array_diet[] =
|
|
{ wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
|
|
|
|
long array_diet_ids[] =
|
|
{ 40, 45, 50 };
|
|
|
|
// Value can be set from string as well
|
|
pg->Append( new wxEnumProperty(wxT("Diet"),
|
|
wxPG_LABEL,
|
|
array_diet,
|
|
array_diet_ids);
|
|
|
|
@endcode
|
|
|
|
wxPGChoices is a class where wxEnumProperty, and other properties which
|
|
require label storage, actually stores strings and values. It is used
|
|
to facilitiate 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. Infact, if you wish to display bitmaps next to labels,
|
|
your best choice is to use this approach.
|
|
|
|
@code
|
|
|
|
wxPGChoices chs;
|
|
chs.Add(wxT("Herbivore"),40);
|
|
chs.Add(wxT("Carnivore"),45);
|
|
chs.Add(wxT("Omnivore"),50);
|
|
|
|
// Let's add an item with bitmap, too
|
|
chs.Add(wxT("None of the above"), wxBitmap(), 60);
|
|
|
|
// Note: you can add even whole arrays to wxPGChoices
|
|
|
|
pg->Append( new wxEnumProperty(wxT("Diet"),
|
|
wxPG_LABEL,
|
|
chs) );
|
|
|
|
// Add same choices to another property as well - this is efficient due
|
|
// to reference counting
|
|
pg->Append( new wxEnumProperty(wxT("Diet 2"),
|
|
wxPG_LABEL,
|
|
chs) );
|
|
|
|
@endcode
|
|
|
|
If you later need to change choices used by a property, there is function
|
|
for that as well.
|
|
|
|
@code
|
|
|
|
//
|
|
// Example 1: Add one extra item
|
|
wxPGChoices& choices = pg->GetPropertyChoices(wxT("Diet"));
|
|
choices.Add(wxT("Custom"),55);
|
|
|
|
//
|
|
// Example 2: Replace all the choices
|
|
wxPGChoices chs;
|
|
chs.Add(wxT("<No valid items yet>"),0);
|
|
pg->SetPropertyChoices(wxT("Diet"),chs);
|
|
|
|
@endcode
|
|
|
|
If you want to create your enum properties with simple (label,name,value)
|
|
constructor, then you need to create a new property class using one of the
|
|
supplied macro pairs. See @ref newprops for details.
|
|
|
|
<b>wxEditEnumProperty</b> is works exactly like wxEnumProperty, except
|
|
is uses non-readonly combobox as default editor, and value is stored as
|
|
string when it is not any of the choices.
|
|
|
|
wxFlagsProperty is similar:
|
|
|
|
@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(wxT("Window Style"),
|
|
wxPG_LABEL,
|
|
flags_prop_labels,
|
|
flags_prop_values,
|
|
wxDEFAULT_FRAME_STYLE) );
|
|
|
|
@endcode
|
|
|
|
wxFlagsProperty can use wxPGChoices just the same way as wxEnumProperty
|
|
(and also custom property classes can be created with similar macro pairs).
|
|
<b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
|
|
you will need to use SetPropertyChoices - otherwise they will not get updated
|
|
properly.
|
|
|
|
@section 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(wxT("MyDateProperty"),
|
|
wxPG_LABEL,
|
|
wxDateTime::Now()) );
|
|
|
|
// Image file property. Wildcard is auto-generated from available
|
|
// image handlers, so it is not set this time.
|
|
pg->Append( new wxImageFileProperty(wxT("Label of ImageFileProperty"),
|
|
wxT("NameOfImageFileProp")) );
|
|
|
|
// Font property has sub-properties. Note that we give window's font as
|
|
// initial value.
|
|
pg->Append( new wxFontProperty(wxT("Font"),
|
|
wxPG_LABEL,
|
|
GetFont()) );
|
|
|
|
// Colour property with arbitrary colour.
|
|
pg->Append( new wxColourProperty(wxT("My Colour 1"),
|
|
wxPG_LABEL,
|
|
wxColour(242,109,0) ) );
|
|
|
|
// System colour property.
|
|
pg->Append( new wxSystemColourProperty(wxT("My SysColour 1"),
|
|
wxPG_LABEL,
|
|
wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
|
|
|
|
// System colour property with custom colour.
|
|
pg->Append( new wxSystemColourProperty(wxT("My SysColour 2"),
|
|
wxPG_LABEL,
|
|
wxColour(0,200,160) ) );
|
|
|
|
// Cursor property
|
|
pg->Append( new wxCursorProperty(wxT("My Cursor"),
|
|
wxPG_LABEL,
|
|
wxCURSOR_ARROW));
|
|
|
|
@endcode
|
|
|
|
|
|
@section 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 or sub-propeties 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
|
|
@link iteratorflags List of Property Iterator Flags@endlink. 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
|
|
|
|
<b>wxPython Note:</b> Instead of ++ operator, use Next() method, and instead of
|
|
* operator, use GetProperty() method.
|
|
|
|
GetIterator() only works with wxPropertyGrid and the individual pages
|
|
of wxPropertyGridManager. In order to iterate through an arbitrary
|
|
property container, you need to use wxPropertyGridInterface::GetVIterator().
|
|
Note however that this virtual iterater is limited to forward iteration.
|
|
|
|
@code
|
|
|
|
wxPGVIterator it;
|
|
|
|
for ( it = manager->GetVIterator();
|
|
!it.AtEnd();
|
|
it.Next() )
|
|
{
|
|
wxPGProperty* p = it.GetProperty();
|
|
// Do something with the property
|
|
}
|
|
|
|
@endcode
|
|
|
|
|
|
@section operations More About Operating with Properties
|
|
|
|
Getting value of selected wxSystemColourProperty (which value type is derived
|
|
from wxObject):
|
|
|
|
@code
|
|
|
|
wxPGId id = pg->GetSelection();
|
|
|
|
if ( id )
|
|
{
|
|
// Get name of property
|
|
const wxString& name = pg->GetPropertyName( id );
|
|
|
|
// If type is not correct, GetColour() method will produce run-time error
|
|
if ( pg->GetPropertyValueType() == wxT("wxColourPropertyValue") ) )
|
|
{
|
|
wxColourPropertyValue* pcolval =
|
|
wxDynamicCast(pg->GetPropertyValueAsWxObjectPtr(id),
|
|
wxColourPropertyValue);
|
|
|
|
// Report value
|
|
wxString text;
|
|
if ( pcolval->m_type == wxPG_CUSTOM_COLOUR )
|
|
text.Printf( wxT("It is custom colour: (%i,%i,%i)"),
|
|
(int)pcolval->m_colour.Red(),
|
|
(int)pcolval->m_colour.Green(),
|
|
(int)pcolval->m_colour.Blue());
|
|
else
|
|
text.Printf( wxT("It is wx system colour (number=%i): (%i,%i,%i)"),
|
|
(int)pcolval->m_type,
|
|
(int)pcolval->m_colour.Red(),
|
|
(int)pcolval->m_colour.Green(),
|
|
(int)pcolval->m_colour.Blue());
|
|
|
|
wxMessageBox( text );
|
|
}
|
|
}
|
|
|
|
@endcode
|
|
|
|
@section populating Populating wxPropertyGrid Automatically
|
|
|
|
@subsection 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* builtin 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 significantly.
|
|
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 );
|
|
|
|
// In order to get wxObject ptr from a variant value,
|
|
// wxGetVariantCast(VARIANT,CLASSNAME) macro has to be called.
|
|
// Like this:
|
|
wxVariant v_txcol = pg->GetPropertyValue(wxT("Text Colour"));
|
|
const wxColour& txcol = wxGetVariantCast(v_txcol,wxColour);
|
|
|
|
@endcode
|
|
|
|
@subsection 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 supplied xrc handler
|
|
(src/xh_propgrid.cpp) uses it. See that code for more info.
|
|
NOTE: src/xh_propgrid.cpp is not included in the library by default,
|
|
to avoid dependency to wxXRC. You will need to add it to your application
|
|
separately.
|
|
|
|
@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 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.
|
|
|
|
The custom event class, wxPropertyGridEvent, has methods to directly
|
|
access the property that triggered the event.
|
|
|
|
Here's a small sample:
|
|
|
|
@code
|
|
|
|
// Portion of an imaginary event table
|
|
BEGIN_EVENT_TABLE(MyForm, wxFrame)
|
|
|
|
...
|
|
|
|
// This occurs when a property value changes
|
|
EVT_PG_CHANGED( PGID, MyForm::OnPropertyGridChange )
|
|
|
|
...
|
|
|
|
END_EVENT_TABLE()
|
|
|
|
void MyForm::OnPropertyGridChange( wxPropertyGridEvent& event )
|
|
{
|
|
wxPGProperty *property = event.GetProperty();
|
|
|
|
// It may be NULL
|
|
if ( !property )
|
|
return;
|
|
|
|
// Get name of changed property
|
|
const wxString& name = property->GetName();
|
|
|
|
// Get resulting value
|
|
wxVariant value = property->GetValue();
|
|
}
|
|
|
|
@endcode
|
|
|
|
Another event type you might find useful 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
|
|
|
|
// Portion of an imaginary event table
|
|
BEGIN_EVENT_TABLE(MyForm, wxFrame)
|
|
|
|
...
|
|
|
|
// This occurs when a property value changes
|
|
EVT_PG_CHANGING( PGID, MyForm::OnPropertyGridChanging )
|
|
|
|
...
|
|
|
|
END_EVENT_TABLE()
|
|
|
|
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 Sub-property Event Handling
|
|
- For aggregate type properties (wxFontProperty, wxFlagsProperty, etc), events
|
|
occur for the main parent property only. For other properties events occur
|
|
for the children themselves..
|
|
|
|
- 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 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 methods 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() == wxT("Font") )
|
|
{
|
|
// Make sure value is not unspecified
|
|
if ( !pendingValue.IsNull() )
|
|
{
|
|
wxFont font << pendingValue;
|
|
|
|
// Let's just allow Arial font
|
|
if ( font.GetFaceName() != wxT("Arial") )
|
|
{
|
|
event.Veto();
|
|
event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
|
|
wxPG_VFB_BEEP |
|
|
wxPG_VFB_SHOW_MESSAGE);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
@endcode
|
|
|
|
|
|
@section 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::Item() and wxPGChoiceEntry class
|
|
reference for more info.
|
|
|
|
|
|
@section 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
|
|
of sub-classing a property class etc.
|
|
|
|
@subsection 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 customvalidator Setting Validator
|
|
|
|
You can set wxValidator for a property using wxPropertyGrid::SetPropertyValidator.
|
|
|
|
Validator will work just like in wxWidgets (ie. editorControl->SetValidator(validator)
|
|
is called).
|
|
|
|
@subsection 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
|
|
using wxPG_EDITOR(EditorName) macro, 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
|
|
|
|
wxPGId colProp = pg->Append(wxColourProperty(wxT("Text Colour")));
|
|
|
|
pg->SetPropertyEditor(colProp,wxPG_EDITOR(TextCtrlAndButton));
|
|
|
|
@endcode
|
|
|
|
Naturally, creating and setting custom editor classes is a possibility as
|
|
well. For more information, see wxPGEditor class reference.
|
|
|
|
@subsection editorattrs Property Attributes Recognized by Editors
|
|
|
|
<b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step",
|
|
"Wrap" and "MotionSpin" attributes.
|
|
|
|
@subsection multiplebuttons Adding Multiple Buttons Next to an Editor
|
|
|
|
See wxPGMultiButton class reference.
|
|
|
|
@subsection 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 attributes Property Attributes
|
|
|
|
Miscellaneous values, often specific to a property type, can be set
|
|
using wxPropertyGrid::SetPropertyAttribute and wxPropertyGrid::SetPropertyAttributeAll
|
|
methods.
|
|
|
|
Attribute names are strings and values wxVariant. Arbitrary names are allowed
|
|
inorder to store user values. Constant equivalents of all attribute string names are
|
|
provided. Some of them are defined as cached strings, so using constants can provide
|
|
for smaller binary size.
|
|
|
|
For complete list of attributes, see @link attrids Property Attributes@endlink.
|
|
|
|
@subsection boolcheckbox Setting wxBoolProperties to Use Check Box
|
|
|
|
To have all wxBoolProperties to use CheckBox editor instead of Choice, use
|
|
following (call after bool properties have been added):
|
|
|
|
@code
|
|
pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX,true);
|
|
@endcode
|
|
|
|
|
|
@section usage2 Using wxPropertyGridManager
|
|
|
|
wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
|
|
which can optionally have toolbar for mode and page selection, and a help text
|
|
box.
|
|
|
|
wxPropertyGridManager inherits from wxPropertyGridInterface, and as such
|
|
it has most property manipulation functions. However, only some of them affect
|
|
properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some
|
|
(eg. Append()) only apply to the currently selected page.
|
|
|
|
To operate explicitly on properties on specific page, use wxPropertyGridManager::GetPage()
|
|
to obtain pointer to page's wxPropertyGridPage object.
|
|
|
|
Visual methods, such as SetCellBackgroundColour and GetNextVisible are only
|
|
available in wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain
|
|
pointer to it.
|
|
|
|
Iteration methods will not work in wxPropertyGridManager. Instead, you must acquire
|
|
the internal grid (GetGrid()) or wxPropertyGridPage object (GetPage()).
|
|
|
|
wxPropertyGridManager constructor has exact same format as wxPropertyGrid
|
|
constructor, and basicly accepts same extra window style flags (albeit also
|
|
has some extra ones).
|
|
|
|
Here's some example code for creating and populating a wxPropertyGridManager:
|
|
|
|
@code
|
|
|
|
wxPropertyGridManager* pgMan = new wxPropertyGridManager(this, PGID,
|
|
wxDefaultPosition, wxDefaultSize,
|
|
// These and other similar styles are automatically
|
|
// passed to the embedded wxPropertyGrid.
|
|
wxPG_BOLD_MODIFIED|wxPG_SPLITTER_AUTO_CENTER|
|
|
// Include toolbar.
|
|
wxPG_TOOLBAR |
|
|
// Include description box.
|
|
wxPG_DESCRIPTION |
|
|
// Include compactor.
|
|
wxPG_COMPACTOR |
|
|
// Plus defaults.
|
|
wxPGMAN_DEFAULT_STYLE
|
|
);
|
|
|
|
wxPropertyGridPage* page;
|
|
|
|
pgMan->AddPage(wxT("First Page"));
|
|
page = pgMan->GetLastPage();
|
|
|
|
page->Append( new wxPropertyCategory(wxT("Category A1")) );
|
|
|
|
page->Append( new wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
|
|
|
|
page->Append( new wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
|
|
|
|
pgMan->AddPage(wxT("Second Page"));
|
|
page = pgMan->GetLastPage();
|
|
|
|
page->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
|
|
|
|
page->Append( new wxFontProperty(wxT("Font"),wxPG_LABEL) );
|
|
|
|
@endcode
|
|
|
|
@subsection 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
|
|
wxPropertyGridMethods and wxPropertyGridState.
|
|
|
|
|
|
@section subclassing Subclassing wxPropertyGrid and wxPropertyGridManager
|
|
|
|
Few things to note:
|
|
|
|
- Only a small percentage of member functions are virtual. If you need more,
|
|
just let me know.
|
|
|
|
- Data manipulation is done in wxPropertyGridState class. So, instead of
|
|
overriding wxPropertyGrid::Insert, you'll probably want to override wxPropertyGridState::DoInsert.
|
|
|
|
- Override wxPropertyGrid::CreateState to instantiate your derivate wxPropertyGridState.
|
|
For wxPropertyGridManager, you'll need to subclass wxPropertyGridPage instead (since it
|
|
is derived from wxPropertyGridState), and hand over instances in wxPropertyGridManager::AddPage
|
|
calls.
|
|
|
|
- You can use a derivate wxPropertyGrid with manager by overriding
|
|
wxPropertyGridManager::CreatePropertyGrid member function. However, if
|
|
you you do this, then you must also use two-step construction (ie.
|
|
default constructor and Create() instead of just constructor with
|
|
arguments) when creating the manager.
|
|
|
|
@section misc Miscellaneous Topics
|
|
|
|
@subsection 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 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 boolproperty wxBoolProperty
|
|
|
|
There are few points about wxBoolProperty that require futher discussion:
|
|
- wxBoolProperty can be shown as either normal combobox or as a checkbox.
|
|
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(wxT("MyFlagsProperty"),wxPG_BOOL_USE_CHECKBOX,true,wxPG_RECURSE);
|
|
@endcode
|
|
|
|
- Default item names for wxBoolProperty are [wxT("False"),wxT("True")]. This can be
|
|
changed using wxPropertyGrid::SetBoolChoices(trueChoice,falseChoice).
|
|
|
|
@subsection 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 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 behavior can be customized using
|
|
wxPropertyGridInterface::SetColumnProportion(). Usually it is used to set
|
|
non-equal column proportions, which in essence stops the splitter(s) no
|
|
longer being 'centered' as such.
|
|
|
|
@subsection 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 Making property labels editable
|
|
|
|
Normally only the second column (i.e. the one at column index 1) is editable
|
|
by user. However, you can make any column editable by calling
|
|
wxPropertyGrid::MakeColumnEditable(index). For instance, calling that
|
|
function with index 0 you can make property labels editable.
|
|
|
|
Events wxEVT_PG_LABEL_EDIT_BEGIN and wxEVT_PG_LABEL_EDIT_ENDING are generated
|
|
as appropriate. You can veto these events to prevent label editor from
|
|
(dis)appearing.
|
|
|
|
@subsection colourproperty wxColourProperty and wxSystemColourProperty
|
|
|
|
Through subclassing, 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.
|
|
|
|
|
|
@subsection compilerdefines Supported Preprocessor Defines
|
|
|
|
Here is list of supported preprocessor defines (other than those that relate with
|
|
wxWidgets core library):
|
|
|
|
<b>wxPG_INCLUDE_MANAGER:</b> Defines as 0 to exclude wxPropertyGridManager from compilation.
|
|
|
|
<b>wxPG_INCLUDE_ADVPROPS:</b> Defines as 0 to exclude properties and editors defined in advprops.h
|
|
and advprops.cpp.
|
|
|
|
<b>wxPG_USE_WXMODULE:</b> Define as 0 to not use wxModule to manage global variables.
|
|
This may be needed in cases where wxPropertyGrid is linked as a plugin DLL, or when
|
|
wxPropertyGrid is linked statically in a DLL.
|
|
|
|
<b>WXMAKINGLIB_PROPGRID:</b> Define if you are linking wxPropertyGrid statically
|
|
but wxWidgets itself is DLL.
|
|
|
|
<b>WXMAKINGDLL_PROPGRID:</b> Define when building wxPropertyGrid as a DLL. This
|
|
should be automatically defined correctly by the Bakefile-generated makefiles.
|
|
|
|
<b>wxPG_USE_STL:</b> Define as 1 to let wxPropertyGrid use STL classes in API
|
|
as much as possible. Default value equals wxUSE_STL.
|
|
|
|
<b>wxPG_COMPATIBILITY_1_2_0:</b> Define as 1 to make wxPropertyGrid more compatible with the
|
|
old 1.2.x releases.
|
|
|
|
<b>wxPG_COMPATIBILITY_1_0_0:</b> Define to make wxPropertyGrid more compatible with the
|
|
old 1.0.x releases.
|
|
|
|
|
|
@section proplist Property Class Descriptions
|
|
|
|
Here are descriptions of built-in properties, with attributes
|
|
(see wxPropertyGrid::SetPropertyAttribute) that apply to them.
|
|
Note that not all attributes are necessarily here. For complete
|
|
list, see @link attrids Property Attributes@endlink.
|
|
|
|
@subsection wxPropertyCategory
|
|
|
|
Not an actual property per se, but a header for a group of properties.
|
|
|
|
@subsection wxStringProperty
|
|
|
|
<b>Inheritable Class:</b> wxStringProperty
|
|
|
|
Simple string property. wxPG_STRING_PASSWORD attribute may be used
|
|
to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
|
|
|
|
@remarks
|
|
* wxStringProperty has a special trait: if it has value of "<composed>",
|
|
and also has child properties, then its displayed value becomes
|
|
composition of child property values, similar as with wxFontProperty,
|
|
for instance.
|
|
|
|
@subsection wxIntProperty
|
|
|
|
Like wxStringProperty, but converts text to a signed long integer.
|
|
wxIntProperty seemlessly supports 64-bit integers (ie. wxLongLong).
|
|
|
|
@subsection wxUIntProperty
|
|
|
|
Like wxIntProperty, but displays value as unsigned int. To set
|
|
the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
|
|
To set the globally used base, manipulate wxPG_UINT_BASE int
|
|
attribute. Regardless of current prefix, understands (hex) values starting
|
|
with both "0x" and "$".
|
|
wxUIntProperty seemlessly supports 64-bit unsigned integers (ie. wxULongLong).
|
|
|
|
@subsection wxFloatProperty
|
|
|
|
Like wxStringProperty, but converts text to a double-precision floating point.
|
|
Default float-to-text precision is 6 decimals, but this can be changed
|
|
by modifying wxPG_FLOAT_PRECISION attribute.
|
|
|
|
@subsection wxBoolProperty
|
|
|
|
Represents a boolean value. wxChoice is used as editor control, by the
|
|
default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
|
|
check box instead.
|
|
|
|
@subsection wxLongStringProperty
|
|
|
|
Like wxStringProperty, but has a button that triggers a small text editor
|
|
dialog.
|
|
|
|
@subsection wxDirProperty
|
|
|
|
Like wxLongStringProperty, but the button triggers dir selector instead.
|
|
|
|
@subsection wxFileProperty
|
|
|
|
Like wxLongStringProperty, but the button triggers file selector instead.
|
|
Default wildcard is "All files..." but this can be changed by setting
|
|
wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
|
|
Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
|
|
only the filename, not the entire path.
|
|
|
|
@subsection wxEnumProperty
|
|
|
|
Represents a single selection from a list of choices -
|
|
custom combobox control is used to edit the value.
|
|
|
|
@subsection wxFlagsProperty
|
|
|
|
Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
|
|
are created for editing individual bits. Textctrl is created to manually edit
|
|
the flags as a text; a continous sequence of spaces, commas and semicolons
|
|
is considered as a flag id separator.
|
|
<b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
|
|
will need to use SetPropertyChoices - otherwise they will not get updated properly.
|
|
|
|
@subsection wxArrayStringProperty
|
|
|
|
Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
|
|
|
|
@subsection wxDateProperty
|
|
|
|
wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
|
|
should work as well. wxPG_DATE_FORMAT attribute can be used to change
|
|
string wxDateTime::Format uses (altough default is recommended as it is
|
|
locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
|
|
style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY;
|
|
specifying wxDP_ALLOWNONE enables better support for unspecified
|
|
property value).
|
|
|
|
@subsection wxEditEnumProperty
|
|
|
|
Represents a string that can be freely edited or selected from list of choices -
|
|
custom combobox control is used to edit the value.
|
|
|
|
@subsection wxMultiChoiceProperty
|
|
|
|
Allows editing a multiple selection from a list of strings. This is
|
|
property is pretty much built around concept of wxMultiChoiceDialog.
|
|
It uses wxArrayString value.
|
|
|
|
@subsection wxImageFileProperty
|
|
|
|
Like wxFileProperty, but has thumbnail of the image in front of
|
|
the filename and autogenerates wildcard from available image handlers.
|
|
|
|
@subsection wxColourProperty
|
|
|
|
<b>Useful alternate editor:</b> Choice.
|
|
|
|
Represents wxColour. wxButton is used to trigger a colour picker dialog.
|
|
|
|
@subsection wxFontProperty
|
|
|
|
Represents wxFont. Various sub-properties are used to edit individual
|
|
subvalues.
|
|
|
|
@subsection wxSystemColourProperty
|
|
|
|
Represents wxColour and a system colour index. wxChoice is used to edit
|
|
the value. Drop-down list has color images.
|
|
|
|
@subsection wxCursorProperty
|
|
|
|
Represents a wxCursor. wxChoice is used to edit the value.
|
|
Drop-down list has cursor images under some (wxMSW) platforms.
|
|
|
|
@subsection Additional Sample Properties
|
|
|
|
Sample application has following additional examples of custom properties:
|
|
- wxFontDataProperty ( edits wxFontData )
|
|
- wxPointProperty ( edits wxPoint )
|
|
- wxSizeProperty ( edits wxSize )
|
|
- wxAdvImageFileProperty ( like wxImageFileProperty, but also has a drop-down for recent image selection)
|
|
- wxDirsProperty ( edits a wxArrayString consisting of directory strings)
|
|
- wxArrayDoubleProperty ( edits wxArrayDouble )
|
|
|
|
@section userhelp Using wxPropertyGrid control
|
|
|
|
This is a short summary of how a wxPropertyGrid is used (not how it is programmed),
|
|
or, rather, how it <b>should</b> behave in practice.
|
|
|
|
- Basic mouse usage is as follows:\n
|
|
- Clicking property label selects it.
|
|
- Clicking property value selects it and focuses to editor control.
|
|
- Clicking category label selects the category.
|
|
- Double-clicking category label selects the category and expands/collapses it.
|
|
- Double-clicking labels of a property with children expands/collapses it.
|
|
- Following apply if wxPG_EX_MULTIPLE_SELECTION extra window style is used:\n
|
|
- Clicking property with Shift down will add it to list of selected properties
|
|
- Dragging with left mouse button down will select multiple properties.
|
|
|
|
- Keyboard usage is as follows:\n
|
|
- alt + down (or right) - displays editor dialog (if any) for a property. Note
|
|
that this shortcut can be changed using wxPropertyGrid::SetButtonShortcut.\n
|
|
Only when editor control is not focused:\n
|
|
- cursor up - moves to previous visible property\n
|
|
- cursor down - moves to next visible property\n
|
|
- cursor left - if collapsible, collapses, otherwise moves to previous property\n
|
|
- cursor right - if expandable, expands, otherwise moves to next property\n
|
|
- tab (if enabled) - focuses keyboard to the editor control of selected property
|
|
NOTE: This doesn't work at the moment (and is unlikely to be fixed). Same applies
|
|
to other tab key combos described below.\n
|
|
Only when editor control is focused:\n
|
|
- return/enter - confirms changes made to a wxTextCtrl based editor\n
|
|
- tab - moves to next visible property (or, if in last one, moves out of grid)\n
|
|
- shift-tab - moves to previous visible property (or, if in first one, moves out of grid)\n
|
|
- escape - unfocuses from editor control and cancels any changes made
|
|
(latter for wxTextCtrl based editor only)\n
|
|
|
|
- In long strings tabs are represented by "\t" and line break by "\n".
|
|
|
|
@section notes Design Notes
|
|
- Currently wxPropertyGridManager uses "easy" way to relay events from embedded
|
|
wxPropertyGrid. That is, the exact same id is used for both.
|
|
|
|
- If wxPG_DOUBLE_BUFFER is 1 (default for MSW, GTK and MAC), wxPropertyGrid::DoDrawItems
|
|
composes the image on a wxMemoryDC. This effectively eliminates flicker caused by drawing
|
|
itself (property editor controls are another matter).
|
|
|
|
- Under wxMSW, flicker freedom when creating native editor controls is achieved by using
|
|
following undocumented scheme:
|
|
@code
|
|
wxControl* ctrl = new wxControl();
|
|
#ifdef __WXMSW__
|
|
ctrl->Hide();
|
|
#endif
|
|
ctrl->Create(parent,id,...);
|
|
|
|
...further initialize, move, resize, etc...
|
|
|
|
#ifdef __WXMSW__
|
|
ctrl->Show();
|
|
#endif
|
|
@endcode
|
|
|
|
@section crossplatform Crossplatform Notes (not necessarily wxPropertyGrid specific)
|
|
|
|
- GTK1: When showing a dialog you may encounter invisible font!
|
|
Solution: Set parent's font using SetOwnFont instead of SetFont.
|
|
|
|
- GTK: Your own control can overdraw wxGTK wxWindow border!
|
|
|
|
- wxWindow::SetSizeHints may be necessary to shrink controls below certain treshold,
|
|
but only on some platforms. For example wxMSW might allow any shrinking without
|
|
SetSizeHints call where wxGTK might not.
|
|
|
|
- GTK Choice (atleast, maybe other controls as well) likes its items set
|
|
in constructor. Appending them seems to be slower (Freeze+Thaw won't help).
|
|
Even using Append that gets wxArrayString argument may not be good, since it
|
|
may just append every string one at a time.
|
|
|
|
|
|
@section newprops Creating New Properties
|
|
|
|
Easiest solution for creating an arbitrary property is to subclass an existing,
|
|
property class that most resembles the intended end result. You may need to include
|
|
header file wx/propgrid/propdev.h.
|
|
|
|
For instance:
|
|
|
|
@code
|
|
|
|
#include <wx/propgrid/propdev.h>
|
|
|
|
//
|
|
// wxLongStringProperty has wxString as value type and TextCtrlAndButton as editor.
|
|
// Here we will derive a new property class that will show single choice dialog
|
|
// on button click.
|
|
//
|
|
|
|
class MyStringProperty : public wxLongStringProperty
|
|
{
|
|
DECLARE_DYNAMIC_CLASS(MyStringProperty)
|
|
public:
|
|
|
|
// Default constructor
|
|
MyStringProperty() { }
|
|
|
|
// Normal property constructor.
|
|
MyStringProperty(const wxString& label,
|
|
const wxString& name = wxPG_LABEL,
|
|
const wxString& value = wxEmptyString)
|
|
: wxLongStringProperty(label, name, value)
|
|
{
|
|
// Prepare choices
|
|
m_choices.Add(wxT("Cat"));
|
|
m_choices.Add(wxT("Dog"));
|
|
m_choices.Add(wxT("Gibbon"));
|
|
m_choices.Add(wxT("Otter"));
|
|
}
|
|
|
|
// Do something special when button is clicked.
|
|
virtual wxPGEditorDialogAdapter* GetEditorDialog() const
|
|
{
|
|
return new wxSingleChoiceDialogAdapter(m_choices);
|
|
}
|
|
|
|
protected:
|
|
wxPGChoices m_choices;
|
|
};
|
|
|
|
IMPLEMENT_DYNAMIC_CLASS(MyStringProperty, wxLongStringProperty)
|
|
|
|
//
|
|
// Actually implement the editor dialog adapter
|
|
// Naturally, in real code this would have to come
|
|
// before wxPGProperty::GetEditorDialog()
|
|
// implementation.
|
|
//
|
|
|
|
class wxSingleChoiceDialogAdapter : public wxPGEditorDialogAdapter
|
|
{
|
|
public:
|
|
|
|
wxSingleChoiceDialogAdapter( const wxPGChoices& choices )
|
|
: wxPGEditorDialogAdapter(), m_choices(choices)
|
|
{
|
|
}
|
|
|
|
virtual bool DoShowDialog( wxPropertyGrid* WXUNUSED(propGrid),
|
|
wxPGProperty* WXUNUSED(property) )
|
|
{
|
|
wxString s = ::wxGetSingleChoice(wxT("Message"),
|
|
wxT("Caption"),
|
|
m_choices.GetLabels());
|
|
if ( s.length() )
|
|
{
|
|
SetValue(s);
|
|
return true;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
protected:
|
|
const wxPGChoices& m_choices;
|
|
};
|
|
|
|
@endcode
|
|
|
|
You can then create a property instance, for instance:
|
|
|
|
@code
|
|
|
|
pg->Append( new MyStringProperty(label, name, value) );
|
|
|
|
@endcode
|
|
|
|
If you want to change editor used, use code like below (continues our sample above).
|
|
|
|
Note that built-in editors include: TextCtrl, Choice, ComboBox, TextCtrlAndButton,
|
|
ChoiceAndButton, CheckBox, SpinCtrl, and DatePickerCtrl.
|
|
|
|
@code
|
|
|
|
// In class body:
|
|
virtual const wxPGEditor* DoGetEditorClass() const
|
|
{
|
|
return wxPG_EDITOR(TextCtrl);
|
|
}
|
|
|
|
@endcode
|
|
|
|
You can change the 'value type' of a property by simply assigning different type
|
|
of variant with SetValue. <b>It is mandatory to implement wxVariantData class
|
|
for all data types used as property values.</b> Also, it is further recommended
|
|
to derive your class from wxPGVariantData (see class documentation for more info).
|
|
|
|
@remarks
|
|
- For practical examples of arbitrary properties, please take a look
|
|
at the sample properties in samples/sampleprops.cpp.
|
|
- Read wxPGProperty class documentation to find out what each virtual member
|
|
function should do.
|
|
- Documentation below may be helpful (altough you'd probably do better
|
|
by looking at the sample properties first).
|
|
|
|
@subsection methoda Macro Pairs
|
|
|
|
These are quick methods for creating customized properties.
|
|
|
|
@subsubsection custstringprop String Property with Button
|
|
|
|
This custom property will be exactly the same as wxLongStringProperty,
|
|
except that you can specify a custom code to handle what happens
|
|
when the button is pressed.
|
|
|
|
In header:
|
|
@code
|
|
WX_PG_DECLARE_STRING_PROPERTY(PROPNAME)
|
|
@endcode
|
|
|
|
In source:
|
|
@code
|
|
|
|
// FLAGS can be wxPG_NO_ESCAPE if escape sequences shall not be expanded.
|
|
WX_PG_IMPLEMENT_STRING_PROPERTY(PROPNAME, FLAGS)
|
|
|
|
bool PROPNAME::OnButtonClick( wxPropertyGrid* propgrid, wxString& value )
|
|
{
|
|
//
|
|
// TODO: Show dialog, read initial string from value. If changed,
|
|
// store new string to value and return TRUE.
|
|
// NB: You must use wxPGProperty::SetValueInEvent().
|
|
//
|
|
}
|
|
@endcode
|
|
|
|
FLAGS is either wxPG_NO_ESCAPE (newlines and tabs are not translated to and
|
|
from escape sequences) or wxPG_ESCAPE (newlines and tabs are transformed
|
|
into C-string escapes).
|
|
|
|
There is also WX_PG_IMPLEMENT_STRING_PROPERTY_WITH_VALIDATOR variant which
|
|
also allows setting up a validator for the property. Like this:
|
|
|
|
@code
|
|
|
|
WX_PG_IMPLEMENT_STRING_PROPERTY_WITH_VALIDATOR(PROPNAME, FLAGS)
|
|
|
|
bool PROPNAME::OnButtonClick( wxPropertyGrid* propgrid, wxString& value )
|
|
{
|
|
//
|
|
// TODO: Show dialog, read initial string from value. If changed,
|
|
// store new string to value and return TRUE.
|
|
// NB: You must use wxPGProperty::SetValueInEvent().
|
|
//
|
|
}
|
|
|
|
wxValidator* PROPNAME::DoGetValidator() const
|
|
{
|
|
//
|
|
// TODO: Return pointer to a new wxValidator instance. In most situations,
|
|
// code like this should work well:
|
|
//
|
|
// WX_PG_DOGETVALIDATOR_ENTRY()
|
|
//
|
|
// wxMyValidator* validator = new wxMyValidator(...);
|
|
//
|
|
// ... prepare validator...
|
|
//
|
|
// WX_PG_DOGETVALIDATOR_EXIT(validator)
|
|
//
|
|
// Macros are used to maintain only one actual validator instance
|
|
// (ie. on a second call, function exits within the first macro).
|
|
//
|
|
// For real examples, search props.cpp for ::DoGetValidator, it should
|
|
// have several.
|
|
//
|
|
}
|
|
@endcode
|
|
|
|
@subsubsection custflagsprop Custom Flags Property
|
|
Flags property with custom default value and built-in labels/values.
|
|
|
|
In header:
|
|
@code
|
|
WX_PG_DECLARE_CUSTOM_FLAGS_PROPERTY(PROPNAME)
|
|
@endcode
|
|
|
|
In source:
|
|
@code
|
|
|
|
// LABELS are VALUES are as in the arguments to wxFlagsProperty
|
|
// constructor. DEFVAL is the new default value (normally it is 0).
|
|
WX_PG_IMPLEMENT_CUSTOM_FLAGS_PROPERTY(PROPNAME,LABELS,VALUES,DEFAULT_FLAGS)
|
|
@endcode
|
|
|
|
The new property class will have simple (label,name,value) constructor.
|
|
|
|
@subsubsection custenumprop Custom EnumProperty
|
|
|
|
Exactly the same as custom FlagsProperty. Simply replace FLAGS with ENUM in
|
|
macro names to create wxEnumProperty based class instead.
|
|
|
|
@subsubsection custarraystringprop Custom ArrayString property
|
|
|
|
This type of custom property allows selecting different string delimiter
|
|
(default is '"' on both sides of the string - as in C code), and allows
|
|
adding custom button into the editor dialog.
|
|
|
|
In header:
|
|
@code
|
|
WX_PG_DECLARE_ARRAYSTRING_PROPERTY(wxMyArrayStringProperty)
|
|
@endcode
|
|
|
|
In source:
|
|
|
|
@code
|
|
|
|
// second argument = string delimiter. '"' for C string style (default),
|
|
// and anything else for str1<delimiter> str2<delimiter> str3 style
|
|
// (so for example, using ';' would result to str1; str2; str3).
|
|
// third argument = const wxChar* text for the custom button. If NULL
|
|
// then no button is added.
|
|
WX_PG_IMPLEMENT_ARRAYSTRING_PROPERTY(wxMyArrayStringProperty,',',wxT("Browse"))
|
|
|
|
bool wxMyArrayStringProperty::OnCustomStringEdit(wxWindow* parent,
|
|
wxString& value)
|
|
{
|
|
//
|
|
// TODO: Show custom editor dialog, read initial string from value.
|
|
// If changed, store new string to value and return TRUE.
|
|
//
|
|
}
|
|
|
|
@endcode
|
|
|
|
@subsubsection custcolprop Custom ColourProperty
|
|
|
|
wxColourProperty/wxSystemColourProperty that can have custom list of colours
|
|
in dropdown.
|
|
|
|
Use version that doesn't have _USES_WXCOLOUR in macro names to have
|
|
wxColourPropertyValue as value type instead of plain wxColour (in this case
|
|
values array might also make sense).
|
|
|
|
In header:
|
|
@code
|
|
#include <wx/propgrid/advprops.h>
|
|
WX_PG_DECLARE_CUSTOM_COLOUR_PROPERTY_USES_WXCOLOUR(wxMyColourProperty)
|
|
@endcode
|
|
|
|
In source:
|
|
|
|
@code
|
|
|
|
// Colour labels. Last (before NULL, if any) must be Custom.
|
|
static const wxChar* mycolprop_labels[] = {
|
|
wxT("Black"),
|
|
wxT("Blue"),
|
|
wxT("Brown"),
|
|
wxT("Custom"),
|
|
(const wxChar*) NULL
|
|
};
|
|
|
|
// Relevant colour values as unsigned longs.
|
|
static unsigned long mycolprop_colours[] = {
|
|
wxPG_COLOUR(0,0,0),
|
|
wxPG_COLOUR(0,0,255),
|
|
wxPG_COLOUR(166,124,81),
|
|
wxPG_COLOUR(0,0,0)
|
|
};
|
|
|
|
// Implement property class. Third argument is optional values array,
|
|
// but in this example we are only interested in creating a shortcut
|
|
// for user to access the colour values.
|
|
WX_PG_IMPLEMENT_CUSTOM_COLOUR_PROPERTY_USES_WXCOLOUR(wxMyColourProperty,
|
|
mycolprop_labels,
|
|
(long*)NULL,
|
|
mycolprop_colours)
|
|
@endcode
|
|
|
|
|
|
@section neweditors Creating Custom Property Editor
|
|
|
|
- See the sources of built-in editors in contrib/src/propgrid/propgrid.cpp
|
|
(search for wxPGTextCtrlEditor).
|
|
|
|
- For additional information, see wxPGEditor class reference
|
|
|
|
@subsection wxpythoneditors In wxPython
|
|
|
|
- See README-propgrid-wxPython.txt
|
|
|
|
*/
|
|
|
|
#endif // __WX_PG_DOX_MAINPAGE_H__
|
|
|