\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
\parindent 0pt
\parskip 11pt
\input psbox.tex
\title{User Manual for wxBuilder 1.9}
\author{Julian Smart\\Decision Support Group\\Artificial Intelligence Applications Institute\\80 South Bridge\\University of Edinburgh\\EH1 1HN}
\date{March 1995}
\makeindex
\begin{document}
\maketitle

\pagestyle{fancyplain}
\bibliographystyle{plain}
\pagenumbering{roman}
\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}
\setfooter{\thepage}{}{}{}{}{\thepage}
\tableofcontents%

\begin{comment}
To be done:
-- describe what effect Description, name etc. have on generated code.
\end{comment}
\chapter{Introduction}%
\pagenumbering{arabic}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

wxBuilder is a tool for interactively building the GUI (Graphical User
Interface) component of a wxWindows application. The user chooses and
places frames, dialog boxes, subwindows and panel items, and wxBuilder
generates appropriate C++ code for compiling with the wxWindows library
on Windows or X. Optionally, the wxWindows resource file format (suffix .WXR)
may be generated to help separate out GUI specification from the application
code.

The user may then populate this skeleton program with further code to
complete the application, or use the results as a design and prototyping
aid. wxBuilder could also find use as a learning aid for a beginning
wxWindows user, since there is a clear correspondence between GUI and
C++ code.

wxBuilder may also be used as a migration tool from straight Windows to
wxWindows, by importing existing Windows resource (.RC) files (Windows version
only).

wxBuilder is not unique in the kind of facilities it provides, but it is
the only known freely available tool to generate multi-platform code,
and is the only one to support wxWindows.

\section{Status of wxBuilder}

wxBuilder now compiles under Windows and Motif. An XView release is
available but there are problems related to multiple modal dialogs that
will be fixed shortly.

Under Motif, there is a problem with the `simulated' windows not always
being drawn correctly; this is a tricky Motif-related problem. The
current work-around is to move the simulated frame or dialog box, and
the display will be refreshed correctly.

Various facilities are planned for a later release, including:

\begin{itemize}
\item one source file per window option
\item MDI support
\item command line parser generation
\item help file generation
\item wxCLIPS generation
\item extend repertoire of GDI objects, such pens, brushes and colours.
\item Support for wxForm
\end{itemize}

\section{Change log}

Version 1.9 March 1995

\begin{itemize}\itemsep=0pt
\item Abandoned the simulation window and now use
the features added in 1.61 (c) to directly manipulate
panel and dialog items.
\item The tree (for one frame or dialog only) is displayed
in the main window.
\end{itemize}

Version 1.8 January 1995

\begin{itemize}\itemsep=0pt
\item Major alterations to generate .WXR resource files (optionally).
\item All elements that use bitmaps and icons now have a bitmap properties editor,
which centralizes the bitmap code and allows specification of desired bitmap
format on each platform.
\item Added support for bitmap message.
\item Fixed some bugs e.g. crashes when a toolbar is present.
\item On loading a project, the main window is displayed immediately.
\end{itemize}

Version 1.7 November 1994

\begin{itemize}\itemsep=0pt
\item Added support for wxGauge and wxGroupBox.
\item Improved sizing code.
\item Fixed bug in panel window style (was always wxBORDER).
\end{itemize}

Version 1.6 October 1994

\begin{itemize}\itemsep=0pt
\item Added support for wxSlider.
\item Changed `int' window styles to `long'.
\item Added support for bitmap buttons.
\end{itemize}

Version 1.5 October 1994

