Committing in .

[wxWidgets.git] / utils / dialoged / docs / tech.tex

\chapter{Technical notes}\label{technotes}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{Overview}

The dialog editor is written as a library, to be invoked by other programs. As you can see,
dialoged.cc is a very small program which invokes the main window via a wxResourceManager
object. The wxResourceManager object controls the user interface and other aspects
of the dialog editor.

There is wxResourceTable object in wxResourceManager: this contains a list of
all the wxItemResources currently being edited. wxResourceTable and wxItemResource
are classes already in wxWindows, defined in wx\_res.h. In order to edit a new
dialog box, the dialog is created, and the existing event handler is temporarily replaced
with a new one which defines editing functionality. This allows existing dialogs - even
instances of subclasses of wxDialogBox - to be edited, the application-specific functionality
being temporarily taken over by the dialog editor.

In order to edit the properties of a dialog box or item, a property list editor is invoked.
This uses the property classes from utils/wxprop. In order to map between properties and the
actual window API, such as SetSize and GetSize, a `proxy' class called wxPropertyInfo
has been defined, with a subclass for each class of wxWindows window to be edited.
This class defines the main members SetProperty, GetProperty, GetPropertyNames,
which transform the normal API into `property' terms.

Properties are mostly extracted directly from the window being edited. This is
in contrast with wxBuilder, where everything is stored in a set of parallel
data structures, and windows `properties' only only set. However, there
are exceptions to this rule in the dialog editor. There {\it is} in fact a set of
parallel objects, the wxItemResource objects which can be seen listed in
the main Dialog Editor window as a dialog is built up. These usually parallel
the properties in the windows, but occasionally this is not possible. For example,
all dialog boxes being edited must be modeless: or the user would not be
able to access other windows. However, the user must be able to specify that
when used in an application, that dialog box will be modal. In this case,
the value in the wxItemResource will not match that in the actual dialog box.

There is a major problem with taking values directly from the windows: this
information sometimes does not match what went in. In Motif and XView,
size values returned are not the same as those given. This causes speedy
`degeneration' of window properties. Under Windows, properties are almost
always consistent. The other platforms will need to be catered for by
relying more on the wxItemResource objects, and not taking size
information directly from windows.

\subsection{Dynamic setting versus recreation}

The property editor scheme relies on being able to set window properties
dynamically: the user changes a value, and the window changes immediately
to reflect the new value. Unfortunately, not all properties can be
changed dynamically in wxWindows; for example, in Motif, the label position
must be given at panel item creation time, because the way the widgets
are laid out depend on the label position. The label position cannot then
be changed without deleting and recreating the item.

Hence the dialog editor takes two approaches: where values are dynamically
settable, this is done. Where they are not, the item is deleted and recreated,
after all existing values have been transferred into the parallel wxItemResource
object. Therefore in wx\_rprop.cc, some of the SetProperty implementations have one or
more call to RecreateWindowFromResource.

\section{Resource associations}

wxItemResource objects (containing information about panel items and dialogs) are not visual
objects. However, they need to be associated with the visual objects when the latter
are created for editing purposes. Therefore there is a hash table called resourceAssociations
in wxResourceManager. When a window is created, the resource pointer and window pointer
are associated via the hash table. When the window is deleted, the association is removed.
Children of a dialog are associated with child wxItemResource objects by calling
wxFindWindowByName with the wxItemResource name.

\section{What needs to be done for XView and Motif}

The following areas need attention before Dialog Editor will run properly on these platforms.

\begin{enumerate}\itemsep=0pt
\item For XView, the property editor needs to be made a modeless, not modal dialog, which has
implications for flow of control in wxPropertyInfo::Edit.
\item Properties which do not return the same value they are set to, such as width and height,
need to be stored directly in wxItemResource and {\it not} transferred from window to wxItemResource
in wxWindowPropertyInfo::InstantiateResource.
\item Properties which cannot be dynamically set in XView or Motif need to have the item recreated (e.g. labelOrientation).
\end{enumerate}

\section{Files}

The Dialog Editor source files are as follows:

\begin{itemize}\itemsep=0pt
\item wx\_rprop.h, wx\_rprop.cc: handle property setting and getting through the `proxy' wxPropertyInfo
classes and using the property list editor from utils/wxprop.
\item wx\_resed.h, wx\_resed.cc: the main implementation, in particular the wxResourceManager class.
\item wx\_reswr.cc: resource writing code.
\item wx\_repal.cc: the dialog editor palette implementation.
\item dialoged.h, dialoged.cc: small `stub' for invoking the user interface via a wxResourceManager object.
\end{itemize}