\helpignore{
\chapter{Classes and data types}

\section{Class hierarchy}

The GUI-specific wxWindows class hierarchy is shown in Figure 5.1.
Many other, non-GUI classes have been omitted.

\vskip 1cm
$$\psboxto(14cm;0cm){wxclasses.ps}$$
\vskip 1cm
\centerline{Figure 5.1: wxWindows class hierarchy}

\newpage

In the following descriptions of the wxWindows classes and their member
functions, note that descriptions of inherited member functions are not
duplicated in derived classes unless their behaviour is different. So in
using a class such as wxCanvas, be aware that wxWindow functions may be
relevant.

Note also that arguments with default values may be omitted from a
function call, for brevity. Size and position arguments may usually be
given a value of -1 (the default), in which case wxWindows will choose a
suitable value.

The member functions are given in alphabetical order except for the
constructors and destructors which appear first.
}

\section{\class{wxApp}: wxObject}

The {\bf wxApp} class represents the application itself.  A wxWindows
application does not have a {\it main} procedure; the equivalent is the {\it OnInit}
member defined for a class derived from {\bf wxApp}. {\it
OnInit} must create and return a main window frame as a bare minimum.
If NULL is returned from {\it OnInit}, the application will exit.
Note that the program's command line arguments, represented by {\it
argc} and {\it argv}, are available from within {\bf wxApp} member functions.

An application closes by destroying all windows. Because all frames
must be destroyed for the application to exit, it is advisable to use
parent frames wherever possible when creating new frames, so that
deleting the top level frame will automatically delete child frames.
In emergencies the {\it wxExit} function can be called to kill the
application.

An example of defining an application follows:

\begin{verbatim}
class DerivedApp: public wxApp
{
 public:
  wxFrame *OnInit(void);
};

wxFrame *DerivedApp::OnInit(void)
{
  wxFrame *the_frame = new wxFrame(argv[0]);
  ...
  return the_frame;
}

MyApp DerivedApp;
\end{verbatim}

\membersection{wxApp::wxApp}

\func{void}{wxApp}{\void}

Constructor. Call implicitly with a definition of a wxApp object.

\membersection{wxApp::\destruct{wxApp}}

\func{void}{\destruct{wxApp}}{\void}

Destructor. Will be called implicitly if the wxApp object is created on the stack.

\membersection{wxApp::argc}

\member{int}{argc}

Number of command line arguments (after environment-specific processing).

\membersection{wxApp::argv}

\member{char **}{argv}

Command line arguments (after environment-specific processing).

\membersection{wxApp::Initialized}

\func{Bool}{Initialized}{\void}

Returns TRUE if the application has been initialized (i.e. if {\bf
OnInit} has returned successfully).  This can be useful for error
message routines to determine which method of output is best for the
current state of the program (some windowing systems may not like
dialogs to pop up before the main loop has been entered).

\membersection{wxApp::MainLoop}

\func{void}{MainLoop}{\void}

Called by wxWindows on creation of the application.  Override this if you wish
to provide your own (environment-dependent) main loop.

\membersection{wxApp::OnExit}

\func{void}{OnExit}{\void}

Provide this member function for any processing which needs to be done as
the application is about to exit.

\membersection{wxApp::OnInit}

\func{wxFrame *}{OnInit}{\void}

This must be provided by the application, and must create and return the
application's main window.

\section{\class{wxBrush}: wxObject}

A brush is a drawing tool for filling in areas. It is used for
painting the background of rectangles, ellipses, etc.  It has a colour
and a style - the style may be wxSOLID (normal) or wxTRANSPARENT (the
brush isn't used). On a monochrome display, the default behaviour is
to show all brushes as white. If you wish the policy to be `all
non-white colours are black', as with pens, uncomment the piece of
code documented in {\bf SetBrush} in wx\_dc.cc. Alternatively, set the
{\bf Colour} member of the device context to TRUE, and select
appropriate colours.

Do not initialize objects on the stack before the program commences,
since other required structures may not have been set up yet. Instead,
define global pointers to objects and create them in {\it OnInit} or
when required.

An application may wish to create brushes with different
characteristics dynamically, and there is the consequent danger that a
large number of duplicate brushes will be created. Therefore an
application may wish to get a pointer to a brush by using the global
list of brushes {\bf wxTheBrushList}, and calling the member function
{\bf FindOrCreateBrush}. See the entry for the \helpref{wxBrushList}
class.

\membersection{wxBrush::wxBrush}

\func{void}{wxBrush}{\void}

\func{void}{wxBrush}{\param{wxColour \&}{colour}, \param{int}{ style}}

\func{void}{wxBrush}{\param{char *}{colour\_name}, \param{int}{ style}}

Constructs a brush: uninitialized, initialized with an RGB colour and
a style, or initialized using a colour name and a style.  If the named
colour form is used, an appropriate {\bf wxColour} structure is found
in the colour database.

\membersection{wxBrush::\destruct{wxBrush}}

\func{void}{\destruct{wxBrush}}{\void}

Destructor, destroying the brush. Note that brushes should very rarely
be deleted since windows may contain pointers to them. All brushes
will be deleted when the application terminates.

\membersection{wxBrush::GetColour}

\func{wxColour\&}{GetColour}{\void}

Returns a reference to the brush colour.

\membersection{wxBrush::GetStyle}

\func{int}{GetStyle}{\void}

Returns the brush style (wxSOLID or wxTRANSPARENT).

\membersection{wxBrush::SetColour}

\func{void}{SetColour}{\param{wxColour \&}{colour}}

\func{void}{SetColour}{\param{char *}{colour\_name}}

\func{void}{SetColour}{\param{int}{ red}, \param{int}{ green}, \param{int}{ blue}}

The brush's colour is changed to the given colour.

\membersection{wxBrush::SetStyle}

\func{void}{SetStyle}{\param{int}{ style}}

Sets the brush style (wxSOLID or wxTRANSPARENT).

\section{\class{wxBrushList}: wxList}

A brush list is a list containing all brushes which have been created.
There is only one instance of this class: {\bf wxTheBrushList}.  Use
this object to search for a previously created brush of the desired
type and create it if not already found. In some windowing systems,
the brush may be a scarce resource, so it is best to reuse old
resources if possible.  When an application finishes, all brushes will
be deleted and their resources freed, eliminating the possibility of
`memory leaks'.

\membersection{wxBrushList::wxBrushList}

\func{void}{wxBrushList}{\void}

Constructor.  The application should not construct its own brush list:
use the object pointer {\bf wxTheBrushList}.

\membersection{wxBrushList::AddBrush}

\func{void}{AddBrush}{\param{wxBrush *}{brush}}

Used by wxWindows to add a brush to the list, called in the brush constructor.

\membersection{wxBrushList::FindOrCreateBrush}

\func{wxBrush *}{FindOrCreateBrush}{\param{wxColour *}{colour}, \param{int}{ style}}

\func{wxBrush *}{FindOrCreateBrush}{\param{char *}{colour\_name}, \param{int}{ style}}

Finds a brush of the given specification, or creates one and adds it to the list.

\membersection{wxBrushList::RemoveBrush}

\func{void}{RemoveBrush}{\param{wxBrush *}{brush}}

Used by wxWindows to remove a brush from the list.


\section{\class{wxButton}: wxItem}

\membersection{wxButton::wxButton}

\func{void}{wxButton}{\param{wxPanel *}{parent}, \param{wxFunction}{ func}, \param{char *}{label},\\
  \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1}}

Constructor, creating and showing a button.  If {\it width} or {\it
height} are omitted (or are less than zero), an appropriate size will
be used for the button.  {\it func} may be NULL; otherwise it is used
as the callback for the button.  Note that the cast (wxFunction) must
be used when passing your callback function name, or the compiler may
complain that the function does not match the constructor declaration.

\membersection{wxButton::\destruct{wxButton}}

\func{void}{\destruct{wxButton}}{\void}

Destructor, destroying the button.

\section{\class{wxCanvas}: wxWindow}

A canvas is a subwindow onto which graphics and text can be drawn, and mouse
and keyboard input can be intercepted.  At present, panel items cannot be
placed on a canvas.

To determine whether a canvas is colour or monochrome, test the canvas's
device context {\bf colour} Bool member variable.

\membersection{wxCanvas::wxCanvas}

\func{void}{wxCanvas}{\param{wxFrame *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1},
  \param{int}{ width = -1}, \param{int}{ height = -1},\\ \param{int}{ style = wxRETAINED}}

Constructor. The style parameter may be a combination (using the C++
logical `or' operator) of the following flags:

\begin{itemize}
\item wxBORDER, to give the canvas a thin border (Windows 3 only)
\item wxRETAINED, to give the canvas a backing store, making repainting much faster but
at a memory premium (XView and Motif only)
\end{itemize}

\membersection{wxCanvas::\destruct{wxCanvas}}

\func{void}{\destruct{wxCanvas}}{\void}

Destructor.

\membersection{wxCanvas::Clear}

\func{void}{Clear}{\void}

Clears the canvas (fills it with the current background brush).

\membersection{wxCanvas::DestroyClippingRegion}

\func{void}{DestroyClippingRegion}{\void}

Destroys the current clipping region so that none of the canvas is clipped.

\membersection{wxCanvas::DrawEllipse}

\func{void}{DrawEllipse}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width},
\param{float}{ height}}

Draws an ellipse contained in the rectangle with the given top left
corner, and with the given size.  The current pen is used for the
outline and the current brush for filling the shape.

\membersection{wxCanvas::DrawLine}

\func{void}{DrawLine}{\param{float}{ x1}, \param{float}{ y1}, \param{float}{ x2},
\param{float}{ y2}}

Draws a line from the first point to the second. The current pen is
used for drawing the line.

\membersection{wxCanvas::DrawLines}

\func{void}{DrawLines}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0}}

\func{void}{DrawLines}{\param{wxList *}{points}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0}}

Draw lines using an array of {\it points} of size {\it n}, or list of
pointers to points, adding the optional offset coordinate. The current
pen is used for drawing the lines.  The programmer is responsible for
deleting the list of points.

\membersection{wxCanvas::DrawPolygon}

\func{void}{DrawPolygon}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0}}

\func{void}{DrawPolygon}{\param{wxList *}{points}, \param{float}{ xoffset = 0},
\param{float}{ yoffset = 0}}

Draw a filled polygon using an array of {\it points} of size {\it n},
or list of pointers to points, adding the optional offset coordinate.
The current pen is used for drawing the outline, and the current brush
for filling the shape.  Using a transparent brush suppresses filling.
The programmer is responsible for deleting the list of points.

Note that wxWindows does not close the first and last points
automatically.

\membersection{wxCanvas::DrawPoint}

\func{void}{DrawPoint}{\param{float}{ x}, \param{float}{ y}}

Draws a point using the current pen.

\membersection{wxCanvas::DrawRectangle}

\func{void}{DrawRectangle}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width}, \param{float}{ height}}

Draws a rectangle with the given top left corner, and with the given
size.  The current pen is used for the outline and the current brush for
filling the shape.

\membersection{wxCanvas::DrawRoundedRectangle}

\func{void}{DrawRoundedRectangle}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width},
  \param{float}{ height}, \param{float}{ radius = 20}}

Draws a rectangle with the given top left corner, and with the given
size.  The corners are quarter-circles using the given radius. The
current pen is used for the outline and the current brush for filling
the shape.

\membersection{wxCanvas::DrawSpline}

\func{void}{DrawSpline}{\param{wxList *}{points}}

Draws a spline between all given control points, using the current
pen.  Doesn't delete the wxList and contents. The spline is drawn
using a series of lines, using an algorithm taken from the X drawing
program `XFIG'.

\func{void}{DrawSpline}{\param{float}{ x1}, \param{float}{ y1}, \param{float}{ x2}, \param{float}{ y2},
  \param{float}{ x3}, \param{float}{ y3}}

Draws a three-point spline using the current pen.

\membersection{wxCanvas::DrawText}

\func{void}{DrawText}{\param{char *}{text}, \param{float}{ x}, \param{float}{ y}}

Draws a text string at the specified point, using the current text font,
and the current text foreground and background colours.

\membersection{wxCanvas::GetDC}

\func{wxDC *}{GetDC}{\void}

Get a pointer to the canvas's device context. Note that the canvas's
apparent device context may be temporarily replaced by the application
using {\it SetContext}, so for example a printer context can be
substituted and programs using the canvas's device context will really
write to the printer. The canvas's {\it real} device context is
unaffected by {\it SetContext}.

\membersection{wxCanvas::ResetContext}

\func{void}{ResetContext}{\void}

Reset a canvas's context set by {\it SetContext}.

\membersection{wxCanvas::Scroll}

\func{void}{Scroll}{\param{int}{ x\_pos}, \param{int}{ y\_pos}}

Scrolls a canvas so the view start is at the given point. The
positions are in scroll units, not pixels, so to convert to pixels you
will have to multiply by the number of pixels per scroll increment.
If either parameter is -1, that position will be ignored (no change in
that direction).

\membersection{wxCanvas::SetBackground}

\func{void}{SetBackground}{\param{wxBrush *}{brush}}

Sets the current background brush for the canvas.  The brush should
not be deleted while being used by a canvas. All brushes are deleted
automatically when the application terminates.

\membersection{wxCanvas::SetClippingRegion}

\func{void}{SetClippingRegion}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width}, \param{float}{ height}}

Sets the clipping region for the canvas. The clipping region is a
rectangular area to which drawing is restricted.  Possible uses for
the clipping region are for clipping text or for speeding up canvas
redraws when only a known area of the screen is damaged.

\membersection{wxCanvas::SetContext}

\func{void}{SetContext}{\param{wxDC *}{dc}}

Set a substitute context for the canvas, so applications which think
they're drawing to canvases can be fooled into drawing to the printer.
Reset with {\it ResetContext}.

\membersection{wxCanvas::SetBrush}

\func{void}{SetBrush}{\param{wxBrush *}{brush}}

Sets the current brush for the canvas.  The brush is not copied, so
you should not delete the brush unless the canvas pen has been set to
another brush, or to NULL. Note that all pens and brushes are
automatically deleted when the program is exited.

\membersection{wxCanvas::SetFont}

\func{void}{SetFont}{\param{wxFont *}{font}}

Sets the current font for the canvas. The font is not copied, so you
should not delete the font unless the canvas pen has been set to
another font, or to NULL.

\membersection{wxCanvas::SetLogicalFunction}

\func{void}{SetLogicalFunction}{\param{int}{ function}}

Sets the current logical function for the canvas. The possible values
are:

\begin{itemize}
\item wxXOR
\item wxINVERT
\item wxOR\_REVERSE
\item wxAND\_REVERSE
\item wxCOPY
\end{itemize}

The default is wxCOPY, which simply draws with the current colour.
The others combine the current colour and the background using a
logical operation.  wxXOR is commonly used for drawing rubber bands or
moving outlines, since drawing twice reverts to the original colour.

\membersection{wxCanvas::SetPen}

\func{void}{SetPen}{\param{wxPen *}{pen}}

Sets the current pen for the canvas.  The pen is not copied, so you
should not delete the pen unless the canvas pen has been set to
another pen, or to NULL. Note that all pens and brushes are
automatically deleted when the program is exited.

\membersection{wxCanvas::SetScrollbars}

\func{void}{SetScrollbars}{\param{int}{ horiz\_pixels}, \param{int}{ vert\_pixels}, \param{int}{ x\_length}, \param{int}{ y\_length},\\
  \param{int }{x\_page}, \param{int}{ y\_page}}

Sets up vertical and/or horizontal scrollbars. The first pair of
parameters give the number of pixels per `scroll step', i.e. amount
moved when the up or down scroll arrows are pressed. These may be 0 or
less for no scrollbar. The second pair gives the length of scrollbar
in scroll steps, which effectively sets the size of the `virtual
canvas'.  The third pair gives the number of scroll steps in a `page',
i.e. amount moved when pressing above or below the scrollbar control,
or using page up/page down (not yet implemented).

