proplist.tex

Wxpython Implemented on Windows CE, Source code

\chapter{Property sheet classes}\label{proplist}

\section{Introduction}\label{proplistintro}

The Property Sheet Classes help the programmer to specify complex dialogs and
their relationship with their associated data. By specifying data as a
wxPropertySheet containing wxProperty objects, the programmer can use
a range of available or custom wxPropertyView classes to allow the user to
edit this data. Classes derived from wxPropertyView act as mediators between the
wxPropertySheet and the actual window (and associated panel items).

For example, the wxPropertyListView is a kind of wxPropertyView which displays
data in a Visual Basic-style property list (see \helpref{the next section}{proplistappearance} for
screen shots). This is a listbox containing names and values, with
an edit control and other optional controls via which the user edits the selected
data item.

wxPropertyFormView is another kind of wxPropertyView which mediates between
the data and a panel or dialog box which has already been created. This makes it a contender for
the replacement of wxForm, since programmer-controlled layout is going to be much more
satisfactory. If automatic layout is desired, then wxPropertyListView could be used instead.

The main intention of this class library was to provide property {\it list} behaviour, but
it has been generalised as much as possible so that the concept of a property sheet and its viewers
can reduce programming effort in a range of user interface tasks.

For further details on the classes and how they are used, please see \helpref{Property classes overview}{proplistpropertyoverview}.

\subsection{The appearance and behaviour of a property list view}\label{proplistappearance}

The property list, as seen in an increasing number of development tools
such as Visual Basic and Delphi, is a convenient and compact method for
displaying and editing a number of items without the need for one
control per item, and without the need for designing a special form. The
controls are as follows:

\begin{itemize}\itemsep=0pt
\item A listbox showing the properties and their current values, which has double-click
properties dependent on the nature of the current property;
\item a text editing area at the top of the display, allowing the user to edit
the currently selected property if appropriate;
\item `confirm' and `cancel' buttons to confirm or cancel an edit (for the property, not the
whole sheet);
\item an optional list that appears when the user can make a choice from several known possible values;
\item a small Edit button to invoke `detailed editing' (perhaps showing or hiding the above value list, or
maybe invoking a common dialog);
\item optional OK/Close, Cancel and Help buttons for the whole dialog.
\end{itemize}

The concept of `detailed editing' versus quick editing gives the user a choice
of editing mode, so novice and expert behaviour can be catered for, or the user can just
use what he feels comfortable with.

Behaviour alters depending on the kind of property being edited. For example, a boolean value has
the following behaviour:

\begin{itemize}\itemsep=0pt
\item Double-clicking on the item toggles between true and false.
\item Showing the value list enables the user to select true or false.
\item The user may be able to type in the word true or false, or the edit control
may be read-only to disallow this since it is error-prone.
\end{itemize}

A list of strings may pop up a dialog for editing them, a simple string just allows text editing,
double-clicking a colour property may show a colour selector, double-clicking on a filename property may
show a file selector (in addition to being able to type in the name in the edit control), etc.

