\documentstyle[a4wide,makeidx,verbatim]{article}
\input psbox.tex
% Remove this for processing with dvi2ps instead of dvips
% \special{!/@scaleunit 1 def}

\parskip=10pt

\title{Tutorial for wxWindows: a portable GUI toolkit for C++}
\author{Julian Smart\\Artificial Intelligence Applications Institute\\
University of Edinburgh\\EH1 1HN}
\date{January 1993}

%\parindent=0 pt

\newcommand{\func}[3]{\hangafter=1\noindent\hangindent=10mm
{\bf #1 #2\index{#2}}(#3)}

% For function/type definition where the name is a pointer,
% e.g. to typeset
%
% typedef void (*wxFunction)(wxObject&)
%
% write:
%
% \pfunc{typedef void}{wxFunction}{param{wxObject&}}

\newcommand{\pfunc}[3]{\hangafter=1\noindent\hangindent=10mm
{\bf #1 (*#2)\index{#2}}(#3)}

\newcommand{\member}[2]{{\bf #1 \it #2}}

\newcommand{\param}[2]{{\bf #1}{\it #2}}

\newcommand{\class}[1]{#1\index{#1}}

\newcommand{\void}{{\bf void}}

\newcommand{\destruct}[1]{{$\sim$}#1}

\makeindex
\begin{document}
\maketitle

\section{Introduction}

This short tutorial accompanies the main wxWindows 1.30 manual, and takes
a look at some of the supplied demonstration programs.  The tutorial
is incomplete and may be expanded in later releases.

\section{The demo programs}

\subsection{A minimal wxWindows program}

The best way to get a feel for how to use a tool is to see a small
example.  The supplied demo `minimal' (source file {\tt minimal.cc})
shows a rudimentary wxWindows program. It has a main window with a panel
inside it, displaying a message. There is a menu bar with a {\bf File} menu
which in turn has a {\bf Quit} option, and the program has its own icon. Under
Windows 3, the system menu shows the usual options including Minimize,
Maximize and Close, and under X, there is a similar pull-down system
menu provided by the current window manager. The window is resizeable,
and the panel automatically resizes to fit its parent.

Look at {\tt minimal.cc}.

\verbatiminput{../samples/minimal/minimal.cc}

The statement {\tt \#include "wx.h"} provides the program with access to
all the wxWindows classes and functions.

The first class declaration, {\bf MyApp}, declares a new application,
overriding one member function {\bf OnInit}. This is an essential part
of writing a wxWindows program, since {\bf OnInit} is the equivalent of
{\bf main} in a normal C++ program.

The class {\bf MyFrame} declares a constructor, and a message handler
for intercepting menu commands.

The definition of the global variable {\bf myApp} looks innocuous enough
but this starts the whole application going simply by being defined.

The {\bf OnInit} MyApp member function does the initialization of
the program. It creates a main frame, sets the icon,
creates a menu bar, a panel, and a panel item.

The {\bf MyFrame} constructor may seem a little pointless, but it
fulfils the requirements of Microsoft C/C++ syntax in defining
the constructor in terms of its parent's constructor.

The {\bf OnMenuCommand} definition intercepts menu commands for the main
frame. If the option chosen is {\bf Quit}, the application terminates by
deleting the main frame. Normally any other existing frames should be
deleted (subframes are deleted automatically); these calls are usually put
in the frame's {\bf OnClose} handler so that a system-generated {\bf
OnClose} event will enable the program to clean itself up first.
System-generated {\bf OnClose} events delete the main frame after calling
{\bf OnClose}, so this should not be done from within {\bf OnClose}.

\subsection{More advanced features: the {\it hello} demo}

The `hello' (source files, {\tt hello.cc} and {\tt hello.h} shows off
some more wxWindows features (see Figures \ref{demo-x} and
\ref{demo-ms}).  When run, two windows pop up. One is the `main window',
with two subwindows - a panel containing various `widgets', and a text
window.  The other contains a canvas, drawing some simple shapes, and
allowing the user to doodle on it by dragging with the left mouse
button.  The canvas contents can be scaled and printed out, either to a
printer supported by Windows or to PostScript, writing to a
file or invoking the printer directly. Under Windows, the graphic may be
copied to the clipboard as a metafile.

\begin{figure}
$$\psboxto(11cm;0cm){hello_x.eps}
$$
\caption{Demo program running under X}\label{demo-x}

\end{figure}
\begin{figure}
$$\psboxto(11cm;0cm){hello_w.eps}
$$
\caption{Demo program running under Windows 3}\label{demo-ms}
\end{figure}

Both frames can be resized, and the subwindows will be resized
in an appropriate manner. The text subwindow can be scrolled;
on the panel, a button can be pressed for the program to prompt the user
with text with which to set the status bar. Clicking on the
list box writes a line of text into the text window.

The {\bf File} menu has options for selecting the `mapping mode' (logical
dimensions) used in drawing graphics, a zoom option, and an option for
loading a file into the text subwindow using a file selector tool.

The {\bf Timer} menu allows the user to switch a timer on and off; when on,
some text gets written to the text subwindow every five seconds.

The {\bf Cursor} menu enables the canvas cursor to be changed, and lets
the potential wxWindows programmer view the available standard cursors.

The {\bf About} option of the Help menu pops up a dialog box with some
information.

This represents a fair amount of GUI functionality for a relatively
small program. This is because wxWindows calls are high level (creating
a working text window is a single call) and because an object-oriented
approach is taken, where much default functionality is provided.

Note also the lack of explicit coordinates or sizes in the panel item
creation calls. This is the preferred approach, leaving wxWindows to lay
out the items from left to right and top to bottom, with the user
interjecting the occasional {\bf NewLine} call.  Explicit positioning is
not recommended since it is less device independent, but can be achieved
by using more parameters to the creation calls, or by using {\bf
SetSize} after an item has been created.  Coordinates and sizes default
to -1, which tells wxWindows to choose appropriate positioning and
sizing.  In this example, the windows are explicitly sized, but you may
size a frame or panel to fit around its contents by calling {\bf Fit}.

{\bf MyFrame's} {\bf OnSize} member sizes each subwindow in proportion
to the new size of the frame. {\bf MyCanvas's} {\bf OnPaint} draws a
couple of lines, a rectangle and a spline whenever the canvas requires
repainting (e.g. on creation, and when exposed). The {\bf OnEvent}
member checks for mouse dragging, and draws a line from the last point
to the current position.  Scrolling the canvas and subsequent
repainting is handled automatically by wxWindows.

Finally, two callback functions demonstrate popping up dialog boxes,
setting the status line, and inserting text into a text window.

This demo can provide a template for your own application.
Gradually modify it for your own needs, and you will rapidly be
writing portable X and Windows 3 programs!

\subsection{The MDI demo}

As explained in the manual, wxWindows takes an automated view of
Microsoft Windows's MDI (Multiple Document Interface) since it is a very
platform-specific feature. The special MDI `Window' menu, allowing the
user to switch between child windows, is provided automatically, though
without any accelerators and without a choice of position. Also, instead
of deriving frames from distinct classes for MDI versus SDI, the
approach taken in Microsoft's class library, wxWindows uses an option in the frame
constructor to switch between styles. This allows the programmer to
delay the MDI/SDI decision, perhaps even providing a command-line switch
to let the user decide.

The {\bf mdi} example program shows this run-time switching. Invoked
without a command line switch, it defaults to SDI. Invoked with the
switch {\tt -mdi} it runs as an MDI program, but only under Windows 3.

There are a few extra considerations when programming an MDI
applications. One is the choice of menu items. An SDI program might have
a main window and several child windows, where the main window menu has
options for quitting the program and other global matters, while child
window menus have child-specific options. In MDI, the child window menu
visually replaces the main window menu when activated, and so it must
duplicate some main window menu options. One solution is to
include logic to add extra menu items depending on whether MDI or
SDI is specified, as the {\bf mdi} example does.

Also, for programs which must be both SDI and MDI (on non-Windows 3
platforms SDI mode is mandatory), the main window must not have
subwindows (i.e. panels, canvases or text subwindows) since the client
area may be occupied with child MDI windows under Windows 3.

MDI icons pose a small technical difficulty, in that for some reason it
is not possible to use the same technique of dynamically painting the
icon onto the iconized frame client area as with SDI frames.
Consequently the programmer must insert some lines into the resource
file for providing icons (see mdi.rc) as well as using the SetIcon call
in the program for non-Windows 3 platforms. Only one icon image for child
MDI frames may be provided.

\subsection{The IPC demo}

The demo in the {\tt directory samples/ipc} shows how processes
may easily talks to each other synchronously (i.e. when A sends a message
to B, A waits for an answer). If you start {\tt server}, then {\tt client},
a new window should appear on top of the server window, which represents
the connection between server and client. Quitting the client causes
the connection to be broken and this window to disappear.

To illustrate `hot linking', click on the server's listbox. This sends
an {\it advise} message to the client, telling it to update its own
listbox. The reverse is not true, however.

A client may request information from the server. Select the {\bf Request}
menu item from the client's {\bf File} menu. The window which pops up
is created by the client and contains a message that the server sent back.

Selecting {\bf Execute} from the client's menu makes the server pop up a window.
Normally this would execute some command that the client wishes the server to run.

The {\bf Poke} menu item sends a {\it poke} message to the server; normally
this would insert some data into the server's memory.

Interprocess communication in wxWindows uses a subset of DDE (Dynamic Data Exchange)
which is Microsoft's standard for low-level IPC under Windows. wxWindows
gives you DDE under UNIX as well as Windows, and makes it easier to program
into the bargain by using an intuitive object-oriented model of communication.

\subsection{The Object Graphics demo}

New to version 1.20 of wxWindows is a library of graphic calls to help with
manipulating objects on a canvas. The demo in {\tt samples/objects} shows
a simple application where the user can create new rectangles and ellipses,
join them up, label them, move them about, resize them, and delete them.

This library is not yet documented but I hope that most of it is
reasonably intuitive from the header file {\tt graphics.h} and from
the demo source code.  Some of the features may be tricky to spot,
however, such as multiple-segment lines and splines, attachment points on
shapes, auto-straightening of line segments, manual repositioning of
line endpoints, newlines in text labels (\%n).

\end{document}