For example, the following gives a canvas horizontal and vertical
scrollbars with 20 pixels per scroll step, a size of 50 steps (1000
pixels) in each direction, and 4 steps (80 pixels) to a page.

\begin{verbatim}
canvas->SetScrollbars(20, 20, 50, 50, 4, 4);
\end{verbatim}


\membersection{wxCanvas::SetTextBackground}

\func{void}{SetTextBackground}{\param{wxColour *}{colour}}

Sets the current text background colour for the canvas.  Do not
delete {\it colour}.

\membersection{wxCanvas::SetTextForeground}

\func{void}{SetTextForeground}{\param{wxColour *}{colour}}

Sets the current text foreground colour for the canvas. Do not
delete {\it colour}.

\membersection{wxCanvas::ViewStart}

\func{void}{ViewStart}{\param{int *}{x}, \param{int *}{ y}}

Get the position at which the visible portion of the canvas starts. If
either of the scrollbars is not at the home position, {\it x} and/or
{\it y} will be greater than zero.  Combined with {\bf GetClientSize},
the application can use this function to efficiently redraw only the
visible portion of the canvas.  The positions are in logical scroll
units, not pixels, so to convert to pixels you will have to multiply
by the number of pixels per scroll increment.

\section{\class{wxCheckBox}: wxItem}

A checkbox is a labelled box which is either on (checkmark is visible) or off (no checkmark).

\membersection{wxCheckBox::wxCheckBox}

\func{void}{wxCheckBox}{\param{wxPanel *}{parent}, \param{wxFunction}{ func},
\param{char *}{label},\\ \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1}}

Constructor, creating and showing a checkbox.  If {\it width} or {\it
height} are omitted (or are less than zero), an appropriate size will
be used for the check box.  {\it func} may be NULL; otherwise it is
used as the callback for the check box.  Note that the cast
(wxFunction) must be used when passing your callback function name, or
the compiler may complain that the function does not match the
constructor declaration.

\membersection{wxCheckBox::\destruct{wxCheckBox}}

\func{void}{\destruct{wxCheckBox}}{\void}

Destructor, destroying the checkbox.

\membersection{wxCheckBox::GetValue}

\func{Bool}{GetValue}{\void}

Gets the state of the checkbox, TRUE if it is checked, FALSE otherwise.

\membersection{wxCheckBox::SetValue}

\func{void}{SetValue}{\param{Bool}{ state}}

Sets the checkbox to the given state: if the state is TRUE, the check is on,
otherwise it is off.


\section{\class{wxChoice}: wxItem}

A choice item is used to select one of a list of strings. Unlike a
listbox, only the selection is visible until the user pulls down the
menu of choices. Under XView and Motif, all selections are visible
when the menu is displayed. Under Windows 3, a scrolling list is
displayed when the user wants to change the selection. Note that under
XView, creating a choice item with a large number of strings takes a
long time due to the inefficiency of Sun's implementation of the XView
choice item.

\membersection{wxChoice::wxChoice}

\func{void}{wxChoice}{\param{wxPanel *}{parent}, \param{wxFunction}{ func},
\param{char *}{label}, \\\param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1}, \param{int}{ n}, \param{char *}{choices[]}}

Constructor, creating and showing a choice. If {\it width} or {\it
height} are omitted (or are less than zero), an appropriate size will be
used for the choice. {\it func} may be NULL; otherwise it is used as
the callback for the choice.  Note that the cast (wxFunction) must be
used when passing your callback function name, or the compiler may
complain that the function does not match the constructor declaration.

{\it n} is the number of possible choices, and {\it choices} is an
array of strings of size {\it n}. wxWindows allocates its own memory
for these strings so the calling program must deallocate the array
itself.

\membersection{wxChoice::\destruct{wxChoice}}

\func{void}{\destruct{wxChoice}}{\void}

Destructor, destroying the choice item.

\membersection{wxChoice::Append}

\func{void}{Append}{\param{char *}{ item}}

Adds the item to the end of the choice item. {\it item} must be
deallocated by the calling program, i.e. wxWindows makes its own copy.

\membersection{wxChoice::Clear}

\func{void}{Clear}{\void}

Clears the strings from the choice item. Under XView, this is done
by deleting and reconstructing the item, but it doesn't redisplay
properly until the user refreshes the window.

\membersection{wxChoice::FindString}

\func{int}{FindString}{\param{char *}{s}}

Finds a choice matching the given string, returning the position if found, or
-1 if not found.

\membersection{wxChoice::GetSelection}

\func{int}{GetSelection}{\void}

Gets the id (position) of the selected string.

\membersection{wxChoice::GetStringSelection}

\func{char *}{GetStringSelection}{\void}

Gets the selected string. This must be copied by the calling program
if long term use is to be made of it.

\membersection{wxChoice::SetSelection}

\func{void}{SetSelection}{\param{int}{ n}}

Sets the choice by passing the desired string position.

\membersection{wxChoice::SetStringSelection}

\func{void}{SetStringSelection}{\param{char *}{ s}}

Sets the choice by passing the desired string.

\membersection{wxChoice::String}

\func{char *}{String}{\param{int}{ n}}

Returns a temporary pointer to the string at position {\it n}.

\section{\class{wxClient}: wxIPCObject}

A wxClient object represents the client part of a client-server DDE
(Dynamic Data Exchange) conversation (available in {\it both}\/
Windows and UNIX). \helpignore{See section \ref{ipc}.}

\membersection{wxClient::wxClient}

\func{void}{wxClient}{\void}

Constructs a client object.

\membersection{wxClient::MakeConnection}

\func{wxConnection *}{MakeConnection}{\param{char *}{host}, \param{char *}{service}, \param{char *}{topic}}

Tries to make a connection with a server specified by the host
(machine name under UNIX, ignored under Windows), service name (must
contain an integer port number under UNIX), and topic string. If the
server allows a connection, a wxConnection object will be returned.
The type of wxConnection returned can be altered by deriving the {\bf
OnMakeConnection} member to return your own derived connection object.

\membersection{wxClient::OnMakeConnection}

\func{wxConnection *}{OnMakeConnection}{\void}

The type of wxConnection returned from a {\bf MakeConnection} call can
be altered by deriving the {\bf OnMakeConnection} member to return your
own derived connection object. By default, an ordinary wxConnection
object is returned.

\section{\class{wxColour}: wxObject}

A colour is an object representing a Red, Green, Blue (RGB) combination
of primary colours, and is used to determine drawing colours. See the
entry for \helpref{wxColourDatabase} for how a pointer to a predefined,
named colour may be returned instead of creating a new colour.

\membersection{wxColour::wxColour}

\func{void}{wxColour}{\param{char}{ red}, \param{char}{ green}, \param{char}{ blue}}

\func{void}{wxColour}{\param{char *}{ colour\_name}}

Construct a colour object from the RGB values or using a colour name
(uses {\bf wxTheColourDatabase}).

\membersection{wxColour::Get}

\func{void}{Get}{\param{char *}{ red}, \param{char *}{ green}, \param{char *}{ blue}}

Gets the RGB values - pass pointers to three char variables.

\membersection{wxColour::Set}

\func{void}{Set}{\param{char}{ red}, \param{char}{ green}, \param{char}{ blue}}

Sets the RGB value.

\section{\class{wxColourDatabase}: wxObject}

wxWindows maintains a database of standard RGB colours for a predefined
set of named colours (such as ``BLACK'', ``LIGHT GREY''). The
application may add to this set if desired by using {\it Append}.  There
is only one instance of this class: {\bf wxTheColourDatabase}.

The colours in the standard database are as follows:

AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL,
CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK
ORCHID, DARK SLATE BLUE, DARK SLATE GREY DARK TURQUOISE, DIM GREY,
FIREBRICK, FOREST GREEN, GOLD, GOLDENROD, GREY, GREEN, GREEN YELLOW,
INDIAN RED, KHAKI, LIGHT BLUE, LIGHT GREY, LIGHT STEEL BLUE, LIME GREEN,
MAGENTA, MAROON, MEDIUM AQUAMARINE, MEDIUM BLUE, MEDIUM FOREST GREEN,
MEDIUM GOLDENROD, MEDIUM ORCHID, MEDIUM SEA GREEN, MEDIUM SLATE BLUE,
MEDIUM SPRING GREEN, MEDIUM TURQUOISE, MEDIUM VIOLET RED, MIDNIGHT BLUE,
NAVY, ORANGE, ORANGE RED, ORCHID, PALE GREEN, PINK, PLUM, PURPLE, RED,
SALMON, SEA GREEN, SIENNA, SKY BLUE, SLATE BLUE, SPRING GREEN, STEEL
BLUE, TAN, THISTLE, TURQUOISE, VIOLET, VIOLET RED, WHEAT, WHITE, YELLOW,
YELLOW GREEN.

Note that wxWindows' colour handling in XView and Motif canvases is
poor and so only some of these colours are likely to show up. This
should be improved in a subsequent release.

\membersection{wxColourDatabase::wxColourDatabase}

\func{void}{wxColourDatabase}{\void}

Constructs the colour database.  Should not need to be used by an 
application.

\membersection{wxColourDatabase::FindColour}

\func{wxColour *}{FindColour}{\param{char *}{colour\_name}}

Finds a colour given the name.  Returns NULL if not found.

\membersection{wxColourDatabase::FindName}

\func{char *}{FindName}{\param{wxColour\&}{ colour}}

Finds a colour name given the colour. Returns NULL if not found.

\membersection{wxColourDatabase::Initialize}

\func{char *}{Initialize}{\void}

Initializes the database with a number of stock colours.  Called by wxWindows
on start-up.

\section{\class{wxConnection}: wxObject}

A wxConnection object represents the connection between a client and a
server. It can be created by making a connection using a client object, or
by the acceptance of a connection by a server object. It implements the
bulk of a DDE (Dynamic Data Exchange) conversation (available in {\it
both}\/ Windows and UNIX).  \helpignore{See section \ref{ipc}.}

\membersection{wxConnection::wxConnection}

\func{void}{wxConnection}{\void}

\func{void}{wxConnection}{\param{char *}{buffer}, \param{int}{ size}}

Constructs a connection object. If no user-defined connection object is
to be derived from wxConnection, then the constructor should not be
called directly, since the default connection object will be provided on
requesting (or accepting) a connection. However, if the user defines his
or her own derived connection object, the {\bf Server::OnAcceptConnection}
and/or {\bf Client::OnMakeConnection} members should be replaced by
functions which construct the new connection object. If the arguments of
the wxConnection constructor are void, then a default buffer is
associated with the connection. Otherwise, the programmer must provide a
a buffer and size of the buffer for the connection object to use in
transactions.

\membersection{wxConnection::Advise}

\func{Bool}{Advise}{\param{char *}{item}, \param{char *}{data}, \param{int}{ size = -1}, \param{int}{ format = wxCF\_TEXT}}

Called by the server application to advise the client of a change in the
data associated with the given item. Causes the client connection's {\bf
OnAdvise} member to be called. Returns TRUE if successful.

\membersection{wxConnection::Execute}

\func{Bool}{Execute}{\param{char *}{data}, \param{int}{ size = -1},
\param{int}{ format = wxCF\_TEXT}}

Called by the client application to execute a command on the server. Can
also be used to transfer arbitrary data to the server (similar to {\bf
Poke} in that respect). Causes the server connection's {\bf OnExecute} member
to be called. Returns TRUE if successful.

\membersection{wxConnection::Disconnect}

\func{Bool}{Disconnect}{\void}

Called by the client or server application to disconnect from the other
program; it causes the {\bf OnDisconnect} message to be sent to the
corresponding connection object in the other program. The default
behaviour of {\bf OnDisconnect} is to delete the connection, but the
calling application must explicitly delete its side of the connection
having called {\bf Disconnect}. Returns TRUE if successful.

\membersection{wxConnection::OnAdvise}

\func{Bool}{OnAdvise}{\param{char *}{topic}, \param{char *}{item}, \param{char *}{data}, \param{int}{ size}, \param{int}{ format}}

Message sent to the client application when the server notifies it of a
change in the data associated with the given item.

\membersection{wxConnection::OnDisconnect}

\func{Bool}{OnDisconnect}{\void}

Message sent to the client or server application when the other
application notifies it to delete the connection. Default behaviour is
to delete the connection object.

\membersection{wxConnection::OnExecute}

\func{Bool}{OnExecute}{\param{char *}{topic}, \param{char *}{data}, \param{int}{ size}, \param{int}{ format}}

Message sent to the server application when the client notifies it to
execute the given data. Note that there is no item associated with
this message.

\membersection{wxConnection::OnPoke}

\func{Bool}{OnPoke}{\param{char *}{topic}, \param{char *}{item}, \param{char *}{data}, \param{int}{ size}, \param{int}{ format}}

Message sent to the server application when the client
notifies it to accept the given data.

\membersection{wxConnection::OnRequest}

\func{char *}{OnRequest}{\param{char *}{topic}, \param{char *}{item}, \param{int *}{size}, \param{int}{ format}}

Message sent to the server application when the client calls {\bf
Request}. The server should respond by returning a character string from
{\bf OnRequest}, or NULL to indicate no data.

\membersection{wxConnection::OnStartAdvise}

\func{Bool}{OnStartAdvise}{\param{char *}{topic}, \param{char *}{item}}

Message sent to the server application by the client, when the client
wishes to start an `advise loop' for the given topic and item. The
server can refuse to participate by returning FALSE.

\membersection{wxConnection::OnStopAdvise}

\func{Bool}{OnStopAdvise}{\param{char *}{topic}, \param{char *}{item}}

Message sent to the server application by the client, when the client
wishes to stop an `advise loop' for the given topic and item. The
server can refuse to stop the advise loop by returning FALSE, although
this doesn't have much meaning in practice.

\membersection{wxConnection::Poke}

\func{Bool}{Poke}{\param{char *}{item}, \param{char *}{data}, \param{int}{ size = -1}, \param{int}{ format = wxCF\_TEXT}}

Called by the client application to poke data into the server. Can
be used to transfer arbitrary data to the server. Causes the server
connection's {\bf OnPoke} member to be called. Returns TRUE if
successful.

\membersection{wxConnection::Request}

\func{char *}{Request}{\param{char *}{item}, \param{int *}{size}, \param{int}{ format = wxCF\_TEXT}}

