## Topic overviews

This chapter contains a selection of topic overviews.

Property classes overview
Validator classes overview
View classes overview
wxPropertySheet overview

### Property classes overview

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

- the transfer of data to and from the physical controls;
- the behaviour of various controls and custom windows for particular types of data;
- 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.

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 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 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 wxPropertyView is available for programmers to derive new kinds of view. One kind of view that is available is the 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 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 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 wxPropertyListValidator from which concrete classes are derived, such as wxRealListValidator and 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 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 Window classes for further details.

### 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 Appearance and behaviour of a property list view.

    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);
      }
    }

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

    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");

      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);
      }
    }

### Validator classes overview

Classes: Validator classes

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.

### wxPropertyValidator overview

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

### wxPropertyListValidator overview

Class: 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 property list appearance).

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.

### wxPropertyFormValidator overview

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.

### View classes overview

Classes: View classes

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

### wxPropertyView overview

Class: wxPropertyView

This is the abstract base class for property views.

### wxPropertyListView overview

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

### wxPropertyFormView overview

Class: 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:

- 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.
- cancel: indicates the Cancel button. Calls wxPropertyFormView::OnCancel. By default, closes and deletes the frame or dialog, then deletes the view.
- help: indicates the Help button. Calls wxPropertyFormView::OnHelp. This needs to be overridden by the application for anything interesting to happen.
- 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).
- update: indicates the Revert button. Calls wxPropertyFormView::OnUpdate, which by defaults transfers the displayed values to the wxProperty objects.

### wxPropertySheet overview

Classes: wxPropertySheet, wxProperty, 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 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.