\begin{itemize}\itemsep=0pt
\item Cured bug in conversion of Windows menu resource to wxWindows menu
(menu items lost their parents).
\item First release of Motif version, with more stable Motif wxWindows implementation.
\item Added ability to load bitmaps into canvases, for more detailed `simulation' of
interfaces.
\item Added provision for extra (user-defined) library and include paths.
\item Improved UNIX and DOS makefile generation.
\item Solved several bugs (e.g. right-click editing of a window caused a crash).
\end{itemize}

Version 1.3 June 1994

\begin{itemize}\itemsep=0pt
\item File history now has names added to front of list.
\item Added Cancel button to on-exit dialog box.
\item Fixed delete bug wxRadioBox/wxListBox/wxChoice properties
dialogs.
\item Fixed bug which disabled loading on the first attempt.
\item Fixed code generation bugs for X/Windows icons.
\item Fixed OnSize code generation bug (statements in wrong order).
\item Fixed UNIX makefile generation bugs.
\item Windows version no longer uses CTL3D since it seems to
crash wxWindows programs on some PCs. Now uses CTL3DV2 instead.
\end{itemize}

Version 1.2 May 1994

\begin{itemize}\itemsep=0pt
\item Added file history.
\item Some code generation bugs fixed.
\end{itemize}

\chapter{Creating a project with wxBuilder}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This chapter guides the user through the main processes involved
in creating a new application.

\section{Running wxBuilder}

Run {\tt wxbuild.exe} (Windows) or {\tt wxbuild} (UNIX) with an optional
project filename. Project files contain all information relevant to an
application except bitmap files and icons; their extension is {\tt .WXP}
\rtfsp(for wxWindows Project).

Below is a screen shot of the main wxBuilder window, with a project
already loaded. A menu bar is supplemented by a tool bar to accelerate
certain commands. The {\it object editor} canvas displays a
tree representing the hierarchy of windows for the current frame or
dialog box.

Below the object editor canvas is a listbox containing a list of all
top-level windows (all the frames and dialog boxes). Clicking on a
window in this listbox creates the window and updates the object editor.

\begin{figure}
$$\image{10cm;0cm}{screen1.ps}$$
\caption{Main wxBuilder window}\label{mainwin}
\end{figure}

The status line is divided into two fields: the left field displays help
messages, and the right field shows the current `mode', either edit or
test mode. In test mode, certain events from project windows (such as
pressing buttons or selecting menu items) will do the user-defined action,
whereas in edit mode, the same events will pop up a dialog to allow editing
of that action.

An {\it object palette} is displayed in a sepearate frame. This allows
selection of a window object (such as a canvas or button) -- the cursor in the object
editor window changes to a cross, and left-clicking on a panel or dialog box
(in edit mode) creates an item of that kind. Items other than panel items
must be created from the Edit menu at present, since only panels and dialog
boxes are sensitive to left clicks. This will probably change.

\begin{figure}
$$\image{10cm;0cm}{palette.ps}$$
\caption{Object palette}\label{pallete}
\end{figure}

\section{Setting up for a new project}

It's wise to set things up properly before starting to create windows.
The {\bf Project} menu has two items you should look at: {\bf Edit project
settings} and {\bf Edit global settings}.

Project settings are saved with the project file and are changed on a
per-project basis. These include project name (used as a base for
generating files), and project directory name.

Global settings are variables that are likely to change on a per-user
basis, and are stored in WIN.INI (under Windows) or .Xdefaults (under
X). Under X, the .Xdefaults file should be edited by hand, since the X
versions of wxBuilder do not currently save global settings. See\rtfsp
\helpref{Resources}{resources}.

In addition, set the name of the application class (to be used as a derivative
of wxApp) and a brief description of the project, using the {\bf Edit application
properties} item on the {\bf File} menu.

\section{Creating a main window}

Every wxWindows must have a frame which is the main window (in C++, returned from
the {\bf wxApp::OnInit} function).

The first frame you create is taken to be this main window. Choose {\bf Edit:
New frame} or click on the frame tool on the palette, and then on the object editor.

You can size and position this frame using the representation on the object
editor (try to resist the temptation to edit the real windows directly!).
See \helpref{Using the object editor}{objecteditor} for further details.

\chapter{Procedures}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{Changing project and global settings}\label{globals}

\subsection{Project settings}

Project settings are saved with the project file and are changed on a
per-project basis.

\begin{twocollist}
\twocolitemruled{{\bf Setting}}{{\bf Description}}
\twocolitem{Root name}{This will be used for all files generated by wxBuilder for this project.
Extensions such as .RC, .CC and .DEF will be appended to form filenames.}
\twocolitem{C++ extension}{Allows you to choose what C++ extension will be used (default .CC).}
\twocolitem{Directory under Windows}{The directory into which the generated files will be placed under Windows.}
\twocolitem{Directory under UNIX}{The directory into which the generated files will be placed under UNIX.}
\twocolitem{Generate makefiles}{If on, will generate makefiles.}
\twocolitem{Generate RC file}{If on, will generate Windows resource file.}
\twocolitem{Generate DEF file}{If on, will generate Windows module definition file.}
\twocolitem{Generate wxWindows resources}{If on, will generate .WXR resource files (different from
Windows resource files), replacing the programmatic creation of menu bars, dialog boxes and panels
where possible.}
\end{twocollist}