Called by the client application to request data from the server. Causes
the server connection's {\bf OnRequest} member to be called. Returns a
character string (actually a pointer to the connection's buffer) if
successful, NULL otherwise.

\membersection{wxConnection::StartAdvise}

\func{Bool}{StartAdvise}{\param{char *}{item}}

Called by the client application to ask if an advise loop can be started
with the server. Causes the server connection's {\bf OnStartAdvise}
member to be called. Returns TRUE if the server okays it, FALSE
otherwise.

\membersection{wxConnection::StopAdvise}

\func{Bool}{StopAdvise}{\param{char *}{item}}

Called by the client application to ask if an advise loop can be
stopped. Causes the server connection's {\bf OnStopAdvise} member to be
called. Returns TRUE if the server okays it, FALSE otherwise.

\section{\class{wxCursor}: wxObject}

A cursor is a small bitmap usually used for denoting where the mouse
pointer is, with a picture that might indicate the interpretation of a
mouse click. As with icons, cursors in X and Windows 3 are created
in a different manner. Therefore, separate cursors will be created for the
different environments.  Platform-specific methods for creating a {\bf
wxCursor} object are catered for, and this is an occasion where
conditional compilation will probably be required (see \helpref{wxIcon} for
an example).

A single cursor object may be used in many windows (any subwindow type).
The wxWindows convention is to set the cursor for a window, as in X, rather
than to set it globally as in Windows 3, although a global {\bf
wxSetCursor} is also available for Windows 3 use.

Run the {\it hello} demo program to see what stock cursors are
available.

\membersection{wxCursor::wxCursor}

\func{void}{wxCursor}{\param{short}{ bits[]}, \param{int}{width},
\param{int}{ height}}

\func{void}{wxCursor}{\param{char *}{ cursor\_name}}

\func{void}{wxCursor}{\param{int}{ id}}

Constructor. A cursor can be created by passing an array of bits
(XView and Motif only) by passing a string name, or by passing a stock
cursor id. {\it cursor\_name} refers to a filename in X, or a
resource name in Windows 3.

The following stock cursor ids may be used:

\begin{itemize}
\item wxCURSOR\_ARROW
\item wxCURSOR\_BULLSEYE
\item wxCURSOR\_CHAR
\item wxCURSOR\_CROSS
\item wxCURSOR\_HAND
\item wxCURSOR\_IBEAM
\item wxCURSOR\_LEFT\_BUTTON
\item wxCURSOR\_MAGNIFIER
\item wxCURSOR\_MIDDLE\_BUTTON
\item wxCURSOR\_NO\_ENTRY
\item wxCURSOR\_PAINT\_BRUSH
\item wxCURSOR\_PENCIL
\item wxCURSOR\_POINT\_LEFT
\item wxCURSOR\_POINT\_RIGHT
\item wxCURSOR\_QUESTION\_ARROW
\item wxCURSOR\_RIGHT\_BUTTON
\item wxCURSOR\_SIZENESW
\item wxCURSOR\_SIZENS
\item wxCURSOR\_SIZENWSE
\item wxCURSOR\_SIZEWE
\item wxCURSOR\_SIZING
\item wxCURSOR\_SPRAYCAN
\item wxCURSOR\_WAIT
\item wxCURSOR\_WATCH
\end{itemize}

\membersection{wxCursor::\destruct{wxCursor}}

\func{void}{\destruct{wxCursor}}{\void}

Destroys the cursor. Unlike an icon, a cursor can be reused for more
than one window, and does not get destroyed when the window is
destroyed. wxWindows destroys all cursors on application exit.

\section{\class{wxDC}: wxObject}

A wxDC is {\it device context} onto which graphics and text can be drawn.
It is intended to represent a number of output devices in a generic way,
so a canvas has a device context and a printer also has a device context.
In this way, the same piece of code may write to a number of different devices,
if the device context is used as a parameter.

To determine whether a device context is colour or monochrome, test the
{\bf Colour} Bool member variable. To override wxWindows monochrome
graphics drawing behaviour, set this member to TRUE.

\membersection{wxDC::wxDC}

\func{void}{wxDC}{\void}

\func{void}{wxDC}{\param{wxCanvas *}{canvas}}

\func{void}{wxDC}{\param{char *}{driver}, \param{char *}{device}, \param{char *}{output}, \param{Bool }{interactive = TRUE}}

Constructor.  The third form may be called with three NULLs to put up a
default printer dialog in Windows or UNIX.  The only supported printer
type in UNIX is ``PostScript''; in Windows, specifying ``PostScript''
uses wxWindow's own Encapsulated PostScript driver, writing to a file
only. Otherwise, {\it device} indicates the type of printer and {\it
output} is an optional file for printing to. The {\it driver} parameter
is currently unused.  Use the {\it Ok} member to test whether the
constructor was successful in creating a useable device context.

The following global variables are defined in wxWindows, edited by the
user in the printer dialog and used by the PostScript driver. An
application may wish to set them to appropriate default values.

\begin{itemize}
\item char *wx\_portrait = TRUE
\item char *wx\_printer\_command =``lpr''
\item char *wx\_printer\_flags = ``''
\item Bool wx\_preview = TRUE
\item char *wx\_preview\_command = ``ghostview''
\item float wx\_printer\_scale\_x = 1.0
\item float wx\_printer\_scale\_y = 1.0
\item float wx\_printer\_translate\_x = 0.0
\item float wx\_printer\_translate\_y = 0.0
\item Bool wx\_print\_to\_file = FALSE
\end{itemize}

\membersection{wxDC::\destruct{wxDC}}

\func{void}{\destruct{wxDC}}{\void}

Destructor.

\membersection{wxDC::Blit}

\func{Bool}{Blit}{\param{float}{ xdest}, \param{float}{ ydest}, \param{float}{ width}, \param{float}{ height},\\
  \param{wxDC *}{source}, \param{float}{ xsrc}, \param{float}{ ysrc}, \param{int}{ logical\_func}}

Copy from a source DC to this DC, specifying the destination
coordinates, size of area to copy, source DC, source coordinates, and
logical function (see \helpref{SetLogicalFunction}).  See
\helpref{CreateCompatibleDC} for typical usage.

\membersection{wxDC::Clear}

\func{void}{Clear}{\void}

\membersection{wxDC::CreateCompatibleDC}

\func{wxDC *}{CreateCompatibleDC}{\void}

Creates and returns a device context compatible with this DC.
A bitmap must be selected into the new DC before it may be used for
anything.  Typical usage is as follows:

\begin{verbatim}
  wxDC *temp_dc = dc.CreateCompatibleDC();
  temp_dc->SelectObject(test_bitmap);
  dc.Blit(250, 50, BITMAP_WIDTH, BITMAP_HEIGHT, temp_dc, 0, 0);
  delete temp_dc;
\end{verbatim}

In future versions of wxWindows, this kind of DC will be used for
drawing graphics in memory, then copying to visible windows.


\membersection{wxDC::DestroyClippingRegion}

\func{void}{DestroyClippingRegion}{\void}

Destroys the current clipping region so that none of the DC is clipped.


\membersection{wxDC::DeviceToLogicalX}

\func{float}{DeviceToLogicalX}{\param{int}{ x}}

Convert device X coordinate to logical coordinate, using the current
mapping mode.

\membersection{wxDC::DeviceToLogicalY}

\func{float}{DeviceToLogicalY}{\param{int}{ y}}

Converts device Y coordinate to logical coordinate, using the current
mapping mode.

\membersection{wxDC::DrawEllipse}

\func{void}{DrawEllipse}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width}, \param{float}{ height}}

Draws an ellipse contained in the rectangle with the given top left corner, and with the
given size.  The current pen is used for the outline and the current brush for
filling the shape.

\membersection{wxDC::DrawIcon}

\func{void}{DrawIcon}{\param{wxIcon *}{icon}, \param{float}{ x}, \param{float}{ y}}

Draw an icon on the display (does nothing if the device context is PostScript).
This can be the simplest way of drawing bitmaps on a canvas. Icons and bitmaps in
X are currently monochrome only.

\membersection{wxDC::DrawLine}

\func{void}{DrawLine}{\param{float}{ x1}, \param{float}{ y1}, \param{float}{ x2}, \param{float}{ y2}}

Draws a line from the first point to the second. The current pen is used
for drawing the line.

\membersection{wxDC::DrawLines}

\func{void}{DrawLines}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0}}

\func{void}{DrawLines}{\param{wxList *}{points}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0}}

Draws lines using an array of {\it points} of size {\it n}, or list of
pointers to points, adding the optional offset coordinate. The current
pen is used for drawing the lines.  The programmer is responsible for
deleting the list of points.

\membersection{wxDC::DrawPolygon}

\func{void}{DrawPolygon}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0}}

\func{void}{DrawPolygon}{\param{wxList *}{points}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0}}

Draws a filled polygon using an array of {\it points} of size {\it n},
or list of pointers to points, adding the optional offset coordinate.
The current pen is used for drawing the outline, and the current brush
for filling the shape.  Using a transparent brush suppresses filling.
The programmer is responsible for deleting the list of points.

Note that wxWindows does not close the first and last points automatically.

\membersection{wxDC::DrawPoint}

\func{void}{DrawPoint}{\param{float}{ x}, \param{float}{ y}}

Draws a point using the current pen.

\membersection{wxDC::DrawRectangle}

\func{void}{DrawRectangle}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width}, \param{float}{ height}}

Draws a rectangle with the given top left corner, and with the given
size.  The current pen is used for the outline and the current brush
for filling the shape.

\membersection{wxDC::DrawRoundedRectangle}

\func{void}{DrawRoundedRectangle}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width}, \param{float}{ height}, \param{float}{ radius = 20}}

Draws a rectangle with the given top left corner, and with the given
size.  The corners are quarter-circles using the given radius. The
current pen is used for the outline and the current brush for filling
the shape.

\membersection{wxDC::DrawSpline}

\func{void}{DrawSpline}{\param{wxList *}{points}}

Draws a spline between all given control points, using the current
pen.  Doesn't delete the wxList and contents. The spline is drawn
using a series of lines, using an algorithm taken from the X drawing
program `XFIG'.

\func{void}{DrawSpline}{\param{float}{ x1}, \param{float}{ y1}, \param{float}{ x2}, \param{float}{ y2}, \param{float}{ x3}, \param{float}{ y3}}

Draws a three-point spline using the current pen.

\membersection{wxDC::DrawText}

\func{void}{DrawText}{\param{char *}{text}, \param{float}{ x}, \param{float}{ y}}

Draws a text string at the specified point, using the current text font,
and the current text foreground and background colours.

\membersection{wxDC::EndDoc}

\func{void}{EndDoc}{\void}

Ends a document (only relevant when outputting to a printer).

\membersection{wxDC::EndPage}

\func{void}{EndPage}{\void}

Ends a document page (only relevant when outputting to a printer).

\membersection{wxDC::GetMapMode}

\func{int}{GetMapMode}{\void}

Gets the {\it mapping mode} for the device context (see \helpref{SetMapMode}).

\membersection{wxDC::LogicalToDeviceX}

\func{int}{LogicalToDeviceX}{\param{float}{ x}}

Converts logical X coordinate to device coordinate, using the current
mapping mode.

\membersection{wxDC::LogicalToDeviceY}

\func{int}{LogicalToDeviceY}{\param{float}{ y}}

Converts logical Y coordinate to device coordinate, using the current
mapping mode.

\membersection{wxDC::Ok}

\func{Bool}{Ok}{\void}

Returns TRUE if the DC is ok to use.

\membersection{wxDC::SelectObject}

\func{void}{SelectObject}{\param{wxBitmap *}{bitmap}}

Selects the given bitmap into the device context, to use as the memory
bitmap. Drawing onto the DC is not yet allowed, but selecting the bitmap
into a DC created by using {\bf CreateCompatibleDC} allows you to then
use {\bf Blit} to copy the bitmap to a canvas. For this purpose, you
may find {\bf DrawIcon} easier to use instead, if your Windows bitmaps can
be converted to icon format.

\membersection{wxDC::SetBackground}

\func{void}{SetBackground}{\param{wxBrush *}{brush}}

Sets the current background brush for the DC.  Do not delete the brush - it will be
deleted automatically when the application terminates.

\membersection{wxDC::SetClippingRegion}

\func{void}{SetClippingRegion}{\param{float}{ x}, \param{float}{ y}, \param{float}{ width}, \param{float}{ height}}

Sets the clipping region for the DC. The clipping region is a rectangular area
to which drawing is restricted.  Possible uses for the clipping region are for clipping text
or for speeding up canvas redraws when only a known area of the screen is damaged.

\membersection{wxDC::SetBrush}

\func{void}{SetBrush}{\param{wxBrush *}{brush}}

Sets the current brush for the DC.  The brush is not copied, so you should not delete
the brush unless the DC pen has been set to another brush, or to NULL. Note that
all pens and brushes are automatically deleted when the program is exited.

\membersection{wxDC::SetFont}

\func{void}{SetFont}{\param{wxFont *}{font}}

Sets the current font for the DC. The font is not copied, so you should not delete
the font unless the DC pen has been set to another font, or to NULL.

\membersection{wxDC::SetLogicalFunction}

\func{void}{SetLogicalFunction}{\param{int}{ function}}

Sets the current logical function for the DC. The possible values are:

\begin{itemize}
\item wxXOR
\item wxINVERT
\item wxOR\_REVERSE
\item wxAND\_REVERSE
\item wxCOPY
\end{itemize}

The default is wxCOPY, which simply draws with the current colour.
The others combine the current colour and the background using a
logical operation.  wxXOR is commonly used for drawing rubber bands or
moving outlines, since drawing twice reverts to the original colour.

\membersection{wxDC::SetMapMode}

\func{void}{SetMapMode}{\param{int}{ int}}

The {\it mapping mode} of the device context defines the unit of
measurement used to convert logical units to device units. Note that
in X, text drawing isn't handled consistently with the mapping mode; a
font is always specified in point size. However, setting the {\it
user scale} (see \helpref{SetUserScale}) scales the text appropriately. In
Windows, scaleable TrueType fonts are always used; in X, results depend
on availability of fonts, but usually a reasonable match is found.

Note that the coordinate origin should ideally be selectable, but for
now is always at the top left of the screen/printer.

Drawing to a Windows printer device context under UNIX
uses the current mapping mode, but mapping mode is currently ignored for
PostScript output.

The mapping mode can be one of the following:

\begin{itemize}
\item MM\_TWIPS - each logical unit is 1/20 of a point, or 1/1440 of
  an inch
\item MM\_POINTS - each logical unit is a point, or 1/72 of an inch
\item MM\_METRIC - each logical unit is 1 mm
\item MM\_LOMETRIC - each logical unit is 1/10 of a mm
\item MM\_TEXT - each logical unit is 1 pixel
\end{itemize}


\membersection{wxDC::SetPen}

\func{void}{SetPen}{\param{wxPen *}{pen}}

Sets the current pen for the DC.  The pen is not copied, so you should
not delete the pen unless the DC pen has been set to another pen, or
to NULL. Note that all pens and brushes are automatically deleted when
the program is exited.

\membersection{wxDC::SetTextBackground}

\func{void}{SetTextBackground}{\param{wxColour *}{colour}}

Sets the current text background colour for the DC.  Do not delete {\it
colour} while selected for use by a DC.

\membersection{wxDC::SetTextForeground}

\func{void}{SetTextForeground}{\param{wxColour *}{colour}}

Sets the current text foreground colour for the DC. Do not delete {\it
colour} while selected for use by a DC.

\membersection{wxDC::SetUserScale}

\func{void}{SetUserScale}{\param{float}{ x\_scale}, \param{float}{y\_scale}}

Sets the user scaling factor, useful for applications which require
`zooming'.

\membersection{wxDC::StartDoc}

\func{Bool}{StartDoc}{\param{char *}{message}}

Starts a document (only relevant when outputting to a printer).
Message is a message to show whilst printing.

\membersection{wxDC::StartPage}

\func{Bool}{StartPage}{\void}

Starts a document page (only relevant when outputting to a printer).

\section{\class{wxDialogBox}: wxPanel}

A dialog box is similar to a panel, with the following exceptions:

\begin{enumerate}
\item A surrounding frame is implicitly created.
\item Extra functionality is automatically given to the dialog box,
  such as tabbing between items (currently Windows only).
\item If the dialog box is {\it modal}, the calling program is blocked
  until the dialog box is dismissed.
\end{enumerate}

Under XView, some panel items may display incorrectly in a modal dialog.
An XView bug-fix for list boxes is supplied with wxWindows, but some
items remain a problem.

Note that under Windows 3, modal dialogs have to be emulated using
modeless dialogs and a message loop. This is because Windows 3 expects
the contents of a modal dialog to be loaded from a resource file or
created on receipt of a dialog initialization message. This is too
restrictive for wxWindows, where any window may be created and displayed
before its contents are created.

It would be easy to add a facility for loading Windows 3 dialog
resources instead of building them programmatically, but of course this
method is very non-portable. \helpignore{See the discussion in section \ref{dialogs}.}

\helpignore{
For a set of dialog convenience functions, including file selection, see
Section \ref{dialog-functions}.}

\membersection{wxDialogBox::wxDialogBox}

