utils/dialoged/docs/tech.tex

   1 \chapter{Technical notes}\label{technotes}
   2 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
   3 \setfooter{\thepage}{}{}{}{}{\thepage}%
   4
   5 \section{Overview}
   6
   7 The dialog editor is written as a library, to be invoked by other programs. As you can see,
   8 dialoged.cc is a very small program which invokes the main window via a wxResourceManager
   9 object. The wxResourceManager object controls the user interface and other aspects
  10 of the dialog editor.
  11
  12 There is wxResourceTable object in wxResourceManager: this contains a list of
  13 all the wxItemResources currently being edited. wxResourceTable and wxItemResource
  14 are classes already in wxWindows, defined in wx\_res.h. In order to edit a new
  15 dialog box, the dialog is created, and the existing event handler is temporarily replaced
  16 with a new one which defines editing functionality. This allows existing dialogs - even
  17 instances of subclasses of wxDialogBox - to be edited, the application-specific functionality
  18 being temporarily taken over by the dialog editor.
  19
  20 In order to edit the properties of a dialog box or item, a property list editor is invoked.
  21 This uses the property classes from utils/wxprop. In order to map between properties and the
  22 actual window API, such as SetSize and GetSize, a `proxy' class called wxPropertyInfo
  23 has been defined, with a subclass for each class of wxWindows window to be edited.
  24 This class defines the main members SetProperty, GetProperty, GetPropertyNames,
  25 which transform the normal API into `property' terms.
  26
  27 Properties are mostly extracted directly from the window being edited. This is
  28 in contrast with wxBuilder, where everything is stored in a set of parallel
  29 data structures, and windows `properties' only only set. However, there
  30 are exceptions to this rule in the dialog editor. There {\it is} in fact a set of
  31 parallel objects, the wxItemResource objects which can be seen listed in
  32 the main Dialog Editor window as a dialog is built up. These usually parallel
  33 the properties in the windows, but occasionally this is not possible. For example,
  34 all dialog boxes being edited must be modeless: or the user would not be
  35 able to access other windows. However, the user must be able to specify that
  36 when used in an application, that dialog box will be modal. In this case,
  37 the value in the wxItemResource will not match that in the actual dialog box.
  38
  39 There is a major problem with taking values directly from the windows: this
  40 information sometimes does not match what went in. In Motif and XView,
  41 size values returned are not the same as those given. This causes speedy
  42 `degeneration' of window properties. Under Windows, properties are almost
  43 always consistent. The other platforms will need to be catered for by
  44 relying more on the wxItemResource objects, and not taking size
  45 information directly from windows.
  46
  47 \subsection{Dynamic setting versus recreation}
  48
  49 The property editor scheme relies on being able to set window properties
  50 dynamically: the user changes a value, and the window changes immediately
  51 to reflect the new value. Unfortunately, not all properties can be
  52 changed dynamically in wxWindows; for example, in Motif, the label position
  53 must be given at panel item creation time, because the way the widgets
  54 are laid out depend on the label position. The label position cannot then
  55 be changed without deleting and recreating the item.
  56
  57 Hence the dialog editor takes two approaches: where values are dynamically
  58 settable, this is done. Where they are not, the item is deleted and recreated,
  59 after all existing values have been transferred into the parallel wxItemResource
  60 object. Therefore in wx\_rprop.cc, some of the SetProperty implementations have one or
  61 more call to RecreateWindowFromResource.
  62
  63 \section{Resource associations}
  64
  65 wxItemResource objects (containing information about panel items and dialogs) are not visual
  66 objects. However, they need to be associated with the visual objects when the latter
  67 are created for editing purposes. Therefore there is a hash table called resourceAssociations
  68 in wxResourceManager. When a window is created, the resource pointer and window pointer
  69 are associated via the hash table. When the window is deleted, the association is removed.
  70 Children of a dialog are associated with child wxItemResource objects by calling
  71 wxFindWindowByName with the wxItemResource name.
  72
  73 \section{What needs to be done for XView and Motif}
  74
  75 The following areas need attention before Dialog Editor will run properly on these platforms.
  76
  77 \begin{enumerate}\itemsep=0pt
  78 \item For XView, the property editor needs to be made a modeless, not modal dialog, which has
  79 implications for flow of control in wxPropertyInfo::Edit.
  80 \item Properties which do not return the same value they are set to, such as width and height,
  81 need to be stored directly in wxItemResource and {\it not} transferred from window to wxItemResource
  82 in wxWindowPropertyInfo::InstantiateResource.
  83 \item Properties which cannot be dynamically set in XView or Motif need to have the item recreated (e.g. labelOrientation).
  84 \end{enumerate}
  85
  86 \section{Files}
  87
  88 The Dialog Editor source files are as follows:
  89
  90 \begin{itemize}\itemsep=0pt
  91 \item wx\_rprop.h, wx\_rprop.cc: handle property setting and getting through the `proxy' wxPropertyInfo
  92 classes and using the property list editor from utils/wxprop.
  93 \item wx\_resed.h, wx\_resed.cc: the main implementation, in particular the wxResourceManager class.
  94 \item wx\_reswr.cc: resource writing code.
  95 \item wx\_repal.cc: the dialog editor palette implementation.
  96 \item dialoged.h, dialoged.cc: small `stub' for invoking the user interface via a wxResourceManager object.
  97 \end{itemize}