mirror of https://github.com/odrling/Aegisub
1898 lines
71 KiB
C
1898 lines
71 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.2.11 Overview
|
||
|
|
||
|
wxPropertyGrid is a specialized two-column grid 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 (for example,
|
||
|
allows populating from near-arbitrary list of wxVariants).
|
||
|
|
||
|
<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.
|
||
|
|
||
|
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 featurelist\n
|
||
|
\ref basics\n
|
||
|
\ref categories\n
|
||
|
\ref parentprops
|
||
|
\ref enumandflags\n
|
||
|
\ref advprops\n
|
||
|
\ref operations\n
|
||
|
\ref events\n
|
||
|
\ref populating\n
|
||
|
\ref customizing\n
|
||
|
\ref custprop\n
|
||
|
\ref usage2\n
|
||
|
\ref subclassing\n
|
||
|
\ref misc\n
|
||
|
\ref proplist\n
|
||
|
\ref userhelp\n
|
||
|
\ref bugs\n
|
||
|
\ref issues\n
|
||
|
\ref todo\n
|
||
|
\ref notes\n
|
||
|
\ref newprops\n
|
||
|
\ref neweditors\n
|
||
|
|
||
|
\section featurelist wxPropertyGrid Features
|
||
|
|
||
|
Following is a non-exhaustive list of various wxPropertyGrid features and classes or methods necessary
|
||
|
to use them.
|
||
|
|
||
|
- Hiding property editor: You can either use limited editing mode (wxPG_LIMITED_EDITING
|
||
|
window style, wxPropertyGrid::LimitPropertyEditing), which hides wxTextCtrl based
|
||
|
editor when other methods (dialog or sub-properties) are available, <b>or</b> you
|
||
|
can disable the property, which effectively hides the editor and makes the property
|
||
|
label to be drawn in grey colour.
|
||
|
- Unspecified, empty values (wxPropertyGrid::SetPropertyUnspecified,
|
||
|
wxPropertyGrid::IsPropertyUnspecified).
|
||
|
- Client data (void*) (wxPropertyGrid::SetPropertyClientData,
|
||
|
wxPropertyGrid::GetPropertyClientData).
|
||
|
- Multi-page management (\ref usage2).
|
||
|
- Setting wxValidator for editor (wxPropertyGrid::SetPropertyValidator).
|
||
|
- Changing editor of property (wxPropertyGrid::SetPropertyEditor).
|
||
|
- Property's value bitmap - small image shown in front of the value text
|
||
|
(wxPropertyGrid::SetPropertyImage).
|
||
|
- Help text shown in parent frame's status bar or in manager's description
|
||
|
text box (wxPropertyGrid::SetPropertyHelpString, wxPropertyGrid::GetPropertyHelpString).
|
||
|
- Changing set of choices used by wxEnumProperty, wxEditEnumProperty or wxMultiChoiceProperty
|
||
|
(wxPropertyGrid::SetPropertyChoices).
|
||
|
- Changing background colour of property's cell (wxPropertyGrid::SetPropertyColour).
|
||
|
- Setting property text max length (wxPropertyGrid::SetPropertyMaxLength)
|
||
|
- Hiding a property (wxPropertyGrid::HideProperty)
|
||
|
- Setting property attributes (\ref attributes)
|
||
|
- Populating wxPropertyGrid (\ref populating).
|
||
|
|
||
|
\section basics Creating and Populating wxPropertyGrid (updated!)
|
||
|
|
||
|
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( wxStringProperty(wxT("Label"),wxT("Name"),wxT("Initial Value")) );
|
||
|
\endcode
|
||
|
|
||
|
wxStringProperty is a factory function that creates a property instance of
|
||
|
a property class "wxStringProperty". Only the first function argument (label)
|
||
|
is mandatory. When necessary, name defaults to label and initial value to
|
||
|
default value. If 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). Empty name is also allowed, but in this case the
|
||
|
property cannot be accessed by its name.
|
||
|
|
||
|
To demonstrate other common property classes, here's another code snippet:
|
||
|
|
||
|
\code
|
||
|
|
||
|
// Add int property
|
||
|
pg->Append( wxIntProperty(wxT("IntProperty"), wxPG_LABEL, 12345678) );
|
||
|
|
||
|
// Add float property (value type is actually double)
|
||
|
pg->Append( wxFloatProperty(wxT("FloatProperty"), wxPG_LABEL, 12345.678) );
|
||
|
|
||
|
// Add a bool property
|
||
|
pg->Append( wxBoolProperty(wxT("BoolProperty"), wxPG_LABEL, false) );
|
||
|
|
||
|
// A string property that can be edited in a separate editor dialog.
|
||
|
pg->Append( 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( wxDirProperty(wxT("DirProperty"), wxPG_LABEL, ::wxGetUserHome()) );
|
||
|
|
||
|
// A file selector property.
|
||
|
pg->Append( 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
|
||
|
|
||
|
All operations on properties should be done via wxPropertyGrid's
|
||
|
(or wxPropertyGridManager's) methods. Class reference of the base property
|
||
|
class should only be interesting for those creating custom property classes.
|
||
|
|
||
|
Property operations, such as SetPropertyValue or DisableProperty,
|
||
|
all have two versions: one which accepts property id (of type wxPGId) and
|
||
|
another that accepts property name. Id is faster since it doesn't require
|
||
|
hash map lookup, but name is often much more convenient.
|
||
|
|
||
|
You can get property id as Append/Insert return value, or by calling
|
||
|
GetPropertyByName.
|
||
|
|
||
|
Below are samples for using some of the more commong operations. See
|
||
|
wxPropertyContainerMethods and wxPropertyGrid class references for complete list.
|
||
|
|
||
|
\code
|
||
|
|
||
|
wxPGId MyPropertyId = pg->GetPropertyByName( wxT("MyProperty") );
|
||
|
|
||
|
// There are many overloaded versions of this method, of which each accept
|
||
|
// different type of value.
|
||
|
// NOTE: If type of MyProperty is not "long", then this will yield a
|
||
|
// run-time error message.
|
||
|
pg->SetPropertyValue( wxT("MyProperty"), 200 );
|
||
|
|
||
|
// Setting a string works for all properties - conversion is done
|
||
|
// automatically.
|
||
|
pg->SetPropertyValue( MyPropertyId, 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( MyPropertyId );
|
||
|
|
||
|
// 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.
|
||
|
pg->DisableProperty( MyPropertyId );
|
||
|
|
||
|
// Set property as read-only.
|
||
|
pg->SetPropertyReadOnly( MyPropertyId );
|
||
|
|
||
|
\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( wxPropertyCategory(wxT("Main")) );
|
||
|
|
||
|
// All these are added to "Main" category
|
||
|
pg->Append( wxStringProperty(wxT("Name")) );
|
||
|
pg->Append( wxIntProperty(wxT("Age"),wxPG_LABEL,25) );
|
||
|
pg->Append( wxIntProperty(wxT("Height"),wxPG_LABEL,180) );
|
||
|
pg->Append( wxIntProperty(wxT("Weight")) );
|
||
|
|
||
|
// Another way
|
||
|
pg->AppendCategory( wxT("Attributes") );
|
||
|
|
||
|
// All these are added to "Attributes" category
|
||
|
pg->Append( wxIntProperty(wxT("Intelligence")) );
|
||
|
pg->Append( wxIntProperty(wxT("Agility")) );
|
||
|
pg->Append( wxIntProperty(wxT("Strength")) );
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
|
||
|
\section parentprops Parent Properties
|
||
|
|
||
|
If you want to combine number of properties under single parent (just
|
||
|
like wxFontProperty combines font attributes), then the easiest way to
|
||
|
proceed is to use wxParentProperty.
|
||
|
|
||
|
\remarks
|
||
|
- wxParentProperty's value type is string, in which
|
||
|
a child property that has children of its own will be embedded in
|
||
|
braces ([]).
|
||
|
- Children of wxParentProperty cannot be accessed globally by their name.
|
||
|
Instead, use "Parent.Child" format.
|
||
|
- However, events occur for the children, not the parent. In addition
|
||
|
to GetPropertyParent, You can use wxPropertyGridEvent::GetMainParent()
|
||
|
to find out property's highest wxParentProperty or wxCustomProperty.
|
||
|
|
||
|
Sample:
|
||
|
|
||
|
\code
|
||
|
wxPGId pid = pg->Append( wxParentProperty(wxT("Car"),wxPG_LABEL) );
|
||
|
|
||
|
pg->AppendIn( pid, wxStringProperty(wxT("Model")),
|
||
|
wxPG_LABEL,
|
||
|
wxT("Lamborghini Diablo SV")) );
|
||
|
|
||
|
pg->AppendIn( pid, wxIntProperty(wxT("Engine Size (cc)"),
|
||
|
wxPG_LABEL,
|
||
|
5707) );
|
||
|
|
||
|
wxPGId speedId = pg->AppendIn( pid, wxParentProperty(wxT("Speeds"),wxPG_LABEL) );
|
||
|
pg->AppendIn( speedId, wxIntProperty(wxT("Max. Speed (mph)"),wxPG_LABEL,300) );
|
||
|
pg->AppendIn( speedId, wxFloatProperty(wxT("0-100 mph (sec)"),wxPG_LABEL,3.9) );
|
||
|
pg->AppendIn( speedId, wxFloatProperty(wxT("1/4 mile (sec)"),wxPG_LABEL,8.6) );
|
||
|
|
||
|
pg->AppendIn( pid, 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) 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( wxEnumProperty(wxT("Diet"),
|
||
|
wxPG_LABEL,
|
||
|
arrDiet) );
|
||
|
|
||
|
|
||
|
|
||
|
//
|
||
|
// Using wxChar* array
|
||
|
//
|
||
|
const wxChar* arrayDiet[] =
|
||
|
{ wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
|
||
|
|
||
|
pg->Append( 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( 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 };
|
||
|
|
||
|
pg->Append( 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 it directly as well, filling it and then passing it to the
|
||
|
factory function.
|
||
|
|
||
|
\code
|
||
|
|
||
|
wxPGChoices chs;
|
||
|
chs.Add(wxT("Herbivore"),40);
|
||
|
chs.Add(wxT("Carnivore"),45);
|
||
|
chs.Add(wxT("Omnivore"),50);
|
||
|
|
||
|
// Note: you can add even whole arrays to wxPGChoices
|
||
|
|
||
|
pg->Append( wxEnumProperty(wxT("Diet"),
|
||
|
wxPG_LABEL,
|
||
|
chs) );
|
||
|
|
||
|
// Add same choices to another property as well - this is efficient due
|
||
|
// to reference counting
|
||
|
pg->Append( 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 has string values.
|
||
|
|
||
|
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( 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 Advanced 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>
|
||
|
|
||
|
...
|
||
|
|
||
|
// wxArrayStringProperty embeds a wxArrayString.
|
||
|
pg->Append( wxArrayStringProperty(wxT("Label of ArrayStringProperty"),
|
||
|
wxT("NameOfArrayStringProp")));
|
||
|
|
||
|
// Date property.
|
||
|
// NB: This will use wxDatePickerCtrl only if wxPG_ALLOW_WXADV is defined
|
||
|
// in propgrid.h or in the library project settings.
|
||
|
pg->Append( 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( wxImageFileProperty(wxT("Label of ImageFileProperty"),
|
||
|
wxT("NameOfImageFileProp")));
|
||
|
|
||
|
// Font property has sub-properties. Note that we give window's font as
|
||
|
// initial value.
|
||
|
pg->Append( wxFontProperty(wxT("Font"),
|
||
|
wxPG_LABEL,
|
||
|
GetFont()) );
|
||
|
|
||
|
// Colour property with arbitrary colour.
|
||
|
pg->Append( wxColourProperty(wxT("My Colour 1"),
|
||
|
wxPG_LABEL,
|
||
|
wxColour(242,109,0) ) );
|
||
|
|
||
|
// System colour property.
|
||
|
pg->Append( wxSystemColourProperty (wxT("My SysColour 1"),
|
||
|
wxPG_LABEL,
|
||
|
wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
|
||
|
|
||
|
// System colour property with custom colour.
|
||
|
pg->Append( wxSystemColourProperty (wxT("My SysColour 2"),
|
||
|
wxPG_LABEL,
|
||
|
wxColour(0,200,160) ) );
|
||
|
|
||
|
// Cursor property
|
||
|
pg->Append( wxCursorProperty (wxT("My Cursor"),
|
||
|
wxPG_LABEL,
|
||
|
wxCURSOR_ARROW));
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
|
||
|
\section operations More About Operating with Properties
|
||
|
|
||
|
Example of iterating through all properties (that are not category captions or
|
||
|
sub-property items):
|
||
|
|
||
|
\code
|
||
|
|
||
|
wxPGId id = pg->GetFirstProperty();
|
||
|
|
||
|
while ( id.IsOk() )
|
||
|
{
|
||
|
// Do something with property id
|
||
|
|
||
|
...
|
||
|
|
||
|
// Get next
|
||
|
pg->GetNextProperty( id );
|
||
|
}
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
Getting value of selected wxSystemColourProperty (which value type is derived
|
||
|
from wxObject):
|
||
|
|
||
|
\code
|
||
|
|
||
|
wxPGId id = pg->GetSelection();
|
||
|
|
||
|
if ( id.IsOk() )
|
||
|
{
|
||
|
|
||
|
// Get name of property
|
||
|
const wxString& name = pg->GetPropertyName( id );
|
||
|
|
||
|
// If type is not correct, GetColour() method will produce run-time error
|
||
|
if ( pg->IsPropertyValueType( id, CLASSINFO(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
|
||
|
|
||
|
|
||
|
\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 )
|
||
|
{
|
||
|
|
||
|
// Get name of changed property
|
||
|
const wxString& name = event.GetPropertyName();
|
||
|
|
||
|
// Get resulting value - wxVariant is convenient here.
|
||
|
wxVariant value = event.GetPropertyValue();
|
||
|
|
||
|
}
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
\remarks On Sub-property Event Handling
|
||
|
- For wxParentProperty and wxCustomProperty, events will occur for
|
||
|
sub-property. For those properties that inherit directly from
|
||
|
wxPGPropertyWithChildren/wxBaseParentPropertyClass (wxFontProperty,
|
||
|
wxFlagsProperty, etc), events occur for the main parent property
|
||
|
only (actually, this has to do whether the children are "private" or not
|
||
|
- see the attributes).
|
||
|
- When wxParentProperty or wxCustomProperty's child gets changed, you can
|
||
|
use wxPropertyGridEvent::GetMainParent to obtain its top non-category
|
||
|
parent (useful, if you have wxParentProperty as child of another
|
||
|
wxParentProperty, for example).
|
||
|
|
||
|
|
||
|
\subsection tofile Saving Population to a Text-based Storage
|
||
|
|
||
|
\code
|
||
|
|
||
|
static void WritePropertiesToMyStorage( wxPropertyGrid* pg, wxPGId id, wxMyStorage& f, int depth )
|
||
|
{
|
||
|
wxString s;
|
||
|
wxString s2;
|
||
|
|
||
|
while ( id.IsOk() )
|
||
|
{
|
||
|
|
||
|
// TODO: Save property into text storage using:
|
||
|
// wxPropertyGrid::GetPropertyClassName
|
||
|
// wxPropertyGrid::GetPropertyName
|
||
|
// wxPropertyGrid::GetPropertyLabel
|
||
|
// wxPropertyGrid::GetPropertyValueAsString
|
||
|
// wxPropertyGrid::GetPropertyChoices
|
||
|
// wxPropertyGrid::GetPropertyAttributes
|
||
|
|
||
|
// Example for adding choices:
|
||
|
wxPGChoices& choices = pg->GetPropertyChoices(id);
|
||
|
if ( choices.IsOk() )
|
||
|
{
|
||
|
// First add id of the choices list inorder to optimize
|
||
|
s2.Printf(wxT("\"%X\""),(unsigned int)choices.GetId());
|
||
|
s.Append(s2);
|
||
|
f.AddToken(s2);
|
||
|
|
||
|
size_t i;
|
||
|
wxArrayString& labels = choices.GetLabels();
|
||
|
wxArrayInt& values = choices.GetValues();
|
||
|
if ( values.GetCount() )
|
||
|
for ( i=0; i<labels.GetCount(); i++ )
|
||
|
{
|
||
|
s2.Printf(wxT("\"%s||%i\""),labels[i].c_str(),values[i]);
|
||
|
f.AddToken(s2);
|
||
|
}
|
||
|
else
|
||
|
for ( i=0; i<labels.GetCount(); i++ )
|
||
|
{
|
||
|
s2.Printf(wxT("\"%s\""),labels[i].c_str());
|
||
|
f.AddToken(s2);
|
||
|
}
|
||
|
}
|
||
|
|
||
|
// Write children, if any
|
||
|
wxPGId firstChild = pg->GetFirstChild(id);
|
||
|
if ( firstChild.IsOk() )
|
||
|
{
|
||
|
WritePropertiesToMyStorage( pg, firstChild, f, depth+1 );
|
||
|
|
||
|
// TODO: Add parent's terminator
|
||
|
}
|
||
|
|
||
|
id = pg->GetNextSibling(id);
|
||
|
}
|
||
|
}
|
||
|
|
||
|
...
|
||
|
|
||
|
// Then you can use this to store the entire hierarchy
|
||
|
wxPGId firstChild = pg->GetFirstChild(pg->GetRoot());
|
||
|
if ( firstChild.IsOk() )
|
||
|
WritePropertiesToFile(pg,first_child,InstanceOfMyStorage,0);
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
For more practical'ish example, see FormMain::OnSaveToFileClick in
|
||
|
propgridsample.cpp.
|
||
|
|
||
|
\subsection fromfile Loading Population from a Text-based Storage
|
||
|
|
||
|
\code
|
||
|
|
||
|
// Recommended when modifying the grid a lot at once
|
||
|
pg->Freeze();
|
||
|
|
||
|
// Necessary if you want a full-page loading
|
||
|
pg->Clear();
|
||
|
|
||
|
wxPropertyGridPopulator populator(pg);
|
||
|
|
||
|
// Store strings from the source here
|
||
|
wxString s_class;
|
||
|
wxString s_name;
|
||
|
wxString s_value;
|
||
|
wxString s_attr;
|
||
|
|
||
|
// Each set of choices loaded must have id
|
||
|
wxPGChoicesId choicesId;
|
||
|
|
||
|
wxArrayString choiceLabels;
|
||
|
wxArrayInt choiceValues;
|
||
|
|
||
|
// Pseudo-code loop to parse the source one "line" at a time
|
||
|
while ( !source.IsAtEnd() )
|
||
|
{
|
||
|
|
||
|
// Clear stuff that doesn't exist at every "line"
|
||
|
choicesId = (wxPGChoicesId) 0;
|
||
|
choiceLabels.Empty();
|
||
|
choiceValues.Empty();
|
||
|
|
||
|
// TODO: Load "line" to variables
|
||
|
|
||
|
// TODO: When a sequence of sibling properties is terminated, call this:
|
||
|
// populator.EndChildren();
|
||
|
|
||
|
// TODO: If had choices, use following code:
|
||
|
// if ( choicesId && !populator.HasChoices(choicesId) )
|
||
|
// {
|
||
|
// populator.AddChoices(choicesId,choiceLabels,choiceValues);
|
||
|
// }
|
||
|
|
||
|
// TODO: Add the property.
|
||
|
// (for sake of simplicity we use here default name for properties)
|
||
|
// populator.AppendByClass(s_class,
|
||
|
// s_name,
|
||
|
// wxPG_LABEL,
|
||
|
// s_value,
|
||
|
// s_attr,
|
||
|
// choicesId);
|
||
|
|
||
|
// TODO: When a sequence of sibling properties begins, call this:
|
||
|
// populator.BeginChildren();
|
||
|
|
||
|
}
|
||
|
|
||
|
pg->Thaw();
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
For more practical'ish example, see FormMain::OnLoadFromFileClick in
|
||
|
propgridsample.cpp.
|
||
|
|
||
|
|
||
|
\section customizing Customizing Properties (without sub-classing)
|
||
|
|
||
|
In this section are presented various ways to have custom appearance
|
||
|
and behaviour 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.
|
||
|
|
||
|
\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 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.
|
||
|
|
||
|
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,(long)1);
|
||
|
\endcode
|
||
|
|
||
|
|
||
|
|
||
|
\section custprop wxCustomProperty
|
||
|
|
||
|
wxCustomProperty allows extra customizing.
|
||
|
|
||
|
- May have children.
|
||
|
|
||
|
For more info on attributes, see \ref attrids. In sample application,
|
||
|
there is a CustomProperty property that has children that can be
|
||
|
used to modify the property itself.
|
||
|
|
||
|
\remarks
|
||
|
- Children of wxParentProperty cannot be accessed globally by their name.
|
||
|
Instead, use "Parent.Child" format.
|
||
|
- However, events occur for the children, not the parent. In addition
|
||
|
to GetPropertyParent, You can use wxPropertyGridEvent::GetMainParent()
|
||
|
to find out property's highest wxParentProperty or wxCustomProperty.
|
||
|
|
||
|
<b>Limitations:</b>
|
||
|
- Currently wxCustomProperty is limited to wxString value type.
|
||
|
- As in wxParentProperty: names of child properties are not visible
|
||
|
globally. You need to use "Parent.SubProperty" name format to access
|
||
|
them.
|
||
|
|
||
|
|
||
|
\section usage2 Using wxPropertyGridManager (Updated!)
|
||
|
|
||
|
wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
|
||
|
which can optionally have toolbar for mode and page selection, help text box,
|
||
|
and a compactor button.
|
||
|
|
||
|
wxPropertyGridManager mirrors most non-visual methods of wxPropertyGrid, some
|
||
|
identically, some so that they can affect a property on any page, and some
|
||
|
so that they can only affect selected target page.
|
||
|
|
||
|
Generally, methods that operate on a property ( such as
|
||
|
GetPropertyValue, SetPropertyValue, EnableProperty, LimitPropertyEditing, Delete, etc. ),
|
||
|
work globally (so the given property can exist on any managed page).
|
||
|
|
||
|
Methods that add properties ( Append, Insert, etc.) or operate on multiple properties
|
||
|
(such as GetPropertyValues or SetPropertyValues), will work in target page only.
|
||
|
Use SetTargetPage(index) method to set current target page. Changing a displayed page
|
||
|
(using SelectPage(index), for example) will automatically set the target page
|
||
|
to the one displayed.
|
||
|
|
||
|
Global methods such as ExpandAll generally work on the target page only.
|
||
|
|
||
|
Visual methods, such as SetCellBackgroundColour and GetNextVisible are only
|
||
|
available in wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain
|
||
|
pointer to it.
|
||
|
|
||
|
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
|
||
|
);
|
||
|
|
||
|
// Adding a page sets target page to the one added, so
|
||
|
// we don't have to call SetTargetPage if we are filling
|
||
|
// it right after adding.
|
||
|
pgMan->AddPage(wxT("First Page"));
|
||
|
|
||
|
pgMan->AppendCategory(wxT("Category A1"));
|
||
|
|
||
|
// Remember, the next line equals pgman->Append( wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
|
||
|
pgMan->Append( wxT("Number"),wxPG_LABEL,1 );
|
||
|
|
||
|
pgMan->Append( wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
|
||
|
|
||
|
pgMan->AddPage(wxT("Second Page"));
|
||
|
|
||
|
pgMan->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
|
||
|
|
||
|
pgMan->Append( wxFontProperty(wxT("Font"),wxPG_LABEL) );
|
||
|
|
||
|
// For total safety, finally reset the target page.
|
||
|
pgMan->SetTargetPage(0);
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
\subsection propgridpage wxPropertyGridPage (New!)
|
||
|
|
||
|
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.
|
||
|
Naturally it inherits from wxPropertyGridMethods and wxPropertyGridState, but, for instance, setting property values is
|
||
|
not yet supported. Use parent manager (m_manager member) instead when needed. Basic property
|
||
|
appending and insertion is supported, however.
|
||
|
|
||
|
|
||
|
\section subclassing Subclassing wxPropertyGrid and wxPropertyGridManager (New!)
|
||
|
|
||
|
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 derivative 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.
|
||
|
|
||
|
|
||
|
\section misc Miscellaneous Topics (Updated!)
|
||
|
|
||
|
\subsection namescope Property Name Scope
|
||
|
|
||
|
- All properties which parent is category or root have their names
|
||
|
globally accessible.
|
||
|
|
||
|
- Sub-properties (i.e. properties which have parent that is not category or
|
||
|
root) can not be accessed globally by their name. Instead, use
|
||
|
"<property>.<subproperty>" in place of "<subproperty>".
|
||
|
|
||
|
\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,(long)1,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 or mouse leaves
|
||
|
the grid.
|
||
|
|
||
|
Because of this, you may find it useful, in some apps, to monitor
|
||
|
wxEVT_COMMAND_TEXT_UPDATED (EVT_TEXT macro) for non-committed changes
|
||
|
in editor. However, the current problem is that pressing Esc in editor
|
||
|
cancels any changes made, thus possibly rendering your knowledge of
|
||
|
changed state incomplete. There is no current, perfect solution for
|
||
|
this problem.
|
||
|
|
||
|
\subsection splittercentering Centering the Splitter (New!)
|
||
|
|
||
|
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)
|
||
|
|
||
|
\subsection compilerdefines Supported Preprocessor Defines
|
||
|
|
||
|
Here is list of supported preprocessor defines (other than those that relate with
|
||
|
wxWidgets core library):
|
||
|
|
||
|
<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_COMPATIBILITY_1_0_0:</b> Define to make wxPropertyGrid more compatible with the
|
||
|
old 1.0.x releases.
|
||
|
|
||
|
|
||
|
\section proplist Property Type Descriptions (Updated!)
|
||
|
|
||
|
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
|
||
|
|
||
|
<b>Inheritable Class:</b> wxPropertyCategoryClass.
|
||
|
|
||
|
Not an actual property per se, but a header for a group of properties.
|
||
|
|
||
|
\subsection wxParentProperty
|
||
|
|
||
|
Pseudo-property that can have sub-properties inserted under itself.
|
||
|
Has textctrl editor that allows editing values of all sub-properties
|
||
|
in a one string. In essence, it is a category that has look and feel
|
||
|
of a property, and which children can be edited via the textctrl.
|
||
|
|
||
|
\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.
|
||
|
|
||
|
\subsection wxIntProperty
|
||
|
|
||
|
Like wxStringProperty, but converts text to a signed long integer.
|
||
|
|
||
|
\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 "$".
|
||
|
|
||
|
\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 1 inorder to use
|
||
|
check box instead.
|
||
|
|
||
|
\subsection wxLongStringProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxLongStringPropertyClass
|
||
|
|
||
|
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
|
||
|
|
||
|
<b>Inheritable Class:</b> wxFilePropertyClass
|
||
|
|
||
|
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 0 inorder to show
|
||
|
only the filename, not the entire path.
|
||
|
|
||
|
\subsection wxEnumProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxEnumPropertyClass
|
||
|
|
||
|
Represents a single selection from a list of choices -
|
||
|
custom combobox control is used to edit the value.
|
||
|
|
||
|
\subsection wxFlagsProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxFlagsPropertyClass
|
||
|
|
||
|
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
|
||
|
|
||
|
<b>Inheritable Class:</b> wxArrayStringPropertyClass
|
||
|
|
||
|
Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
|
||
|
|
||
|
\subsection wxDateProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxDatePropertyClass
|
||
|
|
||
|
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).
|
||
|
|
||
|
<b>
|
||
|
Note that DatePickerCtrl editor depends on wxAdv library, and will only
|
||
|
be used if wxPG_ALLOW_WXADV is defined in propgrid.h or in the library
|
||
|
project settings.
|
||
|
</b>
|
||
|
|
||
|
\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
|
||
|
|
||
|
<b>Inheritable Class:</b> wxMultiChoicePropertyClass
|
||
|
|
||
|
Allows editing a multiple selection from a list of strings. This is
|
||
|
property is pretty much built around concept of wxMultiChoiceDialog.
|
||
|
|
||
|
\subsection wxImageFileProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxImageFilePropertyClass
|
||
|
|
||
|
Like wxFileProperty, but has thumbnail of the image in front of
|
||
|
the filename and autogenerates wildcard from available image handlers.
|
||
|
|
||
|
\subsection wxColourProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> None - instead, see \ref custcolprop.
|
||
|
|
||
|
<b>Useful alternate editor:</b> Choice.
|
||
|
|
||
|
Represents wxColour. wxButton is used to trigger a colour picker dialog.
|
||
|
|
||
|
\subsection wxFontProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxFontPropertyClass
|
||
|
|
||
|
Represents wxFont. Various sub-properties are used to edit individual
|
||
|
subvalues.
|
||
|
|
||
|
\subsection wxSystemColourProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxSystemColourPropertyClass
|
||
|
|
||
|
Represents wxColour and a system colour index. wxChoice is used to edit
|
||
|
the value. Drop-down list has color images.
|
||
|
|
||
|
\subsection wxCursorProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxCursorPropertyPropertyClass
|
||
|
|
||
|
Represents a wxCursor. wxChoice is used to edit the value.
|
||
|
Drop-down list has cursor images under some (wxMSW) platforms.
|
||
|
|
||
|
\subsection wxCustomProperty
|
||
|
|
||
|
<b>Inheritable Class:</b> wxCustomPropertyClass
|
||
|
|
||
|
A customizable property class with string data type. Value image, Editor class,
|
||
|
and children can be modified.
|
||
|
|
||
|
\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 (Updated!)
|
||
|
|
||
|
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.
|
||
|
|
||
|
- 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\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 bugs Known Bugs
|
||
|
NOTE! This section is severely out of date. TODO section in propgrid.cpp has a lot
|
||
|
more of these.
|
||
|
Any insight on these is more than welcome.
|
||
|
- wxGTK: Pressing ESC to unfocus an editor control will screw the focusing
|
||
|
(either focuses back to the editor or moves focus to limbo; works perfectly
|
||
|
on wxMSW though).
|
||
|
- I have experienced a complete freeze when toying with the popup of
|
||
|
wxAdvImageProperty. Visiting another window will end it.
|
||
|
- wxGTK: in sample application, property text colour is not set correct from
|
||
|
wxSystemColourProperty. Value is correct, but the resulting text colour
|
||
|
is sometimes a bit skewed if it is not a shade of gray. This may be GTK's
|
||
|
attempt to auto-adjust it.
|
||
|
- wxGTK: Sometimes '...' text on editor button may disappear (maybe
|
||
|
"invisible font" related thingie). wxAdvImageProperty never seem to get
|
||
|
the text, while other controls do.
|
||
|
Following are wxWidgets or platform bugs:
|
||
|
- wxMSW: After (real) popup window is shown in wxPropertyGrid, grid's scrollbar
|
||
|
won't get hilight until another window is visited. This is probably a Windows
|
||
|
bug.
|
||
|
- wxGTK+ w/ unicode: image handlers return only the first character of an extension
|
||
|
- wxGTK+ 1.2: Controls sometimes disappear. They reappear when cursor is moved
|
||
|
over them.
|
||
|
- wxGTK+ 1.2: Cannot set (multiple) items for wxListBox (affects
|
||
|
wxMultiChoiceProperty).
|
||
|
|
||
|
\section issues Issues
|
||
|
These are not bugs per se, but miscellaneous cross-platform issues that have been
|
||
|
resolved in a less-than-satisfactory manner.
|
||
|
- wxGTK: When selecting wxCursorProperty in sample, there may be
|
||
|
warning: Invalid UTF8 string passed to pango_layout_set_text().
|
||
|
This is probably specific to older versions of GTK.
|
||
|
- Win2K: Pressing Alt+non-registered key combo resulted in app hanging when
|
||
|
wxTAB_TRAVERSAL was used directly. Current solution is not to use it, but
|
||
|
to use wxWANTS_CHARS alone. Strangely enough, this works on wxMSW (but
|
||
|
not wxGTK - precompiler conditional are used to sort things out).
|
||
|
- wxMSW: Toolbar's ToggleTool doesn't disable last item in the same radiogroup. AFAIK,
|
||
|
there is no way to do that (though I didn't do extensive research).
|
||
|
- Atleast with wxGTK2+Unicode+Debug Mode File Selector dialog may trigger an assertion
|
||
|
failure (line 1060 in string.cpp with 2.5.3) that can be cancelled
|
||
|
probably without any ill-effect.
|
||
|
- Under GTK, EVT_MOTION does not trigger for child control. Causes cursor change
|
||
|
inconsistencies. Permanent mouse capture is not practical since it causes wxWindow::
|
||
|
SetCursor to fail (and events cannot be relayed to native controls anyway).
|
||
|
Easy solution used: Splitter drag detect margin and control do not overlap.
|
||
|
- When splitter is being dragged, active editor control (button as well under wxGTK)
|
||
|
is hidden to prevent flickering. This may go unnoticed with some
|
||
|
controls (wxTextCtrl) but is very noticeable with others (wxChoice).
|
||
|
- Under MSW, when resizing, editor controls flicker. No easy fix here
|
||
|
(wxEVT_ONIDLE might be employed).
|
||
|
- Under GTK 1.2, font may show invisible if it is not bold (so it is forced).
|
||
|
- Under wxGTK, controls may flicker a bit (actually, a lot) when being shown.
|
||
|
|
||
|
\section todo Todo
|
||
|
For a detailed TODO, see propertygrid.cpp (just search for "todo" and you'll find it).
|
||
|
|
||
|
\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.
|
||
|
|
||
|
- wxHashMap used to access properties by name uses 'const wxChar*' instead of 'wxString'.
|
||
|
Altough this has somewhat lower performance if used mostly with wxStrings, it is much
|
||
|
faster if a lot of non-wxString strings are used, since they don't have to be
|
||
|
recreated as wxString before using with the hashmap.
|
||
|
If you want to change this behaviour, see propertygrid.h. Comment current version
|
||
|
(including wxPGNameStr), and uncomment version that uses wxString.
|
||
|
Note that with unicode, wxString is always used (due to some weird issues).
|
||
|
|
||
|
- If wxPG_DOUBLE_BUFFER is 1 (default for MSW, GTK and MAC), wxPropertyGrid::OnDrawItems
|
||
|
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 (Updated!)
|
||
|
|
||
|
Easiest solution for creating an arbitrary property is to subclass an existing,
|
||
|
inheritable property that has the desired value type and editor. Property class
|
||
|
to derive from is always property name + Class, for instance wxStringPropertyClass in
|
||
|
case of wxStringProperty. You need to include header file wx/propgrid/propdev.h,
|
||
|
specify a mandatory constructor, and override some virtual member functions (see
|
||
|
wxPGProperty and wxPGPropertyWithChildren).
|
||
|
|
||
|
For instance:
|
||
|
|
||
|
\code
|
||
|
|
||
|
#include <wx/propgrid/propdev.h>
|
||
|
|
||
|
// wxLongStringProperty has wxString as value type and TextCtrlAndButton as editor.
|
||
|
class MyStringPropertyClass : public wxLongStringPropertyClass
|
||
|
{
|
||
|
public:
|
||
|
|
||
|
// Normal property constructor.
|
||
|
MyStringPropertyClass(const wxString& name,
|
||
|
const wxString& label = wxPG_LABEL,
|
||
|
const wxString& value = wxEmptyString)
|
||
|
: wxLongStringPropertyClass(name,label,value)
|
||
|
{
|
||
|
}
|
||
|
|
||
|
// Do something special when button is clicked.
|
||
|
virtual bool OnButtonClick(wxPropertyGrid* propGrid,
|
||
|
wxWindow* primaryCtrl)
|
||
|
{
|
||
|
// Update value in case last minute changes were made.
|
||
|
PrepareValueForDialogEditing(propGrid);
|
||
|
|
||
|
// TODO: Create dialog (m_value has current string, if needed)
|
||
|
|
||
|
int res = dlg.ShowModal();
|
||
|
if ( res == wxID_OK && dlg.IsModified() )
|
||
|
{
|
||
|
DoSetValue(dlg.GetString());
|
||
|
UpdateControl(primaryCtrl);
|
||
|
return true;
|
||
|
}
|
||
|
|
||
|
return false;
|
||
|
}
|
||
|
|
||
|
protected:
|
||
|
};
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
You can then create a property instance with new keyword (as factory function
|
||
|
is absent since macros are not used), for instance:
|
||
|
|
||
|
\code
|
||
|
|
||
|
pg->Append( new MyStringPropertyClass(name,label,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
|
||
|
|
||
|
If you want to change value type used, use code like below.
|
||
|
|
||
|
However, first a word on value types: They are essentially wxPGValueType instances holding
|
||
|
reimplemented member functions for handling specific type of data. Use wxPG_VALUETYPE(ValueType)
|
||
|
to get pointer, altought this should usually not be necessary outside GetValueType. Lightweight
|
||
|
wxPGVariant is used to convey value to (DoSetValue) and from (DoGetValue) property. For common
|
||
|
and small types such as long and bool, the entire value is stored in wxPGVariant. For large
|
||
|
types (even double!), only a pointer is stored. This is sufficient since <b>property instance
|
||
|
is responsible for storing its value</b>.
|
||
|
|
||
|
Built-in value types include: wxString, long, bool, double, void,
|
||
|
wxArrayString. advprops.h also has: wxFont, wxColour, wxArrayInt. See below
|
||
|
for more information about implementing your own value types.
|
||
|
|
||
|
\code
|
||
|
|
||
|
// In class body:
|
||
|
public:
|
||
|
|
||
|
// Minimal constructor must set the new value.
|
||
|
MyPropertyClass(const wxString& name,
|
||
|
const wxString& label = wxPG_LABEL,
|
||
|
UsedDataType value = DefaultValue)
|
||
|
: wxInheritedPropertyClass(name,label,OtherDefaultValue)
|
||
|
{
|
||
|
m_value2 = value;
|
||
|
}
|
||
|
|
||
|
virtual const wxPGValueType* GetValueType() const
|
||
|
{
|
||
|
return wxPG_VALUETYPE(UsedDataType);
|
||
|
}
|
||
|
|
||
|
virtual void DoSetValue(wxPGVariant value)
|
||
|
{
|
||
|
// TODO: Retrieve value from wxPGVariant. For simple types,
|
||
|
// you can use:
|
||
|
//
|
||
|
// UsedDataType val = value.GetFoo(); // Like GetString, or GetLong, similar to wxVariant
|
||
|
//
|
||
|
// For complex types, use:
|
||
|
//
|
||
|
// UsedDataType* pVal = (UsedDataType*) wxPGVariantToVoidPtr(value);
|
||
|
//
|
||
|
// - OR -
|
||
|
//
|
||
|
// UsedDataType* pVal = wxPGVariantToWxObjectPtr(value,UsedDataType);
|
||
|
// wxASSERT(ptr); // Since its NULL if type-checking failed
|
||
|
//
|
||
|
|
||
|
// TODO: Store value to m_value2;
|
||
|
}
|
||
|
|
||
|
virtual wxPGVariant DoGetValue() const
|
||
|
{
|
||
|
// TODO: Return value as wxPGVariant.
|
||
|
//
|
||
|
// For simple types, return the entire value. For example:
|
||
|
//
|
||
|
// return wxPGVariant(m_value2);
|
||
|
//
|
||
|
// For complex types, return pointer. For example:
|
||
|
//
|
||
|
// return wxPGVariant((void*)&m_value2);
|
||
|
}
|
||
|
|
||
|
virtual wxString GetValueAsString(int argFlags) const
|
||
|
{
|
||
|
// TODO: If (argFlags & wxPG_FULL_VALUE), then return storable
|
||
|
// (to config, database, etc) string. Otherwise return
|
||
|
// shown string.
|
||
|
}
|
||
|
|
||
|
virtual bool SetValueFromString(const wxString& text,
|
||
|
int WXUNUSED(argFlags))
|
||
|
{
|
||
|
// TODO: Set value from given string (which is same as previously
|
||
|
// returned from GetValueAsString(wxPG_FULL_VALUE)). Return
|
||
|
// true if value was actually changed.
|
||
|
}
|
||
|
|
||
|
protected:
|
||
|
UsedDataType m_value2;
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
If you want to add support for the internal RTTI scheme, use code like this:
|
||
|
|
||
|
\code
|
||
|
|
||
|
// In private portion of class body:
|
||
|
WX_PG_DECLARE_CLASSINFO()
|
||
|
|
||
|
// In source file:
|
||
|
WX_PG_IMPLEMENT_CLASSINFO(MyStringProperty,wxLongStringProperty)
|
||
|
wxPG_GETCLASSNAME_IMPLEMENTATION(MyStringProperty)
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
|
||
|
\remarks
|
||
|
- For practical examples of arbitrary properties, please take a look
|
||
|
at the sample properties in contrib/samples/propgrid/sampleprops.cpp.
|
||
|
- Read wxPGProperty and wxPGPropertyWithChildren class documentation to
|
||
|
find out what each virtual member function should do.
|
||
|
- Value for property is usually stored in a member named m_value.
|
||
|
- 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
|
||
|
|
||
|
#include <wx/propgrid/propdev.h>
|
||
|
|
||
|
// FLAGS can be wxPG_NO_ESCAPE if escape sequences shall not be expanded.
|
||
|
WX_PG_IMPLEMENT_STRING_PROPERTY(PROPNAME, FLAGS)
|
||
|
|
||
|
bool PROPNAMEClass::OnButtonClick( wxPropertyGrid* propgrid, wxString& value )
|
||
|
{
|
||
|
//
|
||
|
// TODO: Show dialog, read initial string from value. If changed,
|
||
|
// store new string to value and return TRUE.
|
||
|
//
|
||
|
}
|
||
|
\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
|
||
|
|
||
|
#include <wx/propgrid/propdev.h>
|
||
|
|
||
|
WX_PG_IMPLEMENT_STRING_PROPERTY_WITH_VALIDATOR(PROPNAME, FLAGS)
|
||
|
|
||
|
bool PROPNAMEClass::OnButtonClick( wxPropertyGrid* propgrid, wxString& value )
|
||
|
{
|
||
|
//
|
||
|
// TODO: Show dialog, read initial string from value. If changed,
|
||
|
// store new string to value and return TRUE.
|
||
|
//
|
||
|
}
|
||
|
|
||
|
wxValidator* PROPNAMEClass::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
|
||
|
|
||
|
#include <wx/propgrid/propdev.h>
|
||
|
|
||
|
// 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
|
||
|
|
||
|
#include <wx/propgrid/propdev.h>
|
||
|
|
||
|
// 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 wxMyArrayStringPropertyClass::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
|
||
|
|
||
|
#include <wx/propgrid/propdev.h>
|
||
|
|
||
|
// 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
|
||
|
|
||
|
\subsection declaring Declaring an Arbitrary Property
|
||
|
|
||
|
To make your property available globally, you need to declare it in a
|
||
|
header file. Usually you would want to use WX_PG_DECLARE_PROPERTY
|
||
|
macro to do that (it is defined in propgrid.h). It has three arguments: PROPNAME,
|
||
|
T_AS_ARG and DEFVAL. PROPNAME is property NAME (eg. wxStringProperty),
|
||
|
T_AS_ARG is type input in function argument list (eg. "int" for int value type,
|
||
|
"const wxString&" for wxString value type, etc.), and DEFVAL is default value for that.
|
||
|
|
||
|
For example:
|
||
|
|
||
|
\code
|
||
|
|
||
|
// Declare wxRealPoint Property in the header
|
||
|
WX_PG_DECLARE_PROPERTY(wxRealPointProperty,const wxRealPoint&,wxRealPoint(0.0,0.0))
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
There is also WX_PG_DECLARE_PROPERTY_WITH_DECL which takes an additional declaration
|
||
|
argument (export, for example, when exporting from a dll).
|
||
|
|
||
|
If you want that your property could be inherited from, then you would also
|
||
|
have to define the class body in the header file. In most cases this is probably not
|
||
|
necessary and the class can be defined and implemented completely in the source.
|
||
|
In the case of wxPropertyGrid library, most property classes are defined in
|
||
|
propdev.h to allow them to be inherited from, but .
|
||
|
|
||
|
\subsection implementing Implementing a Property
|
||
|
|
||
|
First there is class body with WX_PG_DECLARE_PROPERTY_CLASS macro,
|
||
|
constructor, virtual destructor, and declarations for other overridden
|
||
|
methods. Then comes WX_PG_IMPLEMENT_PROPERTY_CLASS macro, and
|
||
|
after that class method implementations.
|
||
|
|
||
|
\subsection Tips
|
||
|
|
||
|
- To get property's parent grid, call GetGrid().
|
||
|
|
||
|
\subsection valuetypes Creating New Value Types
|
||
|
|
||
|
If you want to a property to use a value type that is not among the
|
||
|
builtin types, then you need to create a new property value type. It is
|
||
|
quite straightforward, using two macros.
|
||
|
|
||
|
In header, use WX_PG_DECLARE_VALUE_TYPE(DATATYPE), like this:
|
||
|
|
||
|
\code
|
||
|
// Example: Declare value type for wxRealPoint.
|
||
|
WX_PG_DECLARE_VALUE_TYPE(wxRealPoint)
|
||
|
\endcode
|
||
|
|
||
|
If, however, class of your value type does not inherit from
|
||
|
wxObject, and you need to use it in wxVariant list used as a
|
||
|
persistent storage (for example, see wxPropertyGrid::GetPropertyValues),
|
||
|
then use this instead, as it also declares a necessary wxVariantData_DATATYPE
|
||
|
class.
|
||
|
|
||
|
\code
|
||
|
// Example: Declare value type and wxVariantData class for wxRealPoint.
|
||
|
WX_PG_DECLARE_VALUE_TYPE_VOIDP(wxRealPoint)
|
||
|
\endcode
|
||
|
|
||
|
There are also _WITH_DECL versions of both.
|
||
|
|
||
|
However, there are a few different implement macros to place in
|
||
|
a source file. Pick one according to the type of type.
|
||
|
|
||
|
\code
|
||
|
|
||
|
// For implementing value type for a wxObject based class.
|
||
|
WX_PG_IMPLEMENT_VALUE_TYPE_WXOBJ(TYPE,DEFPROPERTY,DEFVAL)
|
||
|
|
||
|
// Same as above, except that an instance of TYPE is
|
||
|
// stored in class. Thus, DEFVAL can be any expression
|
||
|
// that can be assigned to the type.
|
||
|
WX_PG_IMPLEMENT_VALUE_TYPE_WXOBJ_OWNDEFAULT(TYPE,DEFPROPERTY,DEFVAL)
|
||
|
|
||
|
// For implementing value type for a non-wxObject based class.
|
||
|
// Like with ...WXOBJ_OWNDEFAULT macro above, instance of TYPE
|
||
|
// is stored and DEFVAL can be any expression.
|
||
|
WX_PG_IMPLEMENT_VALUE_TYPE_VOIDP_SIMPLE(TYPE,DEFPROPERTY,DEFVAL)
|
||
|
|
||
|
// Like above, but also implement the wxVariantData class
|
||
|
// declared with the second kind of value type declare macro.
|
||
|
WX_PG_IMPLEMENT_VALUE_TYPE_VOIDP(TYPE,DEFPROPERTY,DEFVAL)
|
||
|
|
||
|
// Like above, but accepts a custom wxVariantData class.
|
||
|
// You need to use WX_PG_DECLARE_VALUE_TYPE with this instead
|
||
|
// of _VOIDP version.
|
||
|
WX_PG_IMPLEMENT_VALUE_TYPE_VOIDP_CVD(TYPE,DEFPROPERTY,DEFVAL,VARIANTDATACLASS)
|
||
|
|
||
|
// For implementing value type with different default value.
|
||
|
// NOTE: With this type you need to use wxPG_INIT_REQUIRED_TYPE2
|
||
|
// instead of wxPG_INIT_REQUIRED_TYPE.
|
||
|
WX_PG_IMPLEMENT_DERIVED_TYPE(TYPENAME,PARENTVT,DEFVAL)
|
||
|
|
||
|
// For implementing value type for a POD (plain 'ol data) value.
|
||
|
// Generally should not be used since it is meant for
|
||
|
// wxString, int, double etc. which are already implemented.
|
||
|
WX_PG_IMPLEMENT_VALUE_TYPE(TYPE,DEFPROPERTY,TYPESTRING,GETTER,DEFVAL)
|
||
|
|
||
|
\endcode
|
||
|
|
||
|
Argument descriptions:
|
||
|
|
||
|
TYPE - Actual data type represented by the value type, or if
|
||
|
derived type, any custom name.
|
||
|
|
||
|
DEFPROPERY - Name of the property that will edit this
|
||
|
value type by default.
|
||
|
|
||
|
DEFVAL - Default value for the property.
|
||
|
|
||
|
TYPENAME - An arbitraty typename for this value type. Applies
|
||
|
only to the derived type.
|
||
|
|
||
|
PARENTVT - Name of parent value type, from which this derived
|
||
|
type inherits from.
|
||
|
|
||
|
\remarks
|
||
|
- Your class, which you create value type for, must have a
|
||
|
copy constructor.
|
||
|
|
||
|
\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__
|
||
|
|