\subsection{Global settings}

Global settings are variables that are likely to change on a per-user
basis, and are stored in WIN.INI (under Windows) or .Xdefaults (under X).
Under X, the .Xdefaults file should be edited by hand, since the X
versions of wxBuilder do not currently save global settings.

These are the global settings.

\begin{twocollist}
\twocolitemruled{{\bf Setting}}{{\bf Description}}
\twocolitem{Windows compiler}{Set to the desired Windows compiler. At present, the only
recognised compilers are Microsoft's C++ version 7, Visual C++ and the NT compiler. For
other compilers, please write the makefile by hand or use a Microsoft compatibility mode
if available.}
\twocolitem{UNIX compiler}{Type in the name of the UNIX compiler. The default is gcc-2.1.}
\twocolitem{X GUI target}{UNIX makefiles are generated with three targets, allowing simultaneous
compilation of XView , Sun Motif and HP Motif binaries. This target specifies which one should
be used for auto-compiling {\it (not yet implemented).}}
\twocolitem{X includes}{Switches specifying where to find X include directories.}
\twocolitem{X libs}{Switches specifying where to find X library directories.}
\twocolitem{Extra includes (UNIX)}{Allows specification of extra include paths for UNIX makefiles.}
\twocolitem{Extra libs (UNIX)}{Allows specification of extra library paths for UNIX makefiles.}
\twocolitem{Extra includes (Windows)}{Allows specification of extra include paths for Windows makefiles.}
\twocolitem{Extra libs (Windows)}{Allows specification of extra library paths for Windows makefiles.}
\twocolitem{UNIX wxWindows directory}{wxWindows home directory under UNIX.}
\twocolitem{Windows wxWindows directory}{wxWindows home directory under Windows.}
\begin{comment}
\twocolitem{Auto compile}{Compile immediately after code generation {\it (not yet implemented).}}
\twocolitem{Auto run}{Run immediately after compilation {\it (not yet implemented).}}
\end{comment}
\end{twocollist}

See also \helpref{Resources}{resources}.

\section{Using the object editor}\label{objecteditor}

The object editor is a hierarchical view of the windows in
your frame or dialog box.

To edit a window, you may create a new frame or dialog box from the Edit
menu, or click on a window name in the listbox on the main wxBuilder
window

Panel items may be repositioned by dragging with the left mouse button,
selected and deselected with left click, and resized by dragging
on the handles visible when the object is selected. Frames may
be sized interactively as normal, and dialog box size may be specified
in the relevant properties dialog.

Each type of window has a property editor associated with it, allowing
tailoring of specific window characteristics. To invoke a property
editor, right-click on the panel item or object in
the hierarchy. This pops up a menu for editing or deleting the object.

To align panel items, select two or more items, and use an alignment
tool on the tool bar. The first item selected is taken as the
reference for aligning the other items.

\section{Generating C++}

Click on the {\bf C++} tool on the tool bar, or choose {\bf Generate C++}\rtfsp
from the {\bf Project} menu. A report window will be displayed with
error and warning messages, and if successful, source files will be
written in the current project directory.

%See also \helpref{Error and warning messages}{errmessages}.
%

\section{Managing GDI objects}

wxBuilder allows the user to define a set of GDI (Graphics Device
Interface) objects to be used in a program. Currently only fonts are
supported, but in future this will be extended to colours, pens,
brushes, bitmaps, icons and cursors.

To define a set of fonts for the project, invoke the Font Manager
from the {\bf GDI} menu.

\begin{description}
\item[Quit] Quit from the Font Manager.
\item[Help] Invoke help for the Font Manager.
\item[Add] Add a font.
\item[Delete] Delete the selected font.
\end{description}

\section{Creating a frame}

Left-click on the frame icon on the object palette, and left-click
again on the object editor canvas, or choose {\bf New frame} from
the {\bf Edit} menu. The frame properties editor will be shown,
with the following controls.

