proplist.tex

Wxpython Implemented on Windows CE, Source code

  view->AddRegistry(&myFormValidatorRegistry);

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

\subsection{Validator classes overview}\label{proplistvalidatoroverview}

Classes: \helpref{Validator classes}{proplistvalidatorclasses}

The validator classes provide functionality for mediating between a wxProperty and
the actual display. There is a separate family of validator classes for each
class of view, since the differences in user interface for these views implies
that little common functionality can be shared amongst validators.



\subsubsection{wxPropertyValidator overview}\label{wxpropertyvalidatoroverview}

Class: \helpref{wxPropertyValidator}{wxpropertyvalidator}

This class is the root of all property validator classes. It contains a small
amount of common functionality, including functions to convert between
strings and C++ values.

A validator is notionally an object which sits between a property and its displayed
value, and checks that the value the user enters is correct, giving an error message
if the validation fails. In fact, the validator does more than that, and is akin to
a view class but at a finer level of detail. It is also responsible for
loading the dialog box control with the value from the property, putting it back
into the property, preparing special controls for editing the value, and
may even invoke special dialogs for editing the value in a convenient way.

In a property list dialog, there is quite a lot of scope for supplying custom dialogs,
such as file or colour selectors. For a form dialog, there is less scope because
there is no concept of `detailed editing' of a value: one control is associated with
one property, and there is no provision for invoking further dialogs. The reader
may like to work out how the form view could be extended to provide some of the
functionality of the property list!

Validator objects may be associated explicitly with a wxProperty, or they may be
indirectly associated by virtue of a property `kind' that matches validators having
that kind. In the latter case, such validators are stored in a validator registry
which is passed to the view before the dialog is shown. If the validator takes
arguments, such as minimum and maximum values in the case of a wxIntegerListValidator,
then the validator must be associated explicitly with the property. The validator
will be deleted when the property is deleted.

\subsubsection{wxPropertyListValidator overview}\label{wxpropertylistvalidatoroverview}

Class: \helpref{wxPropertyListValidator}{wxpropertylistvalidator}

This class is the abstract base class for property list view validators.
The list view acts upon a user interface containing a list of properties,
a text item for direct property value editing, confirm/cancel buttons for the value,
a pulldown list for making a choice between values, and OK/Cancel/Help buttons
for the dialog (see \helpref{property list appearance}{proplistappearance}).

By overriding virtual functions, the programmer can create custom
behaviour for different kinds of property. Custom behaviour can use just the
available controls on the property list dialog, or the validator can
invoke custom editors with quite different controls, which pop up in
`detailed editing' mode.

See the detailed class documentation for the members you should override
to give your validator appropriate behaviour.

\subsubsection{wxPropertyFormValidator overview}\label{wxpropertyformvalidatoroverview}

This class is the abstract base class for property form view validators.
The form view acts upon an existing dialog box or panel, where either the
panel item names correspond to property names, or the programmer has explicitly
associated the panel item with the property.

By overriding virtual functions, the programmer determines how
values are displayed or retrieved, and the checking that the validator does.

See the detailed class documentation for the members you should override
to give your validator appropriate behaviour.

\subsection{View classes overview}\label{proplistviewoverview}

Classes: \helpref{View classes}{proplistviewclasses}

An instance of a view class relates a property sheet with an actual window.
Currently, there are two classes of view: wxPropertyListView and wxPropertyFormView.

\subsubsection{wxPropertyView overview}\label{wxpropertyviewoverview}

Class: \helpref{wxPropertyView}{wxpropertyview}

This is the abstract base class for property views.

\subsubsection{wxPropertyListView overview}\label{wxpropertylistviewoverview}

Class: \helpref{wxPropertyListView}{wxpropertylistview}

The property list view defines the relationship between a property sheet and
a property list dialog or panel. It manages user interface events such as
clicking on a property, pressing return in the text edit field, and clicking
on Confirm or Cancel. These events cause member functions of the
class to be called, and these in turn may call member functions of
the appropriate validator to be called, to prepare controls, check the property value,
invoke detailed editing, etc.

\subsubsection{wxPropertyFormView overview}\label{wxpropertyformviewoverview}

Class: \helpref{wxPropertyFormView}{wxpropertyformview}

The property form view manages the relationship between a property sheet
and an existing dialog or panel.

You must first create a panel or dialog box for the view to work on.
The panel should contain panel items with names that correspond to
properties in your property sheet; or you can explicitly set the
panel item for each property.

Apart from any custom panel items that you wish to control independently
of the property-editing items, wxPropertyFormView takes over the
processing of item events. It can also control normal dialog behaviour such
as OK, Cancel, so you should also create some standard buttons that the property view
can recognise. Just create the buttons with standard names and the view
will do the rest. The following button names are recognised:

\begin{itemize}\itemsep=0pt
\item {\bf ok}: indicates the OK button. Calls wxPropertyFormView::OnOk. By default,
checks and updates the form values, closes and deletes the frame or dialog, then deletes the view.
\item {\bf cancel}: indicates the Cancel button. Calls wxPropertyFormView::OnCancel. By default,
closes and deletes the frame or dialog, then deletes the view.
\item {\bf help}: indicates the Help button. Calls wxPropertyFormView::OnHelp. This needs
to be overridden by the application for anything interesting to happen.
\item {\bf revert}: indicates the Revert button. Calls wxPropertyFormView::OnRevert,
which by default transfers the wxProperty values to the panel items (in effect
undoing any unsaved changes in the items).
\item {\bf update}: indicates the Revert button. Calls wxPropertyFormView::OnUpdate, which
by defaults transfers the displayed values to the wxProperty objects.
\end{itemize}

\subsection{wxPropertySheet overview}\label{wxpropertysheetoverview}

Classes: \helpref{wxPropertySheet}{wxpropertysheet}, \helpref{wxProperty}{wxproperty}, \helpref{wxPropertyValue}{wxpropertyvalue}

A property sheet defines zero or more properties. This is a bit like an explicit representation of
a C++ object. wxProperty objects can have values which are pointers to C++ values, or they
can allocate their own storage for values.

Because the property sheet representation is explicit and can be manipulated by
a program, it is a convenient form to be used for a variety of
editing purposes. wxPropertyListView and wxPropertyFormView are two classes that
specify the relationship between a property sheet and a user interface. You could imagine
other uses for wxPropertySheet, for example to generate a form-like user interface without
the need for GUI programming. Or for storing the names and values of command-line switches, with the
option to subsequently edit these values using a wxPropertyListView.

A typical use for a property sheet is to represent values of an object
which are only implicit in the current representation of it. For
example, in Visual Basic and similar programming environments, you can
`edit a button', or rather, edit the button's properties.  One of the
properties you can edit is {\it width} - but there is no explicit
representation of width in a wxWindows button; instead, you call SetSize
and GetSize members. To translate this into a consistent,
property-oriented scheme, we could derive a new class
wxButtonWithProperties, which has two new functions: SetProperty and
GetProperty.  SetProperty accepts a property name and a value, and calls
an appropriate function for the property that is being passed.
GetProperty accepts a property name, returning a property value. So
instead of having to use the usual arbitrary set of C++ member functions
to set or access attributes of a window, programmer deals merely with
SetValue/GetValue, and property names and values.
We now have a single point at which we can modify or query an object by specifying
names and values at run-time. (The implementation of SetProperty and GetProperty
is probably quite messy and involves a large if-then-else statement to
test the property name and act accordingly.)