\func{void}{wxDialogBox}{\param{wxFrame *}{parent}, \param{char *}{title},
\param{Bool}{ modal=FALSE},\\ \param{int}{ x=300}, \param{int}{ y=300}, 
  \param{int}{ width=500}, \param{int}{ height=500}}

Constructor.  If {\it modal} is TRUE, the dialog box will wait to be
dismissed (using {\tt Show(FALSE)}) before returning control to the
calling program.

\membersection{wxDialogBox::\destruct{wxDialogBox}}

\func{void}{\destruct{wxDialogBox}}{\void}

Destructor.  Deletes any panel items before deleting the physical window.

\membersection{wxDialogBox::Iconize}

\func{void}{Iconize}{\param{Bool}{ iconize}}

If TRUE, iconizes the dialog box; if FALSE, shows and restores it. Note
that in Windows, iconization has no effect since dialog boxes cannot be
iconized. However, applications may need to explicitly restore dialog
boxes under XView and Motif which have user-iconizable frames, and under Windows
calling {\tt Iconize(FALSE)} will bring the window to the front, as does
{\tt Show(TRUE)}.

\membersection{wxDialogBox::Iconized}

\func{Bool}{Iconized}{\void}

Returns TRUE if the dialog box is iconized. Always returns FALSE under
Windows for the reasons given above.

\membersection{wxDialogBox::Show}

\func{void}{Show}{\param{Bool}{ show}}


If {\it show} is TRUE, the dialog box is shown and brought to the front;
otherwise the box is hidden. If {\it show} is FALSE and the dialog is
modal, control is returned to the calling program.

\section{\class{wxEvent}: wxObject}

An event is a general-purpose structure holding information about an
event passed to a callback or member function.  Call member functions of
{\bf wxEvent} to find out information appropriate to the kind of event,
or query the wxWindow object itself (for example list box, canvas) to find out
the status of the object.

\membersection{wxEvent::wxEvent}

\func{void}{wxEvent}{\void}

Constructor. Should not need to be used by an application.

\membersection{wxEvent::\destruct{wxEvent}}

\func{void}{\destruct{wxEvent}}{\void}

Destructor. Should not need to be used by an application.

\membersection{wxEvent::Button}

\func{Bool}{Button}{\param{int}{ button}}

Returns TRUE if the identified mouse button is changing state. Valid values of {\it button}
are:

\begin{enumerate}
\item Left button
\item Middle button
\item Right button
\end{enumerate}

Not all mice have middle buttons so a portable application should avoid
this one.

\membersection{wxEvent::ButtonDown}

\func{Bool}{ButtonDown}{\void}

Returns TRUE if the event was a mouse button down event.

\membersection{wxEvent::ControlDown}

\func{Bool}{ControlDown}{\void}

Returns TRUE if the control button was down at the time of the event.

\membersection{wxEvent::Dragging}

\func{Bool}{Dragging}{\void}

Returns TRUE if this was a dragging event.

\membersection{wxEvent::IsButton}

\func{Bool}{IsButton}{\void}

Returns TRUE if the event was a mouse button event (not necessarily a button down event -
that may be tested using {\it ButtonDown}).

\membersection{wxEvent::LeftDown}

\func{Bool}{LeftDown}{\void}

Returns TRUE if the left mouse button changed to down.

\membersection{wxEvent::LeftUp}

\func{Bool}{LeftUp}{\void}

Returns TRUE if the left mouse button changed to up.

\membersection{wxEvent::MiddleDown}

\func{Bool}{MiddleDown}{\void}

Returns TRUE if the middle mouse button changed to down.

\membersection{wxEvent::MiddleUp}

\func{Bool}{MiddleUp}{\void}

Returns TRUE if the middle mouse button changed to up.

\membersection{wxEvent::Position}

\func{void}{Position}{\param{float *}{x}, \param{float *}{y}}

Sets *x and *y to the position at which the event occurred. If the
window is a canvas, the position is converted to logical units
(according to the current mapping mode) with scrolling taken into
account. To get back to device units (for example to calculate where on the
screen to place a dialog box associated with a canvas mouse event), use
{\bf wxDC::LogicalToDeviceX} and {\bf wxDC::LogicalToDeviceY}.

For example, the following code calculates screen pixel coordinates
from the frame position, canvas view start (assuming the canvas is the only
subwindow on the frame and therefore at the top left of it), and the
logical event position. A menu is popped up at the position where the
mouse click occurred. (Note that the application should also check that
the dialog box will be visible on the screen, since the click could have
occurred near the screen edge!)