\begin{description}
\item[Name] The name of this frame instance.
\item[Description] A textual description of the frame.
\item[Class name] The name of the C++ class that will be created for
this frame. At present, each frame must have a unique class.
\item[Icon name] The name of the icon file to be used for this frame.
\item[Title] The default title for the frame.
\item[No. status line fields] The number of divisions for the status line.
Zero indicates no status line.
\item[Vertical subwindow tiling] If checked on, the \helpref{subwindow tiling}{tiling}\rtfsp
is vertical. Otherwise it is horizontal.
\item[Thick frame] If checked on, the frame has a thick border for resizing
(Windows only).
\item[Caption] If checked on, the frame has a caption (Windows only).
\item[System menu] If checked on, the frame has a system menu (Windows only).
\item[Minimize button] If checked on, the frame has a minimize button (Windows only).
\item[Maximize button] If checked on, the frame has a maximize button (Windows only).
\item[Shuffle subwindows] If pressed, the subwindow positioning order is rearranged.
\end{description}

\subsection{Subwindow tiling}\label{tiling}

The way in which subwindows are positioned and sized in wxWindows is very different
from the method for panel items, dialog boxes and frames. This is because
subwindows are often sized relative to their parent frame.

If there is only one subwindow, the default wxWindows method is used, which is
simply to resize the subwindow to the frame client area when the frame is created
or resized.

If there is more than one subwindow, wxBuilder uses an algorithm to
layout the windows. It is hoped that this algorithm will cater for most
subwindow layout needs. These are the options and constraints:

\begin{enumerate}
\item Zero or more subwindows may be children of a frame.
\item All subwindows must be tiled either vertically or horizontally.
Mixture of the two tiling modes is not allowed (horizontal tool bars work
independently and may be discounted from this constraint).
\item Each subwindow has a {\it resize strategy}, one of
Fixed, Proportional and Grow.
\item The mix of resize strategies must be such as to allow
wxBuilder to determine all subwindow sizes.
\end{enumerate}

If the resize strategy is Fixed, the specified width (if in horizontal
tiling mode) or height (if in vertical mode) is used. The other
dimension is determined by the size of the frame (and possibly the
presence of a tool bar).

If the resize strategy is Proportional, the free dimension of the
subwindow is determined from that dimension of the frame, together
with the percentage specified in the subwindow property editor.

If the resize strategy is Grow, the free dimension of the
subwindow is determined by adjacent subwindows. In practice
only one subwindow may use this strategy.

\section{Creating a dialog box}

Left-click on the dialog box icon on the object palette, and left-click
again on the object editor canvas, or choose {\bf New dialog} from
the {\bf Edit} menu. The dialog box properties editor will be shown,
with the following controls.

\begin{description}
\item[Name] The name of this dialog box instance.
\item[Description] A textual description of the dialog box.
\item[Class name] The name of the C++ class that will be created for
this dialog box.
\item[Title] The default title for the dialog box.
\item[Width] The width of the dialog box.
\item[Height] The width of the dialog box.
\item[Fit contents] If checked on, the panel will fit itself to its
contents.
\item[Horizontal labels] If checked on, the default labelling orientation
is horizontal, otherwise it is vertical.
\item[Label font] The name of the font to be used for panel item labels.
The font should have been created previously using the font manager,
accessible from the GDI menu.
\item[Button font] The name of the font to be used for panel item contents.
\end{description}

\section{Creating a menu bar}

To create a menu bar for a frame displayed in the object editor, select
the {\bf Edit menu bar} option on the {\bf Edit} menu. 

The Menu Bar Editor will appear with a large listbox for menu and item
names, fields for editing text, and buttons below it for creating
and deleting items.

