docs/latex/proplist/body.tex

   1 \chapter{Introduction}\label{introduction}
   2 \pagenumbering{arabic}%
   3 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
   4 \setfooter{\thepage}{}{}{}{}{\thepage}%
   5
   6 The Property Sheet Classes help the programmer to specify complex dialogs and
   7 their relationship with their associated data. By specifying data as a
   8 wxPropertySheet containing wxProperty objects, the programmer can use
   9 a range of available or custom wxPropertyView classes to allow the user to
  10 edit this data. Classes derived from wxPropertyView act as mediators between the
  11 wxPropertySheet and the actual window (and associated panel items).
  12
  13 For example, the wxPropertyListView is a kind of wxPropertyView which displays
  14 data in a Visual Basic-style property list (see \helpref{the next section}{appearance} for
  15 screen shots). This is a listbox containing names and values, with
  16 an edit control and other optional controls via which the user edits the selected
  17 data item.
  18
  19 wxPropertyFormView is another kind of wxPropertyView which mediates between
  20 the data and a panel or dialog box which has already been created. This makes it a contender for
  21 the replacement of wxForm, since programmer-controlled layout is going to be much more
  22 satisfactory. If automatic layout is desired, then wxPropertyListView could be used instead.
  23
  24 The main intention of this class library was to provide property {\it list} behaviour, but
  25 it has been generalised as much as possible so that the concept of a property sheet and its viewers
  26 can reduce programming effort in a range of user interface tasks.
  27
  28 For further details on the classes and how they are used, please see \helpref{Property classes overview}{propertyoverview}.
  29
  30 \section{The appearance and behaviour of a property list view}\label{appearance}
  31
  32 The property list, as seen in an increasing number of development tools
  33 such as Visual Basic and Delphi, is a convenient and compact method for
  34 displaying and editing a number of items without the need for one
  35 control per item, and without the need for designing a special form. The
  36 controls are as follows:
  37
  38 \begin{itemize}\itemsep=0pt
  39 \item A listbox showing the properties and their current values, which has double-click
  40 properties dependent on the nature of the current property;
  41 \item a text editing area at the top of the display, allowing the user to edit
  42 the currently selected property if appropriate;
  43 \item `confirm' and `cancel' buttons to confirm or cancel an edit (for the property, not the
  44 whole sheet);
  45 \item an optional list that appears when the user can make a choice from several known possible values;
  46 \item a small Edit button to invoke `detailed editing' (perhaps showing or hiding the above value list, or
  47 maybe invoking a common dialog);
  48 \item optional OK/Close, Cancel and Help buttons for the whole dialog.
  49 \end{itemize}
  50
  51 The concept of `detailed editing' versus quick editing gives the user a choice
  52 of editing mode, so novice and expert behaviour can be catered for, or the user can just
  53 use what he feels comfortable with.
  54
  55 Behaviour alters depending on the kind of property being edited. For example, a boolean value has
  56 the following behaviour:
  57
  58 \begin{itemize}\itemsep=0pt
  59 \item Double-clicking on the item toggles between TRUE and FALSE.
  60 \item Showing the value list enables the user to select TRUE or FALSE.
  61 \item The user may be able to type in the word TRUE or FALSE, or the edit control
  62 may be read-only to disallow this since it is error-prone.
  63 \end{itemize}
  64
  65 A list of strings may pop up a dialog for editing them, a simple string just allows text editing,
  66 double-clicking a colour property may show a colour selector, double-clicking on a filename property may
  67 show a file selector (in addition to being able to type in the name in the edit control), etc.
  68
  69 Note that the `type' of property, such as string or integer, does not
  70 necessarily determine the behaviour of the property. The programmer has
  71 to be able to specify different behaviours for the same type, depending
  72 on the meaning of the property. For example, a colour and a filename may
  73 both be strings, but their editing behaviour should be different. This
  74 is why objects of type wxPropertyValidator need to be used, to define
  75 behaviour for a given class of properties or even specific property
  76 name.  Objects of class wxPropertyView contain a list of property
  77 registries, which enable reuse of bunches of these validators in
  78 different circumstances. Or a wxProperty can be explicitly set to use a
  79 particular validator object.
  80
  81 The following screen shot of the property classes test program shows the
  82 user editing a string, which is constrained to be one of three possible
  83 values.
  84
  85 $$\image{8cm;0cm}{prop1.eps}$$\\
  86
  87 The second picture shows the user having entered a integer that
  88 was outside the range specified to the validator. Note that in this picture,
  89 the value list is hidden because it is not used when editing an integer.
  90
  91 $$\image{8cm;0cm}{prop2.eps}$$
  92
  93 \chapter{Files}\label{files}
  94 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
  95 \setfooter{\thepage}{}{}{}{}{\thepage}%
  96
  97 The property class library comprises the following files:
  98
  99 \begin{itemize}\itemsep=0pt
 100 \item prop.h: base property class header
 101 \item proplist.h: wxPropertyListView and associated classes
 102 \item propform.h: wxPropertyListView and associated classes
 103 \item prop.cpp: base property class implementation
 104 \item proplist.cpp: wxPropertyListView and associated class implementions
 105 \item propform.cpp: wxPropertyFormView and associated class implementions
 106 \end{itemize}