\begin{verbatim}
float event_x, event_y;
event.Position(&event_x, &event_y);
frame->GetPosition(&x, &y);
canvas->ViewStart(&x1, &y1);
int mouse_x = (int)(canvas->GetDC()->LogicalToDeviceX(event_x + x - x1);
int mouse_y = (int)(canvas->GetDC()->LogicalToDeviceY(event_y + y - y1);

char *choice = wxGetSingleChoice("Menu", "Pick a node action",
                                 no_choices, choices, frame, mouse_x, mouse_y);
\end{verbatim}

\membersection{wxEvent::RightDown}

\func{Bool}{RightDown}{\void}

Returns TRUE if the right mouse button changed to down.

\membersection{wxEvent::RightUp}

\func{Bool}{RightUp}{\void}

Returns TRUE if the right mouse button changed to up.


\membersection{wxEvent::ShiftDown}

\func{Bool}{ShiftDown}{\void}

Returns TRUE if the shift button was down at the time of the event.

\section{\class{wxFont}: wxObject}

A font is an object which determines the appearance of text, primarily
when drawing text to a canvas or device context. A font is determined by
four parameters:

\begin{itemize}
\item Point size.  This is the standard way of referring to text size.
\item Family.  Supported families are:
  wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN.
  wxMODERN is a fixed pitch font; the others are either fixed or variable pitch.
\item Style. The value can be wxNORMAL, wxSLANT or wxITALIC.
\item Weight. The value can be wxNORMAL, wxLIGHT or wxBOLD.
\end{itemize}

There is currently a difference between the appearance of fonts on the
two platforms, if the mapping mode is anything other than MM\_TEXT.
Under X, font size is always specified in points. Under Windows, the
unit for text is points but the text is scaled according to the
current mapping mode.  However, user scaling on a device canvas will
also scale fonts under both environments. A future version of
wxWindows will attempt to make font appearance more consistent across
platforms.

\membersection{wxFont::wxFont}

\func{void}{wxFont}{\void}

\func{void}{wxFont}{\param{int}{ point\_size}, \param{int}{ family}, \param{int}{ style}, \param{int}{ weight}}

Creates a font object. If the desired font does not exist, the closest
match will be chosen. Under XView, this may result in a number of
XView warnings during the matching process; these should be ignored,
and will only occur the first time wxWindows attempts to use an absent
font in a given size. wxWindows under Motif does the same thing, but
silently. Under Windows 3, only scaleable TrueType fonts are used.

\membersection{wxFont::\destruct{wxFont}}

\func{void}{\destruct{wxFont}}{\void}

Destroys a font object. Do not manually destroy a font which has been
assigned to a canvas. All GDI objects, including fonts, are
automatically destroyed on program exit, so there is no danger of memory
leakage as in conventional Windows programming.

\membersection{wxFont::GetPointSize}

\func{int}{GetPointSize}{\void}

Gets the point size.


\section{\class{wxForm}: wxObject}

\subsection{The purpose of the form class}

The wxForm is a stab at providing form-like functionality, relieving the
programmer of the tedium of defining all the physical panel items and
the callbacks handling out-of-range data. It allows the application
writer to write form dialogs quickly (albeit programmatically) with
panel items being chosen automatically according to the given
constraints. The supplied form demo shows how succinct a form
definition can be. A form gets laid out from left to right; the
programmer can intersperse new lines and specify item sizes, but for
brevity no more control is allowed.

A form does not presuppose a particular type of panel: any window
derived from wxPanel may be associated with a form, once the form has
been built by adding form items. Also, a form reads from and writes to
any C++ variables in your program - just supply pointers to the variables,
and the form handles the rest.

\subsection{Constraints on form items}

Each item in a form may be supplied with zero or more constraints, where
the range of possible constraints depends on the data type, and the
displayed panel item depends upon the data type and the constraint(s)
given.  For example, a string form item with a list of possible strings
as a constraint will produce a list box on the panel; an integer form
item with a range constraint will result in a slider being displayed.
The user may define his or her own constraint by passing a function as a
constraint which returns FALSE if the constraint was violated, TRUE
otherwise.  The function should write an appropriate message into the
buffer passed to it if the constraint was violated.

\subsection{Form appearance}

Once displayed on a panel, a form shows Ok, Cancel, Update and Revert
buttons along the top, with the user-supplied items below. When the user
presses Ok, the form items are checked for violation of constraints; if
any violations are found, an appropriate error message is displayed and
the user must correct the mistake (or press Cancel, which leaves the
item values as they were after the last Update). Pressing Update also
checks the constraints and updates the values, but typically does not
dismiss the dialog. Revert causes the displayed values to take on the
values at the last Update. By default, the OnOk and OnCancel messages
dismiss and delete the dialog box and form, but these may be overridden
by the application (see below).

The display-type values which may be passed to a form-item creation
function are as follows:

\begin{itemize}
\item wxFORM\_DEFAULT: let wxWindows choose a suitable panel item
\item wxFORM\_SINGLE\_LIST: use a single-selection listbox. Default for
string item with a one-of constraint
\item wxFORM\_CHOICE: use a choice item
\item wxFORM\_CHECKBOX: use a checkbox. Default for boolean item
\item wxFORM\_TEXT: use a single-line text item. Default for floating
point item, and for string and integer items with no constraints
\item wxFORM\_MULTITEXT: use a multi-line text item
\item wxFORM\_SLIDER: use a slider. Default for integer item with range
constraint
\end{itemize}

The wxFormItem and wxFormItemConstraint classes are not detailed in this
manual since their members do not need to be directly accessed by the
user. Functions for creating form items and constraints for passing to
{\bf wxForm::Add} are given in the next subsection.

\subsection{Example}

The following is an example of a form definition, taken from the form demo.
Here, a new form {\bf MyForm} has been derived, and a new member {\bf
EditForm} has been defined to edit objects of the type {\bf MyObject},
given a panel to display it on.

\begin{verbatim}
void MyForm::EditForm(MyObject *object, wxPanel *panel)
{
  Add(wxMakeFormString("string 1", &(object->string1), wxFORM_DEFAULT,
                       new wxList(wxMakeConstraintFunction(MyConstraint), 0)));
  Add(wxMakeFormNewLine());

  Add(wxMakeFormString("string 2", &(object->string2), wxFORM_DEFAULT,
                  new wxList(wxMakeConstraintStrings("One", "Two", "Three", 0), 0)));
  Add(wxMakeFormString("string 3", &(object->string3), wxFORM_CHOICE,
                       new wxList(wxMakeConstraintStrings("Pig", "Cow",
                                  "Aardvark", "Gorilla", 0), 0)));
  Add(wxMakeFormNewLine());
  Add(wxMakeFormShort("int 1", &(object->int1), wxFORM_DEFAULT,
                       new wxList(wxMakeConstraintRange(0.0, 50.0), 0)));
  Add(wxMakeFormNewLine());

  Add(wxMakeFormFloat("float 1", &(object->float1), wxFORM_DEFAULT,
                       new wxList(wxMakeConstraintRange(-100.0, 100.0), 0)));
  Add(wxMakeFormBool("bool 1", &(object->bool1)));
  Add(wxMakeFormNewLine());

  Add(wxMakeFormButton("Test button", (wxFunction)MyButtonProc));

  AssociatePanel(panel);
}
\end{verbatim}

\membersection{wxForm::wxForm}

\func{void}{wxForm}{\void}

Constructor.

\membersection{wxForm::\destruct{wxForm}}

\func{void}{\destruct{wxForm}}{\void}

Destructor. Does not delete the associated panel or any panel items, but
does delete all form items.

\membersection{wxForm::Add}

\func{void}{Add}{\param{wxFormItem *}{item}, \param{long }{id = -1}}

Adds a form item to the form. If an id is given this is associated with
the form item; otherwise a new id is generated, by which the item may be
identified later.

\membersection{wxForm::FindItem}

\func{wxNode *}{FindItem}{\param{long }{id}}

Given a form item id, returns a list node containing the form item.

\membersection{wxForm::Set}

\func{Bool}{Set}{\param{long }{id}, \param{wxFormItem *}{item}}

Given a form item id, replaces an existing item with that id with the
given form item. Returns TRUE if successful.

\membersection{wxForm::Delete}

\func{Bool}{Delete}{\param{long }{id}}

Deletes the given form item by id. Returns TRUE if successful.

\membersection{wxForm::AssociatePanel}

\func{void}{AssociatePanel}{\param{wxPanel *}{panel}}

Associates the form with the given panel (or window derived from wxPanel, such as
wxDialogBox). This causes a number of items to be created on the panel
using information from the list of form items. The panel should be shown
after this has been called.

\membersection{wxForm::OnCancel}

\func{void}{OnCancel}{\void}

This member may be derived by the application. When the user presses the
Cancel button, this is called, allowing the application to take action.
By default, {\bf OnCancel} deletes the form and the panel associated with
it, probably the normal desired behaviour.

\membersection{wxForm::OnOk}

\func{void}{OnOk}{\void}

This member may be derived by the application. When the user presses the
OK button, this is called, allowing the application to take action.
By default, {\bf OnOk} deletes the form and the panel associated with
it, probably the normal desired behaviour. Note that if any form item
constraints were violated when the user pressed OK, the member does not
get called.

\membersection{wxForm::OnRevert}

\func{void}{OnRevert}{\void}

This member may be derived by the application. When the user presses the
Revert button, the C++ form item variable values in effect before the
last Update are restored.  Then this member is called, allowing the
application to take further action.

\membersection{wxForm::OnUpdate}

\func{void}{OnUpdate}{\void}

This member may be derived by the application. When the user presses the
Update button, the C++ form item variable values are updated to the
values on the panel.  Then this member is called, allowing the
application to take further action.

\membersection{wxForm::RevertValues}

\func{void}{RevertValues}{\void}

Internal function for displaying the C++ form item values in the
displayed panel items. Should not need to be called by the user.

\membersection{wxForm::UpdateValues}

\func{Bool}{UpdateValues}{\void}

Internal function for setting the C++ form item values to the values set
in the panel items. Should not need to be called by the user.

\subsection{Functions for making form items and constraints}

These functions make form items and their associated constraints for
passing to {\bf wxForm::Add}.

\func{wxFormItem *}{wxMakeFormButton}{\param{char *}{label},
\param{wxFunction}{ fun}}

Makes a button with a conventional callback.

\func{wxFormItem *}{wxMakeFormMessage}{\param{char *}{label}}

Makes a message.

\func{wxFormItem *}{wxMakeFormNewLine}{\void}

Adds a newline.

\func{wxFormItem *}{wxMakeFormLong}{\param{char *}{label}, \param{long *}{var},\\
  \param{int}{ item\_type = wxFORM\_DEFAULT}, \param{wxList *}{constraints = NULL},\\
  \param{char *}{help\_string = NULL}, \param{wxEditFunction}{ editor = NULL}, \param{int}{ width = -1},\\
  \param{int}{ height = -1}}

Makes a long integer form item, given a label, a pointer to the variable
holding the value, an item type, and a list of constraints (see below).
{\it help\_string} and {\it editor} are currently not used.


\func{wxFormItem *}{wxMakeFormShort}{\param{char *}{label}, \param{int *}{var},\\
  \param{int}{ item\_type = wxFORM\_DEFAULT}, \param{wxList *}{constraints = NULL},\\
  \param{char *}{help\_string = NULL}, \param{wxEditFunction}{ editor = NULL}, \param{int}{ width = -1},\\
  \param{int}{ height = -1}}

Makes an integer form item, given a label, a pointer to the variable
holding the value, an item type, and a list of constraints (see below).
{\it help\_string} and {\it editor} are currently not used.


\func{wxFormItem *}{wxMakeFormFloat}{\param{char *}{label}, \param{float *}{var},\\
  \param{int}{ item\_type = wxFORM\_DEFAULT}, \param{wxList *}{constraints = NULL},\\
  \param{char *}{help\_string = NULL}, \param{wxEditFunction}{ editor = NULL},
  \param{int}{ width = -1},\\
  \param{int}{ height = -1}}

Makes a floating-point form item, given a label, a pointer to the variable
holding the value, an item type, and a list of constraints (see below).
{\it help\_string} and {\it editor} are currently not used.


\func{wxFormItem *}{wxMakeFormBool}{\param{char *}{label}, \param{Bool *}{var},\\
  \param{int}{ item\_type = wxFORM\_DEFAULT}, \param{wxList *}{constraints = NULL},\\
  \param{char *}{help\_string = NULL}, \param{wxEditFunction}{ editor = NULL}, \param{int}{ width = -1},\\
  \param{int}{ height = -1}}

Makes a boolean form item, given a label, a pointer to the variable
holding the value, an item type, and a list of constraints (see below).
{\it help\_string} and {\it editor} are currently not used.

\func{wxFormItem *}{wxMakeFormString}{\param{char *}{label}, \param{char **}{var},\\
  \param{int}{ item\_type = wxFORM\_DEFAULT}, \param{wxList *}{constraints = NULL},\\
  \param{char *}{help\_string = NULL}, \param{wxEditFunction}{ editor = NULL},
  \param{int}{ width = -1},\\
  \param{int}{ height = -1}}

Makes a string form item, given a label, a pointer to the variable
holding the value, an item type, and a list of constraints (see below).
{\it help\_string} and {\it editor} are currently not used.


\func{wxFormItemConstraint *}{wxMakeConstraintStrings}{\param{wxList *}{list}}

Makes a constraint specifying that the value must be one of the strings
given in the list.

\func{wxFormItemConstraint *}{wxMakeConstraintStrings}{\param{char *}{first}, \param{}{...}}

Makes a constraint specifying that the value must be one of the strings
given in the variable-length argument list,{\it terminated with a zero}.

\func{wxFormItemConstraint *}{wxMakeConstraintFunction}{\param{wxConstraintFunction }{func}}

Makes a constraint with a function that gets called when the value is
being checked. The function should return FALSE if the constraint was
violated, TRUE otherwise.  The function should also write an appropriate
message into the buffer passed to it if the constraint was violated.
The type {\bf wxConstraintFunction} is defined as follows:

\pfunc{typedef Bool}{wxConstraintFunction}{\param{int}{ type}, \param{char *}{value}, \param{char *}{label}, \param{char *}{msg}}

 {\it type} is the type of the item, for instance wxFORM\_STRING. {\it value} is
the address of the variable containing the value, and should be coerced
to the correct type, except for wxFORM\_STRING, where no coercion is required.

\func{wxFormItemConstraint *}{wxMakeConstraintRange}{\param{float}{ lo}, \param{float}{ hi}}

Makes a range constraint; can be used for integer and floating point
form items.

\section{\class{wxFrame}: wxWindow}

A frame is a window which contains subwindows of various kinds. It has a
title bar and, optionally, a menu bar, and a status line.  Depending on
the platform, the frame has further menus or buttons relating to window
movement, sizing, closing, etc. Most of these events are handled by the host
system without need for special handling by the application. However,
the application should normally define an {\bf OnClose} handler for the
frame so that related data and subwindows can be cleaned up.

The Windows 3 issues of Multiple Document Interface (MDI) versus Single
Document Interface (SDI) frames are covered in section \ref{mdi} and in
the tutorial.

\membersection{wxFrame::wxFrame}

\func{void}{wxFrame}{\param{wxFrame *}{parent}, \param{char *}{title}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1}, \param{int}{ style = wxSDI}}

Constructor.  The {\it parent} parameter can be NULL or an existing frame.
The final parameter determines whether, under Windows, the frame is an
SDI frame (wxSDI), an MDI parent frame (wxMDI\_PARENT) or an MDI child
frame (wxMDI\_CHILD).

\membersection{wxFrame::\destruct{wxFrame}}

\func{void}{\destruct{wxFrame}}{\void}

Destructor. Destroys all child windows and menu bar if present.

\membersection{wxFrame::Centre}

\func{void}{Centre}{\param{int}{ direction = wxBOTH}}

Centres the frame on the display. The parameter may be {\tt
wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.

\membersection{wxFrame::CreateStatusLine}

\func{void}{CreateStatusLine}{\void}

Creates a status line at the bottom of the frame. The width of the
status line is the whole width of the frame (adjusted automatically when
resizing), and the height and text size are chosen by the host system.
Does not work for MDI parent frames.

\membersection{wxFrame::Iconize}

\func{void}{Iconize}{\param{Bool}{ iconize}}

If TRUE, iconizes the frame; if FALSE, shows and restores it.

\membersection{wxFrame::Iconized}

\func{Bool}{Iconized}{\void}

Returns TRUE if the frame is iconized.


\membersection{wxFrame::OnMenuCommand}

\func{void}{OnMenuCommand}{\param{int}{ id}}

Sent to the window when an item on the window's menu has been chosen.
Derive your own frame class to handle this message.

\membersection{wxFrame::OnMenuSelect}

\func{void}{OnMenuSelect}{\param{int}{ id}}

Sent to the window when an item on the window's menu has been selected
(i.e. the cursor is on the item, but the left button has not been
released). Derive your own frame class to handle this message.
See the {\it hello}\/ sample for an example of using this to implement a
line of explanation about each menu item.

This function is only called under Windows 3.

\membersection{wxFrame::SetIcon}

\func{void}{SetIcon}{\param{wxIcon *}{ icon}}

Sets the icon for this frame, deleting any existing one.  Note an
important difference between XView and Windows 3 behaviour. In Windows
3, the title of the frame is the icon label, wrapping if necessary for a
long title. If the frame title changes, the icon label changes. In
XView, the icon label cannot be changed once the icon has been
associated with the frame.  Also, there is no wrapping, and icon labels
must therefore be short.

The best thing to do to accommodate both situations is to have the frame
title set to a short string when setting the icon. Then, set the frame
title to the desired text. In XView, the icon will keep its short text.
In Windows 3, the longer (probably more meaningful) title will be
shown.

Note also that in Windows 3, icons cannot be associated with a window
after window initialization, except by explicitly drawing the icon onto
the iconized window, which is what wxWindows does. Because of this
workaround, the background of the icon will be white rather than the
usual transparent. It was felt limiting to have to pass an icon name at
frame create time.

However, drawing the icon like this does not work (for some unknown
reason) with MDI parent and child frames, and so for MDI applications
the following lines need to be added to the Windows 3 resource file:

\begin{verbatim}
wxSTD_FRAME         ICON icon1.ico
wxSTD_MDICHILDFRAME ICON icon2.ico
\end{verbatim}

where icon1.ico will be used for SDI frames or the MDI parent frame, and
icon2.ico will be used for MDI child frames.

\membersection{wxFrame::SetMenuBar}

\func{void}{SetMenuBar}{\param{wxMenuBar *}{frame}}

Tells the frame to show the given menu bar.  If the frame is destroyed, the
menu bar and its menus will be destroyed also, so do not delete the menu
bar explicitly (except by resetting the frame's menu bar to another
frame or NULL).

\membersection{wxFrame::SetStatusText}

\func{void}{SetStatusText}{\param{char *}{ text}}

Sets the status line text and redraws the status line. Use an empty (not NULL) string
to clear the status line.

\membersection{wxFrame::StatusLineExists}

\func{Bool}{StatusLineExists}{\void}

Returns TRUE if the status line has previously been created.

\section{\class{wxFunction}}

\pfunc{typedef void}{wxFunction}{\param{wxObject\&}{}, \param{wxEvent\&}{}}

The type of a callback function. \helpignore{See the comments in section \ref{function-prob}.}

\section{\class{wxIcon}: wxObject}

An icon is a small rectangular bitmap usually used for denoting a
minimized application. It is optional (but desirable) to associate a
pertinent icon with a frame. Obviously icons in X and Windows 3 are
created in a different manner, and colour icons in X are difficult
to arrange. Therefore, separate icons will be created for the different
environments.  Platform-specific methods for creating a {\bf wxIcon}
structure are catered for, and this is an occasion where conditional
compilation will probably be required.

Note that a new icon must be created for every time the icon is to be
used for a new window. In X, this will ensure that fresh X resources
are allocated for this frame. In Windows 3, the icon will not be
reloaded if it has already been used. An icon allocated to a frame will
be deleted when the frame is deleted.

The following shows the conditional compilation required to define an
icon in X and in Windows 3. The alternative is to use the string
version of the icon constructor, which loads a file under X and a
resource under Windows 3, but has the disadvantage of requiring the
X icon file to be available at run-time. If anyone can invent a
scheme or macro which does the following more elegantly and
platform-independently, I'd like to see it!

\begin{verbatim}
#ifdef wx_x
short aiai_bits[] ={
#include "aiai.icon"
};
#endif
#ifdef wx_msw
  wxIcon *icon = new wxIcon("aiai");
#endif
#ifdef wx_x
  wxIcon *icon = new wxIcon(aiai_bits, 64, 64);
#endif
\end{verbatim}

\membersection{wxIcon::wxIcon}

\func{void}{wxIcon}{\param{short}{ bits[]}, \param{int}{ width}, \param{int}{ height}}

\func{void}{wxIcon}{\param{char *}{ icon\_name}}

Constructor. An icon can be created by passing an array of bits (X only)
or by passing a string name. {\it icon\_name} refers to a filename in X,
a resource name in Windows 3.  

\membersection{wxIcon::\destruct{wxIcon}}

\func{void}{\destruct{wxIcon}}{\void}

Destroys the icon.  Do not explicitly delete an icon pointer which has
been passed to a frame - the frame will delete the icon when it is
destroyed. If assigning a new icon to a frame, the old icon will be
destroyed.

\section{\class{wxHashTable}: wxObject}

This class provides hash table functionality for wxWindows, and for an
application if it wishes.  Data can be hashed on an integer or string
key.  Below is an example of using a hash table.

\begin{verbatim}
  wxHashTable table(KEY_STRING);

  wxPoint *point = new wxPoint(100, 200);
  table.Put("point 1", point);

  ....

  wxPoint *found_point = (wxPoint *)table.Get("point 1");
\end{verbatim}

A hash table is implemented as an array of pointers to lists. When no
data has been stored, the hash table takes only a little more space than
this array (default size is 1000).  When a data item is added, an
integer is constructed from the integer or string key that is within the
bounds of the array. If the array element is NULL, a new (keyed) list is
created for the element. Then the data object is appended to the list,
storing the key in case other data objects need to be stored in the list
also (when a `collision' occurs).

Retrieval involves recalculating the array index from the key, and searching
along the keyed list for the data object whose stored key matches the passed
key. Obviously this is quicker when there are fewer collisions, so hashing
will become inefficient if the number of items to be stored greatly exceeds
the size of the hash table.

\membersection{wxHashTable::wxHashTable}

\func{void}{wxHashTable}{\param{unsigned int}{ key\_type}, \param{int}{ size = 1000}}

Constructor. {\it key\_type} is one of wxKEY\_INTEGER, or wxKEY\_STRING,
and indicates what sort of keying is required. {\it size} is optional.

\membersection{wxHashTable::\destruct{wxHashTable}}

\func{void}{\destruct{wxHashTable}}{\void}

Destroys the hash table.

\membersection{wxHashTable::BeginFind}

\func{void}{BeginFind}{\void}

The counterpart of {\it Next}.  If the application wishes to iterate
through all the data in the hash table, it can call {\it BeginFind} and
then loop on {\it Next}.

\membersection{wxHashTable::Clear}

\func{void}{Clear}{\void}

Clears the hash table of all nodes (but as usual, doesn't delete user data).

\membersection{wxHashTable::Delete}

\func{wxObject *}{Delete}{\param{long}{ key}}

\func{wxObject *}{Delete}{\param{char *}{ key}}

Deletes entry in hash table and returns the user's data (if found).

\membersection{wxHashTable::Get}

\func{wxObject *}{Get}{\param{long}{ key}}

\func{wxObject *}{Get}{\param{char *}{ key}}

Gets data from the hash table, using an integer or string key (depending on which
has table constructor was used).

\membersection{wxHashTable::MakeKey}

\func{long}{MakeKey}{\param{char *}{string}}

Makes an integer key out of a string. An application may wish to make a key
explicitly (for instance when combining two data values to form a key).

\membersection{wxHashTable::Next}

\func{wxNode *}{Next}{\void}

If the application wishes to iterate through all the data in the hash
table, it can call {\it BeginFind} and then loop on {\it Next}. This function
returns a {\bf wxNode} pointer (or NULL if there are no more nodes).  See the
\helpref{wxNode} description. The user will probably only wish to use the
{\bf wxNode::Data} function to retrieve the data; the node may also be deleted.

\membersection{wxHashTable::Put}

\func{void}{Put}{\param{long}{ key}, \param{wxObject *}{object}}

\func{void}{Put}{\param{char *}{ key}, \param{wxObject *}{object}}

Inserts data into the hash table, using an integer or string key (depending on which
has table constructor was used).  Note that only the pointer to the string key
is stored, so it should not be deallocated by the calling program.

\section{\class{wxHelpInstance}: wxClient}

The {\bf wxHelpInstance} class implements the interface by which
applications may invoke wxHelp to provide on-line help. Each instance
of the class maintains one connection to an instance of wxHelp which
belongs to the application, and which is shut down when the Quit
member of {\bf wxHelpInstance} is called (for example in the {\bf
OnClose} member of an application's main frame). Under Windows 3,
there is currently only one instance of wxHelp which is used by all
applications.

Since there is a DDE link between the two programs, each subsequent
request to display a file or section uses the existing instance of
wxHelp, rather than starting a new instance each time. wxHelp thus
appears to the user to be an extension of the current application.
wxHelp may also be invoked independently of a client application.

Normally an application will create an instance of {\bf
wxHelpInstance} when it starts, and immediately call {\bf Initialize}
to associate a filename with it. wxHelp will only get run, however,
just before the first call to display something. See the test program
supplied with the wxHelp source.

Include the file {\tt wx\_help.h} to use this API, even if you have
included {\tt wx.h}.

\membersection{wxHelpInstance::wxHelpInstance}

\func{void}{wxHelpInstance}{\void}

Constructs a help instance object, but does not invoke wxHelp.

\membersection{wxHelpInstance::\destruct{wxHelpInstance}}

Destroys the help instance, closing down wxHelp for this application
if it is running.

\membersection{wxHelpInstance::Initialize}

\func{void}{Initialize}{\param{char *}{file}, \param{int}{ server = -1}}

Initializes the help instance with a help filename, and optionally a server (socket)
number (one is chosen at random if this parameter is omitted). Does not invoke wxHelp.
This must be called directly after the help instance object is created and before
any attempts to communicate with wxHelp.

\membersection{wxHelpInstance::DisplayBlock}

\func{Bool}{DisplayBlock}{\param{long}{ blockNo}}

If wxHelp is not running, runs wxHelp and displays the file at the given block number.

\membersection{wxHelpInstance::DisplayContents}

\func{Bool}{DisplayContents}{\void}

If wxHelp is not running, runs wxHelp and displays the contents (the first section
of the file).

\membersection{wxHelpInstance::DisplaySection}

\func{Bool}{DisplaySection}{\param{int}{ sectionNo}}

If wxHelp is not running, runs wxHelp and displays the given section.
Sections are numbered starting from 1, and section numbers may be viewed by running
wxHelp in edit mode.

\membersection{wxHelpInstance::KeywordSearch}

\func{Bool}{KeywordSearch}{\param{char *}{keyWord}}

If wxHelp is not running, runs wxHelp, and searches for sections matching the
given keyword. If one match is found, the file is displayed at this section. If more
than one match is found, the Search dialog is displayed with the matches.

\membersection{wxHelpInstance::LoadFile}

\func{Bool}{LoadFile}{\param{char *}{file = NULL}}

If wxHelp is not running, runs wxHelp, and loads the given file. If the filename is
not supplied or is NULL, the file specified in {\bf Initialize} is used. If wxHelp
is already displaying the specified file, it will not be reloaded. This member function
may be used before each display call in case the user has opened another file.

\membersection{wxHelpInstance::OnQuit}

\func{Bool}{OnQuit}{\void}

Overridable member called when this application's wxHelp is quit.

\membersection{wxHelpInstance::Quit}

\func{Bool}{Quit}{\void}

If wxHelp is running, quits wxHelp by disconnecting.

\section{\class{wxItem}: wxWindow}

\membersection{wxItem::Centre}

\func{void}{Centre}{\param{int}{ direction = wxHORIZONTAL}}

Centres the frame on the panel or dialog box. The parameter may be {\tt
wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.

You may still use {\bf Fit} in conjunction with this call, but call {\bf Fit}
first before centring items.

\membersection{wxItem::SetDefault}

\func{void}{SetDefault}{\void}

This sets the window to be the default item for the panel or dialog
box.  Under XView, the default item is highlighted, and pressing the
return key executes the callback for the item (but with no visual
feedback, and only if a text item does not have the focus).

Under Windows 3, only dialog box buttons respond to this function.  As
normal under Windows 3, pressing return causes the default button to
be depressed when the return key is pressed. See also {\bf wxWindow::SetFocus}
which sets the keyboard focus for windows and text panel items.

\membersection{wxItem::SetLabel}

\func{void}{wxItem}{\param{char *}{label}}

Sets the item's label. A copy of the label is taken.

\membersection{wxItem::GetLabel}

\func{char *}{wxItem}{\void}

Gets a temporary pointer to the item's label.

\section{\class{wxList}: wxObject}

This class provides linked list functionality for wxWindows, and for an application
if it wishes.  Depending on the form of constructor used, a list can be keyed on
integer or string keys to provide a primitive look-up ability. See \helpref{wxHashTable}
for a faster method of storage when random access is required.  It is very
common to iterate on a list as follows:

\begin{verbatim}
  ...
  wxPoint *point1 = new wxPoint(100, 100);
  wxPoint *point2 = new wxPoint(200, 200);

  wxList SomeList;
  SomeList.Append(point1);
  SomeList.Append(point2);

  ...

  wxNode *node = SomeList.First();
  while (node)
 {
    wxPoint *point = (wxPoint *)node->Data();
    ...
    node = node->Next();
  }
\end{verbatim}

To delete nodes in a list as the list is being traversed, replace

\begin{verbatim}
    ...
    node = node->Next();
    ...
\end{verbatim}

with

\begin{verbatim}
    ...
    delete point;
    delete node;
    node = SomeList.First();
    ...
\end{verbatim}

See \helpref{wxNode} for members that retrieve the data associated with a node, and
members for getting to the next or previous node.

Note that a cast is required when retrieving the data from a node.  Although a
node is defined to store objects of type {\bf wxObject} and derived types, other
types (such as char *) may be used with appropriate casting.

\membersection{wxList::wxList}

\func{void}{wxList}{\void}

\func{void}{wxList}{\param{unsigned int}{ key\_type}}

\func{void}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}}

\func{void}{wxList}{\param{wxObject *}{object}, ...}

Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
and indicates what sort of keying is required (if any).

{\it objects} is an array of {\it n} objects with which to initialize the list.

The variable-length argument list constructor must be supplied with a
terminating NULL.

\membersection{wxList::\destruct{wxList}}

\func{void}{\destruct{wxList}}{\void}

Destroys list.  Also destroys any remaining nodes, but does not destroy
client data held in the nodes.

\membersection{wxList::Append}

\func{wxNode *}{Append}{\param{wxObject *}{object}}

\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}}

\func{wxNode *}{Append}{\param{char *}{key}, \param{wxObject *}{object}}

Appends a new {\bf wxNode} to the end of the list and puts a pointer to the
{\it object} in the node.  The last two forms store a key with the object for
later retrieval using the key. The new node is returned in each case.

\membersection{wxList::Clear}

\func{void}{Clear}{\void}

Clears the list (but does not delete the client data stored with each node).

\membersection{wxList::DeleteContents}

\func{void}{DeleteContents}{\param{Bool}{ destroy}}

If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of
a node whenever the node is destroyed. The default is FALSE.

\membersection{wxList::DeleteNode}

\func{Bool}{DeleteNode}{\param{wxNode *}{node}}

Deletes the given node from the list, returning TRUE if successful.

\membersection{wxList::DeleteObject}

\func{Bool}{DeleteObject}{\param{wxObject *}{object}}

Finds the given client {\it object} and deletes the appropriate node from the list, returning
TRUE if successful. The application must delete the actual object separately.

\membersection{wxList::Find}

\func{wxNode *}{Find}{\param{long}{ key}}

\func{wxNode *}{Find}{\param{char *}{key}}

Returns the node whose stored key matches {\it key}. Use on a keyed list only.

\membersection{wxList::First}

\func{wxNode *}{First}{\void}

Returns the first node in the list (NULL if the list is empty).

\membersection{wxList::Insert}

\func{wxNode *}{Insert}{\param{wxObject *}{object}}

Insert object at front of list.

\func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}

Insert object before {\it position}.


\membersection{wxList::Last}

\func{wxNode *}{Last}{\void}

Returns the last node in the list (NULL if the list is empty).

\membersection{wxList::Member}

\func{Bool}{Member}{\param{wxObject *}{object}}

Returns TRUE if the client data {\it object} is in the list.

\membersection{wxList::Nth}

\func{wxNode *}{Nth}{\param{int}{ n}}

Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
or the nth node could not be found).

\membersection{wxList::Number}

\func{int}{Number}{\void}

Returns the number of elements in the list.

\section{\class{wxListBox}: wxItem}

A list box is used to select one or more of a list of strings. The
strings are displayed in a scrolling box, with the selected string(s)
marked in reverse video. A list item can be single selection (if an item
is selected, the previous selection is removed) or multiple selection
(clicking an item toggles the item on or off independently of other
selections).

\membersection{wxListBox::wxListBox}

\func{void}{wxListBox}{\param{wxPanel *}{parent}, \param{wxFunction}{ func},
\param{char *}{label},\\
  \param{Bool}{ multiple\_selection = FALSE}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1}, \param{int}{ n}, \param{char *}{choices[]}}

Constructor, creating and showing a list box. If {\it width} or {\it
height} are omitted (or are less than zero), an appropriate size will be
used for the list box. {\it func} may be NULL; otherwise it is used as
the callback for the list box.  Note that the cast (wxFunction) must be
used when passing your callback function name, or the compiler may
complain that the function does not match the constructor declaration.

{\it n} is the number of possible choices, and {\it choices} is an array of strings
of size {\it n}. wxWindows allocates its own memory for these strings so the
calling program must deallocate the array itself.

{\it multiple\_selection} is TRUE for a multiple selection list box, FALSE for
a single selection list box.

\membersection{wxListBox::\destruct{wxListBox}}

\func{void}{\destruct{wxListBox}}{\void}

Destructor, destroying the list box.

\membersection{wxListBox::Append}

\func{void}{Append}{\param{char *}{ item}}

Adds the item to the end of the list box. {\it item} must be deallocated by the calling
program, i.e. wxWindows makes its own copy.

\func{void}{Append}{\param{char *}{ item}, \param{char *}{client\_data}}

Adds the item to the end of the list box, associating the given data
with the item. {\it item} must be deallocated by the calling program.

\membersection{wxListBox::Clear}

\func{void}{Clear}{\void}

Clears all strings from the list box.

\membersection{wxListBox::GetClientData}

\func{char *}{GetClientData}{\param{int}{ n}}

Returns a pointer to the client data associated with the given item (if any).

\membersection{wxListBox::Deselect}

\func{void}{Deselect}{\param{int}{ n}}

Deselects the given item in the list box.

\membersection{wxListBox::FindString}

\func{int}{FindString}{\param{int}{ char *s}}

Finds a choice matching the given string, returning the position if found, or
-1 if not found.

\membersection{wxListBox::GetSelection}

\func{int}{GetSelection}{\void}

Gets the id (position) of the selected string - for single selection list boxes only.

\membersection{wxListBox::GetSelections}

\func{int}{GetSelections}{\param{int **}{selections}}

Gets an array containing the positions of the selected strings. The number of selections
is returned.  Pass a pointer to an integer array, and do not deallocate the returned array.

\membersection{wxListBox::GetStringSelection}

\func{char *}{GetStringSelection}{\void}

Gets the selected string - for single selection list boxes only. This
must be copied by the calling program if long term use is to be made of
it.

\membersection{wxListBox::Set}

\func{void}{Set}{\param{int}{ n}, \param{char *}{choices[]}}

Clears the list box and adds the given strings. Deallocate the array from the calling program
after this function has been called.

\membersection{wxListBox::SetSelection}

\func{void}{SetSelection}{\param{int}{ n}}

Sets the choice by passing the desired string position.

\membersection{wxListBox::SetStringSelection}

\func{void}{SetStringSelection}{\param{char *}{ s}}

Sets the choice by passing the desired string.

\membersection{wxListBox::String}

\func{char *}{String}{\param{int}{ n}}

Returns a temporary pointer to the string at position {\it n}.

\section{\class{wxMenu}: wxItem}

A menu is a popup (or pull down) list of items, one of which may be selected before the
menu goes away (clicking elsewhere dismisses the menu).  At present, menus may only
be used to construct menu bars, but will eventually have wider use.

A menu item has an integer ID associated with it which can be used to
identify the selection, or to change the menu item in some way.

\membersection{wxMenu::wxMenu}

\func{void}{wxMenu}{\param{char *}{title = NULL}, \param{wxFunction}{ func = NULL}}

Both arguments are presently ignored.

\membersection{wxMenu::\destruct{wxMenu}}

\func{void}{\destruct{wxMenu}}{\void}

Destructor, destroying the menu.

\membersection{wxMenu::Append}

\func{void}{Append}{\param{int}{ id}, \param{char *}{ item}}

\func{void}{Append}{\param{int}{ id}, \param{char *}{ item}, \param{wxMenu *}{submenu}}

Adds the item to the end of the menu. {\it item} must be deallocated by the calling
program.  If the second form is used, the given menu will be a pullright submenu (must be
created already).  Do not use {\it submenu} after this call: it will be deallocated by
wxWindows.

\membersection{wxMenu::AppendSeparator}

\func{void}{AppendSeparator}{\void}

Adds a separator to the end of the menu. Under XView, this appears as
a space.

\membersection{wxMenu::Enable}

\func{void}{Enable}{\param{int}{ id}, \param{Bool}{ flag}}

If {\it flag} is TRUE, enables the given menu item, else disables it
(greys it).

\membersection{wxMenu::Check}

\func{void}{Check}{\param{int}{ id}, \param{Bool}{ flag}}

If {\it flag} is TRUE, checks the given menu item, else unchecks it.
Works in Windows 3 but has no effect in XView or Motif.

\section{\class{wxMenuBar}: wxItem}

A menu bar is a series of menus accessible from the top of a frame.
Selecting a title pulls down a menu; selecting a menu item causes a {\it
MenuSelection} message to be passed to the frame with the menu item
integer id as the only argument.

\membersection{wxMenuBar::wxMenuBar}

\func{void}{wxMenuBar}{\void}

\func{void}{wxMenuBar}{\param{int}{ n}, \param{wxMenu *}{menus[]}, \param{char *}{titles[]}}

Construct a menu bar. In the second form, the calling program must have
created an array of menus and an array of titles. Do not use the
submenus again after this call.

\membersection{wxMenuBar::\destruct{wxMenuBar}}

\func{void}{\destruct{wxMenuBar}}{\void}

Destructor, destroying the menu bar and removing it from the parent frame (if any).

\membersection{wxMenuBar::Append}

\func{void}{Append}{\param{wxMenu *}{menu}, \param{char *}{title}}

Adds the item to the end of the menu bar. Do not use {\it menu} after
this call: it will be deallocated by wxWindows.

\membersection{wxMenuBar::Enable}

\func{void}{Enable}{\param{int}{ id}, \param{Bool}{ flag}}

If {\it flag} is TRUE, enables the given menu item, else disables it
(greys it). Only use this when the menu bar has been associated with a
frame; otherwise, use the wxMenu equivalent call.

\membersection{wxMenuBar::Check}

\func{void}{Check}{\param{int}{ id}, \param{Bool}{ flag}}

If {\it flag} is TRUE, checks the given menu item, else unchecks it.
Works in Windows but has no effect in XView or Motif. Only use this when the menu
bar has been associated with a frame; otherwise, use the wxMenu
equivalent call.

\section{\class{wxMessage}: wxItem}

A message is a simple line of text which may be displayed in a panel. It does not
respond to mouse clicks.

\membersection{wxMessage::wxMessage}

\func{void}{wxMessage}{\param{wxPanel *}{panel}, \param{char *}{message}, \param{int }{x = -1}, \param{int }{y = -1}}

Creates and displays the message at the given coordinate.

\membersection{wxMessage::\destruct{wxMessage}}

\func{void}{\destruct{wxMessage}}{\void}

Destroys the message.

\section{\class{wxMetaFile}: wxObject}

A wxMetaFile represents the Windows 3 metafile object, so metafile
operations have no effect in X. In wxWindows, only sufficient functionality
has been provided for copying a graphic to the clipboard; this may be extended
in a future version. Presently, the only way of creating a metafile
is to use a wxMetafileDC.

\membersection{wxMetaFile::wxMetaFile}

\func{void}{wxMetaFile}{\void}

Constructor.

\membersection{wxMetaFile::\destruct{wxMetaFile}}

\func{void}{\destruct{wxMetaFile}}{\void}

Destructor.

\membersection{wxMetaFile::SetClipboard}

\func{Bool}{SetClipboard}{\param{int}{ width = 0},
\param{int}{ height = 0}}

Passes the metafile data to the clipboard. The metafile can no longer be
used for anything, but the wxMetaFile object must still be destroyed by
the application.

\section{\class{wxMetaFileDC}: wxDC}

This is a type of device context that allows a metafile object to be
created (Windows only), and has most of the characteristics of a normal
wxDC. The {\bf Close} member must be called after drawing into the
device context, to return a metafile. The only purpose for this at
present is to allow the metafile to be copied to the clipboard (see \helpref{wxMetaFile}).

Adding metafile capability to an application should be easy if you
already write to a wxDC; simply pass the wxMetaFileDC to your drawing
function instead. You may wish to conditionally compile this code so it
is not compiled under X (although no harm will result if you leave it
in).

\membersection{wxMetaFileDC::wxMetaFileDC}

\func{void}{wxMetaFileDC}{\param{char *}{filename = NULL}}

Constructor. If no filename is passed, the metafile is created
in memory.

\membersection{wxMetaFileDC::\destruct{wxMetaFileDC}}

\func{void}{\destruct{wxMetaFileDC}}{\void}

Destructor.

\membersection{wxMetaFileDC::Close}

\func{wxMetaFile *}{Close}{\void}

This must be called after the device context is finished with. A
metafile is returned, and ownership of it passes to the calling
application (so it should be destroyed explicitly).

\section{\class{wxMultiText}: wxText}

Members as for {\bf wxText}, but allowing multiple lines of text.

\membersection{wxText::GetValue}

\func{char *}{GetValue}{\void}
\func{void}{GetValue}{\param{char *}{buffer}, \param{int}{bufferSize}}

The first form gets a pointer to the current value -- this is allocated using {\it new}, so
should be deleted by the calling program. The second form copies the value into
a buffer, for situations where a lot of text is returned (more than the capacity
of the small buffer used for the first form).

\section{\class{wxNode}: wxObject}

A node structure used in linked lists (see \helpref{wxList}).

\membersection{wxNode::Data}

\func{wxObject *}{Data}{\void}

Retrieves the client data pointer associated with the node. This will
have to be cast to the correct type.

\membersection{wxNode::Next}

\func{wxNode *}{Next}{\void}

Retrieves the next node (NULL if at end of list).

\membersection{wxNode::Previous}

\func{wxNode *}{Previous}{\void}

Retrieves the previous node (NULL if at start of list).

\membersection{wxNode::SetData}

\func{void}{SetData}{\void}

Sets the data associated with the node (usually the pointer will have been
set when the node was created).

\section{\class{wxObject}}

This is the root class of all wxWindows classes, and has no base
functionality.  It declares a virtual destructor which ensures that
destructors get called for all derived class objects where necessary.

\section{\class{wxPanel}: wxWindow}

A panel is a subwindow of a frame in which {\it panel items} can be placed to allow
the user to view and set controls. Panel items include messages, text items, list items,
and check boxes. Use {\bf Fit} to fit the panel around its items.

\membersection{wxPanel::wxPanel}

\func{void}{wxPanel}{\param{wxFrame *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{int}{ style = 0}}

Constructor. Set style to wxBORDER to draw a thin border in Windows 3.

\membersection{wxPanel::\destruct{wxPanel}}

\func{void}{\destruct{wxPanel}}{\void}

Destructor.  Deletes any panel items before deleting the physical window.

\membersection{wxPanel::GetCursor}

\func{void}{GetCursor}{\param{int *}{x}, \param{int *}{y}}

Gets the current panel `cursor' position, i.e. where the next panel item
will be placed.

\membersection{wxPanel::GetHorizontalSpacing}

\func{int}{GetHorizontalSpacing}{\void}

Gets the horizontal spacing for placing items on a panel.

\membersection{wxPanel::GetVerticalSpacing}

\func{int}{GetVerticalSpacing}{\void}

Gets the vertical spacing for placing items on a panel.

\membersection{wxPanel::NewLine}

\func{void}{NewLine}{\void}

Cause the next item to be positioned at the beginning of the next line,
using the current vertical spacing. More than one new line in succession
causes extra vertical spacing to be inserted.

\membersection{wxPanel::SetHorizontalSpacing}

\func{void}{SetHorizontalSpacing}{\param{int}{ sp}}

Sets the horizontal spacing for placing items on a panel.

\membersection{wxPanel::SetLabelPosition}

\func{void}{SetLabelPosition}{\param{int}{ position}}

Determines the current method of placing labels on panel items: if {\it
position} is {\tt wxHORIZONTAL}, labels are placed to the left of the
item value. If {\it position} is {\tt wxVERTICAL}, the label is placed
above the item value. The default behaviour is to have horizontal label
placing.

Under Windows 3, this function words for {\bf wxText}, {\bf wxChoice}
and {\bf wxListBox}. Under XView, absolute positioning must be used
for the wxVERTICAL position to work in some cases. This is because of
some strange behaviour in XView where setting a horizontal layout
orientation but a vertical label position causes items after list box
to appear too low on the panel. So, where it is necessary to have
vertical labels, use absolute positioning where results are not as
expected.

\membersection{wxPanel::SetVerticalSpacing}

\func{void}{SetVerticalSpacing}{\param{int}{ sp}}

Sets the vertical spacing for placing items on a panel.

\membersection{wxPanel::Tab}

\func{void}{Tab}{\param{int}{ pixels}}

Tabs by the given number of pixels.

\section{wxPathList: wxList}

The path list is a convenient way of storing a number of directories, and
when presented with a filename without a directory, searching for an existing file
in those directories.  Storing the filename only in an application's files and
using a locally-defined list of directories makes the application and its files more
portable.

Use the {\it FileNameFromPath} global function to extract the filename
from the path.

\membersection{wxPathList::wxPathList}

\func{void}{wxPathList}{\void}

Constructor.

\membersection{wxPathList::AddEnvList}

\func{void}{AddEnvList}{\param{char *}{env\_variable}}

Finds the value of the given environment variable, and adds all paths
to the path list. Useful for finding files in the PATH variable, for
example.

\membersection{wxPathList::AddPath}

\func{void}{AddPath}{\param{char *}{path}}

Adds the given directory to the path list.

\membersection{wxPathList::FindValidPath}

\func{char *}{FindValidPath}{\param{char *}{file}}

Searches for a full path for an existing file by appending {\it file} to
successive members of the path list.  If the file exists, a temporary
pointer to the full path is returned.

\membersection{wxPathList::Member}

\func{Bool}{Member}{\param{char *}{file}}

TRUE if the path is in the path list (ignoring case).

\section{\class{wxPen}: wxObject}

A pen is a drawing tool for drawing outlines. It is used for drawing
lines and painting the outline of rectangles, ellipses, etc.  It has a
colour, a width and a style. On a monochrome display, the default
behaviour is to show all non-white pens as black. To change this,
set the {\bf Colour} member of the device context to TRUE, and select
appropriate colours.

The style may be one of wxSOLID, wxDOT, wxLONG\_DASH, wxSHORT\_DASH and
wxDOT\_DASH. The names of these styles should be self explanatory.

Do not initialize objects on the stack before the program commences,
since other required structures may not have been set up yet. Instead,
define global pointers to objects and create them in {\it OnInit} or
when required.

An application may wish to dynamically create pens with different
characteristics, and there is the consequent danger that a large number
of duplicate pens will be created. Therefore an application may wish to
get a pointer to a pen by using the global list of pens {\bf
wxThePenList}, and calling the member function {\bf FindOrCreatePen}.
See the entry for the \helpref{wxPenList} class.

\membersection{wxPen::wxPen}

\func{void}{wxPen}{\void}

\func{void}{wxPen}{\param{wxColour \&}{colour}, \param{int}{ style}}

\func{void}{wxPen}{\param{char *}{colour\_name}, \param{int}{ style}}

Constructs a pen, uninitialized, initialized with a width, initialized
with an RGB colour, a width and a style, or initialized using a colour
name, a width and a style.  If the named colour form is used, an appropriate {\bf
wxColour} structure is found in the colour database.

\membersection{wxPen::\destruct{wxPen}}

\func{void}{\destruct{wxPen}}{\void}

Destructor, destroying the pen. Note that pens should very rarely be deleted
since windows may contain pointers to them. All pens will be deleted when the
application terminates.

\membersection{wxPen::GetColour}

\func{wxColour\&}{GetColour}{\void}

Returns a reference to the pen colour.

\membersection{wxPen::GetStyle}

\func{int}{GetStyle}{\void}

Returns the pen style.

\membersection{wxPen::GetWidth}

\func{int}{GetWidth}{\void}

Returns the pen width.

\membersection{wxPen::SetColour}

\func{void}{SetColour}{\param{wxColour \&}{colour}}

\func{void}{SetColour}{\param{char *}{colour\_name}}

\func{void}{SetColour}{\param{int}{ red}, \param{int}{ green}, \param{int}{ blue}}

The pen's colour is changed to the given colour.

\membersection{wxPen::SetStyle}

\func{void}{SetStyle}{\param{int}{ style}}

Set the pen style (wxSOLID or wxTRANSPARENT).

\membersection{wxPen::SetWidth}

\func{void}{SetWidth}{\param{int}{ width}}

Set the pen width.
\section{\class{wxPenList}: wxList}

A pen list is a list containing all pens which have been created. There
is only one instance of this class: {\bf wxThePenList}.  Use this object to search
for a previously created pen of the desired type and create it if not already found.
In some windowing systems, the pen may be a scarce resource, so it is best to
reuse old resources if possible.  When an application finishes, all pens will be
deleted and their resources freed, eliminating the possibility of `memory leaks'.

\membersection{wxPenList::wxPenList}

\func{void}{wxPenList}{\void}

Constructor.  The application should not construct its own pen list:
use the object pointer {\bf wxThePenList}.

\membersection{wxPenList::AddPen}

\func{void}{AddPen}{\param{wxPen *}{pen}}

Used by wxWindows to add a pen to the list, called in the pen constructor.

\membersection{wxPenList::FindOrCreatePen}

\func{wxPen *}{FindOrCreatePen}{\param{wxColour *}{colour}, \param{int}{ width}, \param{int}{ style}}

\func{wxPen *}{FindOrCreatePen}{\param{char *}{colour\_name}, \param{int}{ width}, \param{int}{ style}}

Finds a pen of the given specification, or creates one and adds it to the list.

\membersection{wxPenList::RemovePen}

\func{void}{RemovePen}{\param{wxPen *}{pen}}

Used by wxWindows to remove a pen from the list.

\section{\class{wxPoint}: wxObject}

A {\bf wxPoint} is a useful data structure for graphics operations.
It simply contains floating point {\it x} and {\it y} members.

\membersection{wxPoint::wxPoint}

\func{void}{wxPoint}{\void}

\func{void}{wxPoint}{\param{float}{ x}, \param{float}{ y}}

Create a point.

\member{float}{ x}

\member{float}{ y}

Members of the {\bf wxPoint} object.


\section{\class{wxServer}: wxIPCObject}

A wxServer object represents the server part of a client-server DDE
(Dynamic Data Exchange) conversation (available in {\it both}\/ Windows
and UNIX). \helpignore{See section \ref{ipc}.}

\membersection{wxServer::wxServer}

\func{void}{wxServer}{\void}

Constructs a server object.

\membersection{wxServer::Create}

\func{Bool}{Create}{\param{char *}{service}}

Registers the server using the given service name. Under UNIX, the
string must contain an integer id which is used as an Internet port
number. FALSE is returned if the call failed (for example, the port
number is already in use).

\membersection{wxServer::OnAcceptConnection}

\func{wxConnection *}{OnAcceptConnection}{\param{char *}{topic}}

When a client calls {\bf MakeConnection}, the server receives the
message and this member is called. The application should derive a
member to intercept this message and return a connection object of
either the standard wxConnection type, or of a user-derived type. If the
topic is ``STDIO'', the application may wish to refuse the connection.
Under UNIX, when a server is created the OnAcceptConnection message is
always sent for standard input and output, but in the context of DDE
messages it doesn't make a lot of sense.


\section{\class{wxSlider}: wxItem}

\membersection{wxSlider::wxSlider}

A slider is, as its name suggests, an item with a handle which can be pulled
back and forth to change a value.  It is currently horizontal only. In Windows 3,
a scrollbar is used to simulate the slider.

\func{void}{wxSlider}{\param{wxPanel *}{parent}, \param{wxFunction}{ func}, \param{char *}{label},\\
  \param{int}{ value}, \param{int}{ min\_value}, \param{int}{ max\_value}, \param{int}{ width}, \param{int}{ x = -1}, \param{int}{ y = -1}}

Constructor, creating and showing a horizontal slider.  The {\it width} is in pixels,
and the scroll increment will be adjusted to a suitable value given the minimum and
 maximum integer values.

\membersection{wxSlider::\destruct{wxSlider}}

\func{void}{\destruct{wxSlider}}{\void}

Destructor, destroying the slider.

\membersection{wxSlider::GetValue}

\func{int}{GetValue}{\void}

Gets the current slider value.

\membersection{wxSlider::SetValue}

\func{void}{SetValue}{\param{int}{ value}}

Sets the value (and displayed position) of the slider).


\section{\class{wxStringList}: wxList}

A string list is a list which is assumed to contain strings, with a
specific member functions. Memory is allocated when strings are added to
the list, and deallocated by the destructor or by the {\bf Delete}
member.

\membersection{wxStringList::wxStringList}

\func{void}{wxStringList}{\void}

Constructor.

\func{void}{wxStringList}{\param{char *}{first}, ...}

Constructor, taking NULL-terminated string argument list. wxStringList
allocates memory for the strings.

\membersection{wxStringList::\destruct{wxStringList}}

\func{void}{\destruct{wxStringList}}{\void}

Deletes string list, deallocating strings.

\membersection{wxStringList::Add}

\func{void}{Add}{\param{char *}{s}}

Adds string to list, allocating memory.

\membersection{wxStringList::Delete}

\func{void}{Delete}{\param{char *}{s}}

Searches for string and deletes from list, deallocating memory.

\membersection{wxStringList::ListToArray}

\func{char **}{ListToArray}{\param{Bool}{ new\_copies = FALSE}}

Converts the list to an array of strings, only allocating new memory if
{\bf new\_copies} is TRUE.

\membersection{wxStringList::Member}

\func{Bool}{Member}{\param{char *}{s}}

Returns TRUE if {\bf s} is a member of the list (tested using {\bf strcmp}).

\membersection{wxStringList::Sort}

\func{void}{Sort}{\void}

Sorts the strings in ascending alphabetical order. Note that all nodes
(but not strings) get deallocated and new ones allocated.

\section{\class{wxText}: wxWindow}

\membersection{wxText::wxText}

A text item is an area of editable text, with an optional label
displayed in front of it.

\func{void}{wxText}{\param{wxPanel *}{parent}, \param{wxFunction}{ func}, \param{char *}{label},\\
  \param{char *}{value = ""}, \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1}}

Constructor, creating and showing a text item with the given string
value. If {\it width} or {\it height} are omitted (or are less than
zero), an appropriate size will be used for the item.  {\it func}
may be NULL; otherwise it is used as the callback for the list box. 
Note that the cast (wxFunction) must be used when passing your callback
function name, or the compiler may complain that the function does not
match the constructor declaration.

\membersection{wxText::\destruct{wxText}}

\func{void}{\destruct{wxText}}{\void}

Destructor, destroying the text item.

\membersection{wxText::GetValue}

\func{char *}{GetValue}{\void}

Gets a pointer to the current value -- this is allocated using {\it new}, so
should be deleted by the calling program.

\membersection{wxText::SetValue}

\func{void}{SetValue}{\param{char *}{ value}}

Sets the text. {\it value} must be deallocated by the calling program.

\section{\class{wxTextWindow}: wxWindow}

A text window is a subwindow of a frame, offering some basic ability
to display scrolling text. At present, editing is only possible using
the XView and Motif implementations.

\membersection{wxTextWindow::wxTextWindow}

\func{void}{wxTextWindow}{\param{wxFrame *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1}, \param{int}{ style = 0}}

Constructor. Set style to wxBORDER to draw a thin border in Windows 3.

\membersection{wxTextWindow::\destruct{wxTextWindow}}

\func{void}{\destruct{wxTextWindow}}{\void}

Destructor.  Deletes any stored text before deleting the physical window.

\membersection{wxTextWindow::Clear}

\func{void}{Clear}{\void}

Clears the window and deletes the stored text.

\membersection{wxTextWindow::DiscardEdits}

\func{void}{DiscardEdits}{\void}

Clears the window and deletes the stored text (same as {\bf Clear}).

\membersection{wxTextWindow::LoadFile}

\func{Bool}{LoadFile}{\param{char *}{ file}}

Loads and displays the named file, if it exists. Success is indicated by a return
value of TRUE.

\membersection{wxTextWindow::Modified}

\func{Bool}{Modified}{\void}

Returns TRUE if the text has been modified. Under Windows 3, this always returns
FALSE.

\membersection{wxTextWindow::SaveFile}

\func{Bool}{SaveFile}{\param{char *}{ file}}

Saves the text in the named file. Success is indicated by a return
value of TRUE.

\membersection{wxTextWindow::WriteText}

\func{void}{WriteText}{\param{char *}{ text}}

Writes the text into the text window. Presently there is no means of writing
text to other than the end of the existing text.  Newlines in the text string
are the only control characters allowed, and they will cause appropriate
line breaks.  See the \cinsert operators for more convenient ways of writing to the
window.

\membersection{wxTextWindow::\cinsert}

\func{wxTextWindow\&}{\cinsert}{\param{char *}{s}}

\func{wxTextWindow\&}{\cinsert}{\param{int}{ i}}

\func{wxTextWindow\&}{\cinsert}{\param{long}{ i}}

\func{wxTextWindow\&}{\cinsert}{\param{float}{ f}}

\func{wxTextWindow\&}{\cinsert}{\param{double}{ d}}

\func{wxTextWindow\&}{\cinsert}{\param{char}{ c}}

Operator definitions for writing to a text window, for example:

\begin{verbatim}
  wxTextWindow wnd(my_frame);

  wnd << "Welcome to text window number " << 1 << ".\n";
\end{verbatim}

\section{\class{wxTimer}: wxObject}

The wxTimer object is an abstraction of Windows 3, XView and X toolkit timers. To
use it, derive a new class and override the {\bf Notify} member to
perform the required action. Start with {\bf Start}, stop with {\bf
Stop}, it's as simple as that.

\membersection{wxTimer::wxTimer}

\func{void}{wxTimer}{\void}

Constructor.

\membersection{wxTimer::\destruct{wxTimer}}

\func{void}{\destruct{wxTimer}}{\void}

Destructor. Stops the timer if activated.

\membersection{wxTimer::Notify}

\func{void}{Notify}{\void}

This member should be overridden by the user. It is called on timeout.

\membersection{wxTimer::Start}

\func{Bool}{Start}{\param{int}{ milliseconds = -1}}

(Re)starts the timer. If {\it milliseconds}\/ is absent or -1, the
previous value is used. Returns FALSE if the timer could not be started,
TRUE otherwise (in Windows 3 timers are a limited resource).

\membersection{wxTimer::Stop}

\func{void}{Stop}{\void}

Stops the timer.

\section{\class{wxWindow}: wxObject}

wxWindow is the base class for all windows and panel items.  Any
children of the window will be deleted automatically by the destructor
before the window itself is deleted.

\membersection{wxWindow::wxWindow}

\func{void}{wxWindow}{\void}

Constructor.

\membersection{wxWindow::\destruct{wxWindow}}

\func{void}{\destruct{wxWindow}}{\void}

Destructor. Deletes all subwindows, then deletes itself.

\membersection{wxWindow::AddChild}

\func{void}{AddChild}{\param{wxWindow *}{child}}

Adds a child window.  This is called automatically by window creation
functions so should not be required by the application programmer.

\membersection{wxWindow::Center}

\func{void}{Center}{\param{int}{ direction}}

See \helpref{Centre}.

\membersection{wxWindow::Centre}

\func{void}{Centre}{\param{int}{ direction}}

Centres the window. The parameter may be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}
or {\tt wxBOTH}.

The actual behaviour depends on the derived window. For a frame or dialog box,
centring is relative to the whole display. For a panel item, centring is
relative to the panel.

\membersection{wxWindow::DestroyChildren}

\func{void}{DestroyChildren}{\void}

Destroys all children of a window.  Called automatically by the destructor.

\membersection{wxWindow::Fit}

\func{void}{Fit}{\void}

Sizes the window to fit the content (for panels and frames).

\membersection{wxWindow::GetClientData}

\func{char *}{GetClientData}{\void}

Gets user-supplied client data.  Normally, any extra data the programmer wishes
to associate with the window should be made available by deriving a new class
with new data members.

\membersection{wxWindow::GetClientSize}

\func{void}{GetClientSize}{\param{int *}{width}, \param{int *}{height}}

This gets the size of the window `client area' in pixels.  The client area is the
area which may be drawn on by the programmer, excluding title bar, border etc.

\membersection{wxWindow::GetHandle}

\func{char *}{GetHandle}{\void}

Gets the platform-specific handle of the physical window.

\membersection{wxWindow::GetPosition}

\func{void}{GetPosition}{\param{int *}{x}, \param{int *}{y}}

This gets the position of the window in pixels, relative to the parent window or
if no parent, relative to the whole display.

\membersection{wxWindow::GetSize}

\func{void}{GetSize}{\param{int *}{width}, \param{int *}{height}}

This gets the size of the entire window in pixels.

\membersection{wxWindow::GetTextExtent}

\func{void}{GetTextExtent}{\param{char *}{string}, \param{int *}{x}, \param{int *}{y}}

Gets the width and height of the string as it would be drawn on the window with the
currently selected font.

\membersection{wxWindow::OnActivate}

\func{void}{OnActivate}{\param{Bool}{ active}}

Called when a window is activated or deactivated (Windows 3
only). If the window is being activated, {\it active} is TRUE, else it
is FALSE.

\membersection{wxWindow::OnChar}

\func{void}{OnChar}{\param{int}{ ch}}

Sent to the window when the user has pressed a key. {\it ch} gives the
ASCII code (function key identifiers not yet implemented). See
\helpref{OnEvent} for mouse event notification. Currently applicable
to canvas subwindows only.

\membersection{wxWindow::OnClose}

\func{Bool}{OnClose}{\void}

Sent to the window when the user has tried to close the window.  If TRUE is returned,
the window will be deleted by the system, otherwise the attempt will be ignored.
Derive your own class to handle this message; the default handler returns TRUE.
Really only relevant to wxFrames.

\membersection{wxWindow::OnEvent}

\func{void}{OnEvent}{\param{wxEvent\&}{ event}}

Sent to the window when the user has initiated an event with the
mouse. Derive your own class to handle this message. So far,
only relevant to the wxCanvas class. See \helpref{OnChar} for character
events, and also {\bf wxEvent} for how to access event information.

\membersection{wxWindow::OnKillFocus}

\func{void}{OnKillFocus}{\void}

Called when a window's focus is being killed.

\membersection{wxWindow::OnPaint}

\func{void}{OnPaint}{\void}

Sent to the window when the window must be refreshed.
Derive your own class to handle this message. So far, only
relevant to the wxCanvas class.

\membersection{wxWindow::OnSetFocus}

\func{void}{OnSetFocus}{\void}

Called when a window's focus is being set.

\membersection{wxWindow::OnSize}

\func{void}{OnSize}{\param{int}{ x}, \param{int}{ y}}

Sent to the window when the window has been resized. You may wish to use
this for frames to resize their child windows as appropriate. Derive
your own class to handle this message. Note that the size passed is of
the whole window: call {\bf GetClientSize} for the area which may be
used by the application. A window is sent both an OnPaint and an OnSize message
when a resize occurs.

\membersection{wxWindow::SetFocus}

\func{void}{SetFocus}{\void}

This sets the window to receive keyboard input. The only panel item that will
respond to this under XView is the {\bf wxText} item and derived items.

\membersection{wxWindow::SetSize}

\func{void}{SetSize}{\param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height}}

This sets the size of the entire window in pixels.

\membersection{wxWindow::SetClientData}

\func{void}{SetClientData}{\param{char *}{data}}

Sets user-supplied client data.  Normally, any extra data the programmer wishes
to associate with the window should be made available by deriving a new class
with new data members.

\membersection{wxWindow::SetClientSize}

\func{void}{SetClientSize}{\param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height}}

This sets the size of the window client area in pixels. Using this function to size a window
tends to be more device-independent than {\bf SetSize}, since the application need not
worry about what dimensions the border or title bar have when trying to fit the window
around panel items, for example.

\membersection{wxWindow::SetCursor}

\func{wxCursor *}{SetCursor}{\param{wxCursor *}{cursor}}

Sets the window's cursor, returning the previous cursor (if any). This
function applies to all subwindows.

\membersection{wxWindow::SetTitle}

\func{void}{SetTitle}{\param{char *}{title}}

Sets the window's title, allocating its own string storage. Currently
applicable only to frames.

\membersection{wxWindow::Show}

\func{void}{Show}{\param{Bool}{ show}}

If {\it show} is TRUE, displays the window and brings it to the front.  Otherwise,
hides the window.

\helpignore{\chapter{Miscellaneous functions}}

\section{File functions}\label{file-functions}

See also the \helpref{wxPathList} class.

\membersection{::Dos2UnixFilename}

\func{void}{Dos2UnixFilename}{\param{char *}{s}}

Converts a DOS to a UNIX filename by replacing backslashes with forward
slashes.

\membersection{::FileExists}

\func{Bool}{FileExists}{\param{char *}{filename}}

Returns TRUE if the file exists.

\membersection{::FileNameFromPath}

\func{char *}{FileNameFromPath}{\param{char *}{path}}

Returns the filename for a full path (returns a new string).

\membersection{::IsAbsolutePath}

\func{Bool}{IsAbsolutePath}{\param{char *}{filename}}

Returns TRUE if the argument is an absolute filename, i.e. with a slash
or drive name at the beginning.

\membersection{::PathOnly}

\func{char *}{PathOnly}{\param{char *}{path}}

Returns the directory part of the filename (returns a new string).

\membersection{::Unix2DosFilename}

\func{void}{Unix2DosFilename}{\param{char *}{s}}

Converts a UNIX to a DOS filename by replacing forward
slashes with backslashes.

\membersection{::wxConcatFiles}

\func{Bool}{wxConcatFiles}{\param{char *}{file1}, \param{char *}{file2},
\param{char *}{file3}}

Concatenates {\it file1} and {\it file2} to {\it file3}, returning
TRUE if successful.

\membersection{::wxCopyFile}

\func{Bool}{wxCopyFile}{\param{char *}{file1}, \param{char *}{file2}}

Copies {\it file1} to {\it file2}, returning TRUE if successful.

\membersection{::wxIsWild}

\func{Bool}{wxIsWild}{\param{char *}{pattern}}

Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}.