\begin{description}
\item[Menus] List of menus and menu items.
\item[Name] Contains the name of a new or currently
selected menu item.
\item[Id] Allows the user to specify the name of the
menu item identifier, as used in a {\bf wxMenu::Append} call.
These names will be associated with integers automatically
by wxBuilder. If the user leaves this field blank, wxBuilder
will generate a suitable identifier.
\item[Help string] Allows the user to specify a
help string which will appear on the status line when
the mouse cursor is over that menu item (Motif and Windows only).
\item[New item] Creates an item at the same level as the
currently selected menu item. So, if the currently
selected item is a menu called {\it Edit}, pressing this
button will create a new menu, not an item on the {\it Edit}\rtfsp
menu. Note that you must fill in the fields {\it before} you
press the button.
\item[New child] Creates a {\it child} of the currently selected menu
item, i.e. it creates a new submenu. So to create the first item
of the {\it Edit} menu, select the {\it Edit} item and press
this button.  Note that you must fill in the fields {\it before} you
press the button.
\item[New separator] Creates a separator after the selected menu item.
\item[Delete item] Deletes the currently selected menu item.
\item[Save item] Saves the displayed values in the currently selected
menu item.
\end{description}
\par

\subsection{Hotkeys}

To specify a hotkey, insert an ampersand (\&) before the letter
which serves as the hotkey (Windows and Motif). For example,\rtfsp
{\bf E\&xit}.

\subsection{Deleting a menu bar}

To remove the entire menu bar, delete the object in the usual
way from the object editor (select the menu bar object and choose
the {\bf Delete object} option from the {\bf Edit} menu).

Alternatively, delete all the menus from the menu bar editor.

\section{Creating a tool bar}

To create a tool bar for a frame displayed in the object editor, select
the {\bf Edit tool bar} option on the {\bf Edit} menu. 

The tool bar properties editor will appear with the following controls.

\begin{description}
\item[Name] The name of this tool bar instance.
\item[Description] A textual description of the tool bar.
\item[Class name] The name of the C++ class that will be created for
this tool barl.
\item[Rows/cols] The maximum number of columns for this toolbar
(set to a high number since only one row is allowed).
\item[Tools] A list of the current tools in the tool bar.
\item[Id] Contains the name of the identifier for a new or currently
selected tool. wxBuilder allocates actual integer identifiers
for these names automatically.
\item[Help string] Allows the user to specify a
help string which will appear on the status line when
the mouse cursor is over that menu item (Motif and Windows only).
\item[Bitmap] The name of the bitmap file for the tool. A full
path or extension should not be given; the project path will be prepended, and
a .BMP or .XBM extension added as appropriate.
\item[Toggle] If checked on, this tool will be a toggle tool.
\item[Add] Press to add a tool to the tool bar. Note that you
must fill in the fields {\it before} you press the button.
\item[Save] Saves the displayed values in the currently selected
toggle.
\item[Delete] Deletes the currently selected tool.
\item[Demote] Moves the selected tool to the end of the tool bar.
\end{description}

\subsection{Deleting a tool bar}

To remove the entire tool bar, delete the object in the usual
way from the object editor (select the tool bar object and choose
the {\bf Delete object} option from the {\bf Edit} menu).

\section{Creating a panel subwindow}

Left-click on the panel icon on the object palette, and left-click again
on the object editor, inside a frame object. The panel properties editor
will be shown, with the following controls.

\begin{description}
\item[Name] The name of this panel instance.
\item[Description] A textual description of the panel.
\item[Class name] The name of the C++ class that will be created for
this panel.
\item[Border] If checked on, the panel will have a border.
\item[Resize strategy] One of Fixed, Proportional and Grow.
See \helpref{subwindow tiling}{tiling}.
\item[Width] The width of the panel.
\item[Height] The width of the panel.
\item[\% frame] If Resize strategy is Proportional, this value specifies
the proportion of the frame for determining the subwindow size.
\item[Fit contents] If checked on, the panel will fit itself to its
contents.
\item[Horizontal labels] If checked on, the default labelling orientation
is horizontal, otherwise it is vertical.
\item[Label font] The name of the font to be used for panel item labels.
The font should have been created previously using the font manager,
accessible from the GDI menu.
\item[Button font] The name of the font to be used for panel item contents.
\end{description}

\section{Creating a canvas subwindow}

Left-click on the canvas icon on the object palette, and left-click
again on the object editor, inside a frame object. The canvas properties
editor will be shown, with the following controls.