When the user invokes the property editor for a wxButtonWithProperties, the system
creates a wxPropertySheet with `imaginary' properties such as width, height, font size
and so on. For each property, wxButtonWithProperties::GetProperty is called, and the result is
passed to the corresponding wxProperty. The wxPropertySheet is passed to a wxPropertyListView
as described elsewhere, and the user edits away. When the user has finished editing, the system calls
wxButtonWithProperties::SetProperty to transfer the wxProperty value back into the button
by way of an appropriate call, wxWindow::SetSize in the case of width and height properties.

\section{Classes by category}\label{proplistclassesbycat}

A classification of property sheet classes by category.

\subsection{Data classes}

\begin{itemize}\itemsep=0pt
\item \helpref{wxProperty}{wxproperty}
\item \helpref{wxPropertyValue}{wxpropertyvalue}
\item \helpref{wxPropertySheet}{wxpropertysheet}
\end{itemize}

\subsection{Validator classes}\label{proplistvalidatorclasses}

Validators check that the values the user has entered for a property are
valid. They can also define specific ways of entering data, such as a
file selector for a filename, and they are responsible for transferring
values between the wxProperty and the physical display. 

Base classes:

\begin{itemize}\itemsep=0pt
\item \helpref{wxPropertyValidator}{wxproperty}
\item \helpref{wxPropertyListValidator}{wxpropertylistvalidator}
\item \helpref{wxPropertyFormValidator}{wxpropertyformvalidator}
\end{itemize}

List view validators:

\begin{itemize}\itemsep=0pt
\item \helpref{wxBoolListValidator}{wxboollistvalidator}
\item \helpref{wxFilenameListValidator}{wxfilenamelistvalidator}
\item \helpref{wxIntegerListValidator}{wxintegerlistvalidator}
\item \helpref{wxListOfStringsListValidator}{wxlistofstringslistvalidator}
\item \helpref{wxRealListValidator}{wxreallistvalidator}
\item \helpref{wxStringListValidator}{wxstringlistvalidator}
\end{itemize}

Form view validators:

\begin{itemize}\itemsep=0pt
\item \helpref{wxBoolFormValidator}{wxboolformvalidator}
\item \helpref{wxIntegerFormValidator}{wxintegerformvalidator}
\item \helpref{wxRealFormValidator}{wxrealformvalidator}
\item \helpref{wxStringFormValidator}{wxstringformvalidator}
\end{itemize}

\subsection{View classes}\label{proplistviewclasses}

View classes mediate between a property sheet and a physical window.

\begin{itemize}\itemsep=0pt
\item \helpref{wxPropertyView}{wxpropertyview}
\item \helpref{wxPropertyListView}{wxpropertylistview}
\item \helpref{wxPropertyFormView}{wxpropertyformview}
\end{itemize}

\subsection{Window classes}\label{proplistwindowclasses}

The class library defines some window classes that can be used as-is with a suitable
view class and property sheet.

\begin{itemize}\itemsep=0pt
\item \helpref{wxPropertyFormFrame}{wxpropertyformframe}
\item \helpref{wxPropertyFormDialog}{wxpropertyformdialog}
\item \helpref{wxPropertyFormPanel}{wxpropertyformpanel}
\item \helpref{wxPropertyListFrame}{wxpropertylistframe}
\item \helpref{wxPropertyListDialog}{wxpropertylistdialog}
\item \helpref{wxPropertyListPanel}{wxpropertylistpanel}
\end{itemize}

\subsection{Registry classes}

A validator registry is a list of validators that can be applied to properties in a property sheet.
There may be one or more registries per property view.

\begin{itemize}\itemsep=0pt
\item \helpref{wxPropertyValidatorRegistry}{wxpropertyvalidatorregistry}
\end{itemize}