\membersection{::wxMatchWild}

\func{Bool}{wxMatchWild}{\param{char *}{pattern}, \param{char *}{text}, \param{Bool}{ dot\_special}}

Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it
dot\_special}\/ is TRUE, filenames beginning with a dot are not matched
with wildcard characters. See \helpref{wxIsWild}.

\membersection{::wxRemoveFile}

\func{Bool}{wxRemoveFile}{\param{char *}{file}}

Removes {\it file}, returning TRUE if successful.

\membersection{::wxRenameFile}

\func{Bool}{wxRenameFile}{\param{char *}{file1}, \param{char *}{file2}}

Renames {\it file1} to {\it file2}, returning TRUE if successful.

\section{String functions}

\membersection{::copystring}

\func{char *}{copystring}{\param{char *}{s}}

Makes a copy of the string {\it s} using the C++ new operator, so it can be
deleted with the delete operator.

\section{Dialog functions}\label{dialog-functions}

Below are a number of convenience functions for getting input from the
user or displaying messages. Note that in these functions the last three
parameters are optional. However, it is recommended to pass a parent frame
parameter, or (in Windows 3) the wrong window frame may be brought to
the front when the dialog box is popped up.

\membersection{::wxGetTextFromUser}

\func{char *}{wxGetTextFromUser}{\param{char *}{message}, \param{char *}{caption = "Input text"},\\
  \param{char *}{default\_value = ""}, \param{wxFrame *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}

Pop up a dialog box with title set to {\it caption}, message {\it message}, and a
{\it default\_value}.  The user may type in text and press OK to return this text,
or press Cancel to return NULL.

\membersection{::wxGetSingleChoice}

\func{char *}{wxGetSingleChoice}{\param{char *}{message}, \param{char *}{caption}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{wxFrame *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}

Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection
listbox. The user may choose an item and press OK to return a string or
Cancel to return NULL.

{\it choices} is an array of {\it n} strings for the listbox.

\membersection{::wxGetSingleChoiceIndex}

\func{int}{wxGetSingleChoiceIndex}{\param{char *}{message}, \param{char *}{caption}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{wxFrame *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}

As {\bf wxGetSingleChoice} but returns the index representing the selected string.

\membersection{::wxGetSingleChoiceData}

\func{char *}{wxGetSingleChoiceData}{\param{char *}{message}, \param{char *}{caption}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{char *}{client\_data[]}, \param{wxFrame *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}

As {\bf wxGetSingleChoice} but takes an array of client data pointers
corresponding to the strings, and returns one of these pointers.

\membersection{::wxMessageBox}

\func{int}{wxMessageBox}{\param{char *}{message}, \param{char *}{caption = "Message"}, \param{int}{ type = wxOK},\\
  \param{wxFrame *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}

General purpose message dialog.  {\it type} may be one or more of the
following identifiers or'ed together: wxYES\_NO, wxCANCEL, wxOK.

The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.

For example:
\begin{verbatim}
  ...
  int answer = wxMessageBox("Quit program?", "Confirm",
                            wxYES_NO | wxCANCEL, main_frame);
  if (answer == wxYES)
    delete main_frame;
  ...
\end{verbatim}

{\it message} may contain newline characters, in which case the
message will be split into separate lines and centred in the dialog
box, to cater for large messages.

\membersection{::wxFileSelector}

\func{char *}{wxFileSelector}{\param{char *}{message}, \param{char *}{default\_path = NULL},\\
  \param{char *}{default\_filename = NULL}, \param{char *}{default\_extension = NULL},\\
  \param{char *}{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxFrame *}{parent = NULL},\\
  \param{int}{ x = -1}, \param{int}{ y = -1}}

Pops up a file selector box. In Windows, this is the common file selector
dialog. In X, this is a file selector box with somewhat less functionality.
The path and filename are distinct elements of a full file pathname.
If path is NULL, the current directory will be used. If filename is NULL,
no default filename will be supplied. The wildcard determines what files
are displayed in the file selector, and file extension supplies a type
extension for the required filename. Flags may be a combination of wxOPEN,
wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, or 0. They are only significant
at present in Windows.

Both the X and Windows versions implement a wildcard filter. Typing a
filename containing wildcards (*, ?) in the filename text item, and
clicking on Ok, will result in only those files matching the pattern being
displayed. In the X version, supplying no default name will result in the
wildcard filter being inserted in the filename text item; the filter is
ignored if a default name is supplied.

The application must check for a NULL return value (the user pressed
Cancel). For example:

\begin{verbatim}
char *s = wxFileSelector("Choose a file to open");
if (s)
{
  ...
}
\end{verbatim}


\section{GDI functions}\label{gdi-functions}

The following are relevant to the GDI (Graphics Device Interface).

\membersection{::wxColourDisplay}

\func{Bool}{wxColourDisplay}{\void}

Returns TRUE if the display is colour, FALSE otherwise.

\membersection{::SetCursor}

\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}

Globally sets the cursor; only works in Windows 3.


\section{Miscellaneous}

\membersection{::NewId}

\func{long}{NewId}{\void}

Generates an integer identifier unique to this run of the program.

\membersection{::RegisterId}

\func{void}{RegisterId}{\param{long}{ id}}

Ensures that ids subsequently generated by {\bf NewId} do not clash with
the given {\bf id}.

\membersection{::wxDisplaySize}

\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}

Gets the physical size of the display in pixels.

\membersection{::wxGetElapsedTime}

\func{long}{wxGetElapsedTime}{\void}

Gets the time in milliseconds since the last {\bf wxGetElapsedTime} or
{\bf wxStartTimer}.

\membersection{::wxSleep}

\func{void}{wxSleep}{\param{int}{ secs}}

Under X, sleeps for the specified number of seconds using the
technique specified in the XView manual, not UNIX {\bf sleep}.

\membersection{::wxStartTimer}

\func{void}{wxStartTimer}{\void}

Starts a stopwatch; use {\bf wxGetElapsedTime} to get the elapsed time.

\membersection{::wxYield}

\func{void}{wxYield}{\void}

Yields control to other applications (has no effect under XView or Motif).

\membersection{::wxExecute}

\func{void}{wxExecute}{\param{char *}{command}}

Executes a command in UNIX or Windows. Note that under Windows, the
function immediately returns, whereas under UNIX, it does
returns only after the command has finished executing, unless the
command is executed in the background (append an ampersand).