\begin{description}
\item[Name] The name of this canvas instance.
\item[Description] A textual description of the canvas.
\item[Class name] The name of the C++ class that will be created for
this canvas.
\item[Border] If checked on, the canvas will have a border.
\item[Resize strategy] One of Fixed, Proportional and Grow.
See \helpref{subwindow tiling}{tiling}.
\item[Width] The width of the canvas.
\item[Height] The width of the canvas.
\item[\% frame] If Resize strategy is Proportional, this value specifies
the proportion of the frame for determining the subwindow size.
\item[Retained canvas] If checked on, the canvas will be retained under X.
\item[Pixels/unit X] The number of pixels per logical X unit. If zero,
no horizontal scrollbar will be shown.
\item[Pixels/unit Y] The number of pixels per logical Y unit. If zero,
no vertical scrollbar will be shown.
\item[No units X] The number of logical units in the X dimension.
\item[No units Y] The number of logical units in the Y dimension.
\item[Units/page X] The number of logical units per horizontal page.
\item[Units/page Y] The number of logical units per vertical page.
\item[Use bitmap] If on, will load a bitmap into the canvas.
\item[Edit bitmap properties] Allows the user to change the name of the bitmap,
and the method of bitmap creation on each of the X and Windows platforms.
\end{description}

\subsection{Displaying a bitmap}

A Windows bitmap (or GIF under X) may be displayed in the canvas.  For
code generation purposes, this facility should only be used if the
wxImage library (X) or DIB library (Windows) is available at your
site.

\section{Creating a text subwindow}

Left-click on the text subwindow icon on the object palette, and left-click
again on the object editor, inside a frame object. The text subwindow properties
editor will be shown, with the following controls.

\begin{description}
\item[Name] The name of this text subwindow instance.
\item[Description] A textual description of the text subwindow.
\item[Class name] The name of the C++ class that will be created for
this text subwindow.
\item[Border] If checked on, the text subwindow will have a border.
\item[Resize strategy] One of Fixed, Proportional and Grow.
See \helpref{subwindow tiling}{tiling}.
\item[Width] The width of the subwindow.
\item[Height] The width of the subwindow.
\item[\% frame] If Resize strategy is Proportional, this value specifies
the proportion of the frame for determining the subwindow size.
\item[Text file] The name of a text file to be loaded onto the canvas on creation.
\end{description}

\section{Creating a button item}

Left-click on the button icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
button properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this button.
\item[Description] A textual description of the button.
\item[Label] Label for the button.
\item[Auto size] If checked on, the button will size itself according the
the text label. If off, the size will be determined by the interactively sizing
the button from the object editor.
\item[Use bitmap] If on, will use a bitmap instead of a string label.
\item[Edit bitmap properties] Allows the user to change the name of the bitmap,
and the method of bitmap creation on each of the X and Windows platforms.
\end{description}

\section{Creating a checkbox item}

Left-click on the checkbox icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
checkbox properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this checkbox.
\item[Description] A textual description of the checkbox.
\item[Label] Label for the checkbox.
\item[Auto size] If checked on, the checkbox will size itself according the
the text label. If off, the size will be determined by the interactively sizing
the checkbox from the object editor.
\item[Label position] Horizontal, vertical or default label placement. Under Windows
the checkbox label is always horizontal.
\end{description}

\section{Creating a choice item}

Left-click on the choice item icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
choice item properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this choice item.
\item[Description] A textual description of the choice item.
\item[Label] Label for the choice item.
\item[Auto size] If checked on, the choice item will size according to
wxWindows defaults. If off, the size will be determined by interactively sizing
the choice item from the object editor.
\item[Label position] Horizontal, vertical or default label placement.
\item[Values] A list of default string values.
\item[Value] Text field for entering a choice item value.
\item[Add] Add the text in the current field to the list of default values.
\item[Delete] Delete the currently selected item.
\end{description}

\section{Creating a gauge item}

Left-click on the gauge icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
gauge properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this gauge.
\item[Description] A textual description of the gauge.
\item[Label] Label for the gauge.
\item[Auto size] If checked on, the gauge will size according to
wxWindows defaults. If off, the size will be determined by interactively sizing
the gauge from the object editor.
\item[Label position] Horizontal, vertical or default label placement.
\item[Range] Range of the gauge (default 100).
\end{description}

\section{Creating a groupbox item}

Left-click on the groupbox icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
groupbox properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this groupbox.
\item[Description] A textual description of the groupbox.
\item[Label] Label for the groupbox.
\item[Label position] Horizontal, vertical or default label placement.
\end{description}

\section{Creating a listbox item}