Note that the `type' of property, such as string or integer, does not
necessarily determine the behaviour of the property. The programmer has
to be able to specify different behaviours for the same type, depending
on the meaning of the property. For example, a colour and a filename may
both be strings, but their editing behaviour should be different. This
is why objects of type wxPropertyValidator need to be used, to define
behaviour for a given class of properties or even specific property
name.  Objects of class wxPropertyView contain a list of property
registries, which enable reuse of bunches of these validators in
different circumstances. Or a wxProperty can be explicitly set to use a
particular validator object. 

The following screen shot of the property classes test program shows the
user editing a string, which is constrained to be one of three possible
values.

\helponly{\image{}{prop1.bmp}}

The second picture shows the user having entered a integer that
was outside the range specified to the validator. Note that in this picture,
the value list is hidden because it is not used when editing an integer.

\helponly{\image{}{prop2.bmp}}

\section{Headers}\label{proplistfiles}

The property class library comprises the following files:

\begin{itemize}\itemsep=0pt
\item prop.h: base property class header
\item proplist.h: wxPropertyListView and associated classes
\item propform.h: wxPropertyListView and associated classes
\end{itemize}

\section{Topic overviews}\label{proplistoverviews}

This chapter contains a selection of topic overviews.

\subsection{Property classes overview}\label{proplistpropertyoverview}

The property classes help a programmer to express relationships between
data and physical windows, in particular:

\begin{itemize}\itemsep=0pt
\item the transfer of data to and from the physical controls;
\item the behaviour of various controls and custom windows for particular
types of data;
\item the validation of data, notifying the user when incorrect data is entered,
or even better, constraining the input so only valid data can be entered.
\end{itemize}

With a consistent framework, the programmer should be able to use existing
components and design new ones in a principled manner, to solve many data entry
requirements.

Each datum is represented in a \helpref{wxProperty}{wxproperty}, which has a name and a value.
Various C++ types are permitted in the value of a property, and the property can store a pointer
to the data instead of a copy of the data. A \helpref{wxPropertySheet}{wxpropertysheet} represents a number of these properties.

These two classes are independent from the way in which the data is visually manipulated. To
mediate between property sheets and windows, the abstract class \helpref{wxPropertyView}{wxpropertyview} is
available for programmers to derive new kinds of view. One kind of view that is available is the \helpref{wxPropertyListView}{wxpropertylistview},
which displays the data in a Visual Basic-style list, with a small number of controls for editing
the currently selected property. Another is \helpref{wxPropertyFormView}{wxpropertyformview} which
mediates between an existing dialog or panel and the property sheet.

The hard work of mediation is actually performed by validators, which are instances of classes
derived from \helpref{wxPropertyValidator}{wxpropertyvalidator}. A validator is associated with
a particular property and is responsible for
responding to user interface events, and displaying, updating and checking the property value.
Because a validator's behaviour depends largely on the kind of view being used, there has to be
a separate hierarchy of validators for each class of view. So for wxPropertyListView, there is
an abstract class \helpref{wxPropertyListValidator}{wxpropertylistvalidator} from which concrete
classes are derived, such as \helpref{wxRealListValidator}{wxreallistvalidator} and
\rtfsp\helpref{wxStringListValidator}{wxstringlistvalidator}.

A validator can be explicitly set for a property, so there is no doubt which validator
should be used to edit that property. However, it is also possible to define a registry
of validators, and have the validator chosen on the basis of the {\it role} of the property.
So a property with a ``filename" role would match the ``filename" validator, which pops
up a file selector when the user double clicks on the property.

You don't have to define your own frame or window classes: there are some predefined
that will work with the property list view. See \helpref{Window classes}{proplistwindowclasses} for
further details.

\subsubsection{Example 1: Property list view}

The following code fragment shows the essentials of creating a registry of
standard validators, a property sheet containing some properties, and
a property list view and dialog or frame. RegisterValidators will be
called on program start, and PropertySheetTest is called in response to a
menu command.

Note how some properties are created with an explicit reference to
a validator, and others are provided with a ``role'' which can be matched
against a validator in the registry.

The interface generated by this test program is shown in the section \helpref{Appearance and
behaviour of a property list view}{proplistappearance}.

\begin{verbatim}
void RegisterValidators(void)
{
  myListValidatorRegistry.RegisterValidator((wxString)"real", new wxRealListValidator);
  myListValidatorRegistry.RegisterValidator((wxString)"string", new wxStringListValidator);
  myListValidatorRegistry.RegisterValidator((wxString)"integer", new wxIntegerListValidator);
  myListValidatorRegistry.RegisterValidator((wxString)"bool", new wxBoolListValidator);
}

void PropertyListTest(Bool useDialog)
{
  wxPropertySheet *sheet = new wxPropertySheet;

  sheet->AddProperty(new wxProperty("fred", 1.0, "real"));
  sheet->AddProperty(new wxProperty("tough choice", (Bool)true, "bool"));
  sheet->AddProperty(new wxProperty("ian", (long)45, "integer", new wxIntegerListValidator(-50, 50)));
  sheet->AddProperty(new wxProperty("bill", 25.0, "real", new wxRealListValidator(0.0, 100.0)));
  sheet->AddProperty(new wxProperty("julian", "one", "string"));
  sheet->AddProperty(new wxProperty("bitmap", "none", "string", new wxFilenameListValidator("Select a bitmap file", "*.bmp")));
  wxStringList *strings = new wxStringList("one", "two", "three", NULL);
  sheet->AddProperty(new wxProperty("constrained", "one", "string", new wxStringListValidator(strings)));

  wxPropertyListView *view =
    new wxPropertyListView(NULL,
     wxPROP_BUTTON_CHECK_CROSS|wxPROP_DYNAMIC_VALUE_FIELD|wxPROP_PULLDOWN);

  wxDialogBox *propDialog = NULL;
  wxPropertyListFrame *propFrame = NULL;
  if (useDialog)
  {
    propDialog = new wxPropertyListDialog(view, NULL, "Property Sheet Test", true, -1, -1, 400, 500);
  }
  else
  {
    propFrame = new wxPropertyListFrame(view, NULL, "Property Sheet Test", -1, -1, 400, 500);
  }
  
  view->AddRegistry(&myListValidatorRegistry);

  if (useDialog)
  {
    view->ShowView(sheet, propDialog);
    propDialog->Centre(wxBOTH);
    propDialog->Show(true);
  }
  else
  {
    propFrame->Initialize();
    view->ShowView(sheet, propFrame->GetPropertyPanel());
    propFrame->Centre(wxBOTH);
    propFrame->Show(true);
  }
}
\end{verbatim}

\subsubsection{Example 2: Property form view}

This example is similar to Example 1, but uses a property form view to
edit a property sheet using a predefined dialog box.

\begin{verbatim}
void RegisterValidators(void)
{
  myFormValidatorRegistry.RegisterValidator((wxString)"real", new wxRealFormValidator);
  myFormValidatorRegistry.RegisterValidator((wxString)"string", new wxStringFormValidator);
  myFormValidatorRegistry.RegisterValidator((wxString)"integer", new wxIntegerFormValidator);
  myFormValidatorRegistry.RegisterValidator((wxString)"bool", new wxBoolFormValidator);
}

void PropertyFormTest(Bool useDialog)
{
  wxPropertySheet *sheet = new wxPropertySheet;

  sheet->AddProperty(new wxProperty("fred", 25.0, "real", new wxRealFormValidator(0.0, 100.0)));
  sheet->AddProperty(new wxProperty("tough choice", (Bool)true, "bool"));
  sheet->AddProperty(new wxProperty("ian", (long)45, "integer", new wxIntegerFormValidator(-50, 50)));
  sheet->AddProperty(new wxProperty("julian", "one", "string"));
  wxStringList *strings = new wxStringList("one", "two", "three", NULL);
  sheet->AddProperty(new wxProperty("constrained", "one", "string", new wxStringFormValidator(strings)));

  wxPropertyFormView *view = new wxPropertyFormView(NULL);

  wxDialogBox *propDialog = NULL;
  wxPropertyFormFrame *propFrame = NULL;
  if (useDialog)
  {
    propDialog = new wxPropertyFormDialog(view, NULL, "Property Form Test", true, -1, -1, 400, 300);
  }
  else
  {
    propFrame = new wxPropertyFormFrame(view, NULL, "Property Form Test", -1, -1, 400, 300);
    propFrame->Initialize();
  }
  
  wxPanel *panel = propDialog ? propDialog : propFrame->GetPropertyPanel();
  panel->SetLabelPosition(wxVERTICAL);
  
  // Add items to the panel
  
  (void) new wxButton(panel, (wxFunction)NULL, "OK", -1, -1, -1, -1, 0, "ok");
  (void) new wxButton(panel, (wxFunction)NULL, "Cancel", -1, -1, 80, -1, 0, "cancel");
  (void) new wxButton(panel, (wxFunction)NULL, "Update", -1, -1, 80, -1, 0, "update");
  (void) new wxButton(panel, (wxFunction)NULL, "Revert", -1, -1, -1, -1, 0, "revert");
  panel->NewLine();
  
  // The name of this text item matches the "fred" property
  (void) new wxText(panel, (wxFunction)NULL, "Fred", "", -1, -1, 90, -1, 0, "fred");
  (void) new wxCheckBox(panel, (wxFunction)NULL, "Yes or no", -1, -1, -1, -1, 0, "tough choice");
  (void) new wxSlider(panel, (wxFunction)NULL, "Sliding scale", 0, -50, 50, 100, -1, -1, wxHORIZONTAL, "ian");
  panel->NewLine();
  (void) new wxListBox(panel, (wxFunction)NULL, "Constrained", wxSINGLE, -1, -1, 100, 90, 0, NULL, 0, "constrained");