Left-click on the listbox icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
listbox properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this listbox.
\item[Description] A textual description of the listbox.
\item[Label] Label for the listbox.
\item[Auto size] If checked on, the listbox will size according to
wxWindows defaults. If off, the size will be determined by interactively sizing
the listbox from the object editor.
\item[Label position] Horizontal, vertical or default label placement.
\item[Values] A list of default string values.
\item[Value] Text field for entering a listbox value.
\item[Add] Add the text in the current field to the list of default values.
\item[Delete] Delete the currently selected item.
\end{description}

\section{Creating a message item}

Left-click on the message item icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
message item properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this message item.
\item[Description] A textual description of the message item.
\item[Label] Label for the message item.
\item[Use bitmap] If on, will use a bitmap instead of a string message.
\item[Edit bitmap properties] Allows the user to change the name of the bitmap,
and the method of bitmap creation on each of the X and Windows platforms.
\end{description}

\section{Creating a radiobox item}

Left-click on the radiobox icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
radiobox properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this radiobox.
\item[Description] A textual description of the radiobox.
\item[Label] Label for the radiobox.
\item[Auto size] If checked on, the radiobox will size according to
wxWindows defaults. If off, the size will be determined by interactively sizing
the radiobox from the object editor.
\item[Label position] Horizontal, vertical or default label placement.
\item[Rows/cols] Number of rows or columns (depending on label orientation
value).
\item[Values] A list of default string values.
\item[Value] Text field for entering a radiobox value.
\item[Add] Add the text in the current field to the list of default values.
\item[Delete] Delete the currently selected item.
\end{description}

\section{Creating a slider item}

Left-click on the slider icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
slider properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this slider.
\item[Description] A textual description of the slider.
\item[Label] Label for the slider.
\item[Auto size] If checked on, the slider will size according to
wxWindows defaults. If off, the size will be determined by interactively sizing
the slider from the object editor.
%\item[Label position] Horizontal, vertical or default label placement.
\item[Min Value] Minimum integer slider value
\item[Max Value] Maximum integer slider value
\end{description}

The current position of the slider will be used as the default value.

\section{Creating a text item}

Left-click on the text item icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
text item properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this text item.
\item[Description] A textual description of the text item.
\item[Label] Label for the text item.
\item[Auto size] If checked on, the text item will size according to
wxWindows defaults. If off, the size will be determined by the interactively sizing
the text item from the object editor.
\item[Label position] Horizontal, vertical or default label placement.
\item[Value] Text field for the default text value.
\end{description}

\section{Creating a multi-line text item}

Left-click on the multitext item icon on the object palette, and left-click
again on the object editor inside a panel or dialog box object. The
multitext item properties editor will be shown, with the following
controls.

\begin{description}
\item[Name] The name of this multitext item.
\item[Description] A textual description of the multitext item.
\item[Label] Label for the multitext item.
\item[Auto size] If checked on, the multitext item will size according to
wxWindows defaults. If off, the size will be determined by the interactively sizing
the multitext item from the object editor.
\item[Label position] Horizontal, vertical or default label placement.
\item[Value] Text field for the default text value.
\end{description}

\section{Editing a window object's properties}

An object's properties may be edited by one of three methods.

\begin{enumerate}
\item Select the object with left click on the object editor, and
choose {\bf Delete object} from the {\bf Edit} menu.
\item Right-click on the object in the object editor.
\item Left-click on the object name in the object hierarchy window.
\end{enumerate}

\section{Deleting a window object}

An object may be deleted by selecting it with left click on the
object editor, and choosing {\bf Delete object} from the {\bf Edit} menu.

\section{Associating actions with events}

In order to give the interface some dynamics, a small repertoire
of actions is available for association with some events. For example, a menu
command called {\bf Open report window} might be associated with
with the {\bf Open window} action, to open another frame in the interface.

To create an action, execute the event you wish to associate with an
action. These events are currently:

\begin{itemize}
\item Menu commands
\item Button depression
\item Tool depression
\end{itemize}

You will be presented with a list of possible actions. Once you have
chosen an action, the appropriate action editor is invoked.

The next time you invoke the event in Edit mode, the action editor will
be presented. You may delete the action using the {\bf Delete} button.
In Test mode, the event will cause the appropriate action to be executed.

Currently, only one action per event is allowed. A later release of
wxBuilder may allow multiple events, so (for example) an event could
cause a window to be opened {\it and} a file to be loaded.

Note that some actions are mandatory for a working C++ program to be
generated. For example, a modal dialog box with no action dismissing it
will cause the window to be uncloseable, which might require the user to
quit the windowing system to recover.

\section{Converting Windows resource files}

Menu bars and dialog boxes can be converted from Windows resource files,
using Petr Smilauer's resource parser (Windows version of wxBuilder
only). Menu bars convert well, but due to the differences between
wxWindows panel items and Windows controls, dialog boxes convert less
well.

Use the {\bf Load Windows resources} option from the {\bf Edit}\rtfsp
menu. This opens a dialog box from which .RC files may be loaded,
or added to the existing database of resources. Once the resource
file has been loaded, quit from this dialog and use the\rtfsp
{\bf Convert menu bar} or {\bf Convert dialog} option from
the {\bf Edit} menu.

\chapter{Code generation details}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

Some or all of the following files may be generated:

\begin{itemize}
\item a header file (.H)
\item a main source file (.CC)
\item UNIX and DOS makefiles
\item a module definition file (.DEF)
\item a Windows resource file (.RC)
\end{itemize}

For every frame, dialog box and subwindow, a class is generated, to
allow customization for each window instance except for panel items.

Frames, dialog boxes and subwindows are generated with data members
for their contained windows. Pointers to all frame objects are held
in the wxApp-derived class.

The description property is used to document class declarations
and definitions.

If the user has specified actions for menu commands, buttons or tool bar
tools, the appropriate wxFrame::OnMenuCommand members functions,
wxToolBar::OnLeftClick member functions, or button callbacks are
generated with working code, otherwise empty stubs (or case statements)
are generated for the user to fill in.

Platform-specific resource loading is dealt with using conditional
compilation statements.

\chapter{Resources}\label{resources}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

The following is a list of the WIN.INI or .Xdefaults resources
associated with wxBuilder. Under Windows, the resources follow the {\tt
[wxBuilder]} section in WIN.INI. Under X, each resource name
should be prefixed by {\tt wxBuilder.} in the .Xdefaults file.

\begin{twocollist}
\twocolitemruled{{\bf Resource}}{{\bf Description}}
\twocolitem{autoCompile}{1 or 0.}
\twocolitem{autoRun}{1 or 0 (not implemented).}
\twocolitem{compilerDOS}{The name of the compiler in the DOS/Windows environment.}
\twocolitem{compilerUNIX}{The name of the compiler in the UNIX environment.}
\twocolitem{xIncludes}{List of X include directories.}
\twocolitem{xLib}{List of X include directories.}
\twocolitem{extraIncludesX}{List of extra include directories (under UNIX).}
\twocolitem{extraLibsX}{List of extra library directories (under UNIX).}
\twocolitem{extraIncludesMSW}{List of extra include directories (under Windows).}
\twocolitem{extraLibsMSW}{List of extra library directories (under Windows).}
\twocolitem{wxDirUNIX}{wxWindows directory under UNIX.}
\twocolitem{wxDirDOS}{wxWindows directory under DOS.}
\twocolitem{mainX}{Main wxBuilder window X coordinate.}
\twocolitem{mainY}{Main wxBuilder window Y coordinate.}
\twocolitem{mainWidth}{Main wxBuilder window width.}
\twocolitem{mainHeight}{Main wxBuilder window height.}
\twocolitem{reportX}{Report window X coordinate.}
\twocolitem{reportY}{Report window Y coordinate.}
\twocolitem{reportWidth}{Report window width.}
\twocolitem{reportHeight}{Report window height.}
\twocolitem{treeX}{Tree window X coordinate.}
\twocolitem{treeY}{Tree window Y coordinate.}
\twocolitem{treeWidth}{Tree window width.}
\twocolitem{treeHeight}{Tree window height.}
\twocolitem{paletteX}{Palette X coordinate.}
\twocolitem{paletteY}{Palette Y coordinate.}
\end{twocollist}

\begin{comment}
\chapter{Error and warning messages}\label{errmessages}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
\end{comment}

\addcontentsline{toc}{chapter}{Index}
\printindex
\end{document}