\chapter{wxWindows Class Reference}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
\helpignore{\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
$$\image{14cm;0cm}{wxclass.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.

From version 1.50 beta (j), string return values are allocated and
deallocated by wxWindows. Therefore, return values should always be
copied for long-term use, especially since the same buffer is often
used by wxWindows.

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

\section{A Rough Guide}

To set a wxWindows application going, you'll need to derive a \helpref{wxApp}{wxapp} class.

An application must have a top-level \helpref{wxFrame}{wxframe} window (returned by \helpref{wxApp::OnInit}{wxapponinit}),
each frame containing one or more instances of \helpref{wxPanel}{wxpanel}, \helpref{wxTextWindow}{wxtextwindow}\rtfsp
or \helpref{wxCanvas}{wxcanvas}.

A frame can have a \helpref{wxMenuBar}{wxmenubar}, a status line, and a \helpref{wxIcon}{wxicon} for
when the frame is iconized.

A \helpref{wxPanel}{wxpanel} is used to place items (classes derived from \helpref{wxItem}{wxitem})
which are used for user interaction. Examples of items are \helpref{wxButton}{wxbutton},
\rtfsp\helpref{wxCheckBox}{wxcheckbox}, \helpref{wxChoice}{wxchoice}, \helpref{wxListBox}{wxlistbox}, \helpref{wxSlider}{wxslider},
\rtfsp\helpref{wxRadioBox}{wxradiobox}, \helpref{wxSlider}{wxslider}.

Instances of \helpref{wxDialogBox}{wxdialogbox} can also be used for panels, items and they have
the advantage of not requiring a separate frame.

Instead of creating a dialog box and populating it with items, it is possible to choose
one of the convenient \helpref{dialog functions}{dialogfunctions}, such as \helpref{wxMessageBox}{wxmessagebox}
and \helpref{wxFileSelector}{wxfileselector}.

If you want to draw arbitrary graphics, you'll need a \helpref{wxCanvas}{wxcanvas}. In fact,
you never draw directly onto a canvas---you use a {\it device context} (DC). \helpref{wxDC}{wxdc} is
the base for \helpref{wxCanvasDC}{wxcanvasdc}, \helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxPostScriptDC}{wxpostscriptdc},
\rtfsp\helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxMetaFileDC}{wxmetafiledc} and \helpref{wxPrinterDC}{wxprinterdc}.
If your drawing functions have {\bf wxDC} as a parameter, you can pass any of these DCs
to the function, and thus use the same code to draw to several different devices.
You can draw using the member functions of {\bf wxDC}, such as \helpref{wxDC::DrawLine}{wxdcdrawline}
and \helpref{wxDC::DrawText}{wxdcdrawtext}. Control colour on a canvas (\helpref{wxColour}{wxcolour}) with
brushes (\helpref{wxBrush}{wxbrush}) and pens (\helpref{wxPen}{wxpen}).

On a canvas, you will probably need to intercept key events by overriding the
\rtfsp\helpref{wxCanvas::OnChar}{wxcanvasonchar} member, and mouse events by overriding \helpref{wxCanvas::OnEvent}{wxcanvasonevent}.

Most modern applications will have an on-line, hypertext help system; for this, you
need wxHelp and the \helpref{wxHelpInstance}{wxhelpinstance} class to control
wxHelp. To add sparkle, you might use the wxToolBar class (documented separately)
which makes heavy use of the \helpref{wxBitmap}{wxbitmap}.

GUI applications aren't all graphical wizardry. List and hash table needs are
catered for by \helpref{wxList}{wxlist}, \helpref{wxStringList}{wxstringlist} and \helpref{wxHashTable}{wxhashtable}.
You will undoubtedly need some platform-independent \helpref{file functions}{filefunctions},
and you may find it handy to maintain and search a list of paths using \helpref{wxPathList}{wxpathlist}.
There's a \helpref{miscellany}{miscellany} of operating system and other functions.

If you have several communicating applications, you can try out the DDE-like functions, by
using the three classes \helpref{wxClient}{wxclient}, \helpref{wxServer}{wxserver} and
\rtfsp\helpref{wxConnection}{wxconnection}. These use DDE under Windows, and a simulation using
sockets under UNIX.

\section{\class{wxApp}: wxObject}\label{wxapp}

The {\bf wxApp} class represents the application itself.  A wxWindows
application does not have a {\it main} procedure; the equivalent is the
\rtfsp\helpref{OnInit}{wxapponinit} member defined for a class derived from {\bf wxApp}.\rtfsp
{\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. The alternative
is to explicitly delete child frames in the top-level frame's \helpref{wxFrame::OnClose}{wxframeonclose}\rtfsp
member.

In emergencies the \helpref{wxExit}{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(NULL, argv[0]);
  ...
  return the_frame;
}

MyApp DerivedApp;
\end{verbatim}

\membersection{wxApp::wxApp}

\func{void}{wxApp}{\param{int}{ language = wxLANGUAGE\_ENGLISH}}

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

The argument is a language identifier; this is an experimental
feature and will be expanded and documented in future versions.

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

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

Destructor. Will be called implicitly on program exit 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::wx\_class}

\member{char *}{wx\_class}

Currently used under Motif only, where the value is passed to {\it
XtOpenDisplay} on initialization. Set this member in the constructor of
your derived {\bf wxApp} class to give the application a name other than
the default {\it ``wxApp''}.

\membersection{wxApp::Dispatch}\label{dispatch}

\func{void}{Dispatch}{\void}

Dispatches the next event in the windowing system event queue.
(Windows 3.1, WIN32, and Motif). See also \helpref{wxApp::Pending}{pending}.

This can be used for programming event loops, e.g.

\begin{verbatim}
  while (app.Pending())
    Dispatch();
\end{verbatim}

\membersection{wxApp::Initialized}

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

Returns TRUE if the application has been initialized (i.e. if\rtfsp
\helpref{OnInit}{wxapponinit} 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}\label{apponexit}

\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}\label{wxapponinit}

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

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

\membersection{wxApp::Pending}\label{pending}

\func{Bool}{Pending}{\void}

Returns TRUE if unprocessed events are in the window system event queue
(Windows 3.1, WIN32, and Motif). See also \helpref{wxApp::Dispatch}{dispatch}.

\section{\class{wxBitmap}: wxObject}\label{wxbitmap}

This class encapsulates the concept of a platform-dependent bitmap,
either monochrome or colour. Platform-specific methods for creating a
\rtfsp{\bf wxBitmap} structure from an existing file are catered for, and
this is an occasion where conditional compilation will probably be
required.

A bitmap created dynamically or loaded from a file can be selected
into a memory device context (instance of \helpref{wxMemoryDC}{wxmemorydc}). This
enables the bitmap to be copied to a canvas or memory device context
using \helpref{wxDC::Blit}{wxdcblit}, or to be used as a drawing surface.  The {\bf
wxToolBar} class was implemented using bitmaps, and the toolbar demo
shows one of the toolbar bitmaps being used for drawing a miniature
version of the graphic which appears on the main canvas.

wxWindows contains code to `grey out' a bitmap when used in an insensitive
panel item. Under X, this code is contained in the wxBitmap class.
Under Windows, the user-contributed Fafa library is responsible for this.

See \helpref{wxMemoryDC}{wxmemorydc} for an example of drawing onto a bitmap.

The following shows the conditional compilation required to load a
bitmap in X and in Windows 3. The alternative is to use the string
version of the bitmap 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.

\begin{verbatim}
#ifdef wx_x
#include "aiai.xbm"
#endif
#ifdef wx_msw
  wxIcon *icon = new wxBitmap("aiai");
#endif
#ifdef wx_x
  wxIcon *icon = new wxBitmap(aiai_bits, aiai_width, aiai_height);
#endif
\end{verbatim}

\subsection{Loading bitmaps: further information}

See also the DIB and wxImage libraries distributed with
wxWindows. DIB allows loading of .BMP files under Windows, and
wxImage allows loading of a variety of bitmap formats under X.
wxBuilder makes use of both of these packages: search for wxLoadBitmap
for example of usage.

\membersection{wxBitmap::wxBitmap}

\func{void}{wxBitmap}{\param{char}{ bits[]}, \param{int}{ width}, \param{int}{ height}\\
  \param{int}{ depth = 1}}

Constructs a (usually monochrome) bitmap from an array of pixel values, under both
X and Windows.

\func{void}{wxBitmap}{\param{int}{ width}, \param{int}{ height} \param{int}{ depth = -1}}

Constructs a new bitmap. If the final argument is omitted, the display depth of
the screen is used.

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

Constructs a bitmap by passing a string name. {\it icon\_name} refers
to an XBM filename in X, a resource name in Windows 3.

\membersection{wxBitmap::\destruct{wxBitmap}}

\func{void}{\destruct{wxBitmap}}{\void}

Destroys the bitmap. The bitmap will be destroyed automatically by wxWindows
when the application exits.

\membersection{wxBitmap::GetDepth}

\func{int}{GetDepth}{\void}

Gets the colour depth of the bitmap. A value of 1 indicates a
monochrome bitmap.

\membersection{wxBitmap::GetHeight}

\func{int}{GetHeight}{\void}

Gets the height of the bitmap in pixels.

\membersection{wxBitmap::GetWidth}

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

Gets the width of the bitmap in pixels.

\membersection{wxBitmap::Ok}

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

Returns TRUE if the bitmap was successfully created.

\section{\class{wxBrush}: wxObject}\label{wxbrush}

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 unless the colour is really black. If you wish the
policy to be `all non-white colours are black', as with pens, uncomment
the piece of code documented in \helpref{wxDC::SetBrush}{wxdcsetbrush} 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 \helpref{wxApp::OnInit}{wxapponinit} 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
\rtfsp{\bf FindOrCreateBrush}. See \helpref{wxBrushList}{brushlist} and \helpref{wxDC}{wxdc}.

\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 \helpref{wxColour}{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.

If you have to delete a brush, then call
\helpref{wxDC::SetBrush}{wxdcsetbrush} with a NULL argument to ensure that
the old brush is restored, and the current brush is selected out of the
device context.

\membersection{wxBrush::GetColour}

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

Returns a reference to the brush colour.

\membersection{wxBrush::GetStipple}

\func{wxBitmap *}{GetStipple}{\void}

Gets the stipple bitmap.

\membersection{wxBrush::GetStyle}

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

Returns the brush style, one of:

\begin{itemize}
\item wxTRANSPARENT
\item wxSOLID
\item wxBDIAGONAL\_HATCH
\item wxCROSSDIAG\_HATCH
\item wxFDIAGONAL\_HATCH
\item wxCROSS\_HATCH
\item wxHORIZONTAL\_HATCH
\item wxVERTICAL\_HATCH
\end{itemize}

\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::SetStipple}

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

Sets the stipple bitmap.

Note that there is a big difference between stippling in X and Windows.
On X, the stipple is a mask between the wxBitmap and current colour.
On Windows, the current colour is ignored, and the bitmap colour is used.
However, for pre-defined modes like wxCROSS\_HATCH, the behaviour is the
same for both platforms.

\membersection{wxBrush::SetStyle}

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

Sets the brush style, one of:

\begin{itemize}
\item wxTRANSPARENT
\item wxSOLID
\item wxBDIAGONAL\_HATCH
\item wxCROSSDIAG\_HATCH
\item wxFDIAGONAL\_HATCH
\item wxCROSS\_HATCH
\item wxHORIZONTAL\_HATCH
\item wxVERTICAL\_HATCH
\end{itemize}

\section{\class{wxBrushList}: wxList}\label{brushlist}

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'. See \helpref{wxBrush}{wxbrush}.

\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}\label{wxbutton}

A button is a {\it panel item} that contains a text string or bitmap,
and is one of the commonest elements of a GUI. It may be placed on a
\rtfsp\helpref{dialog box}{wxdialogbox} or \helpref{panel}{wxpanel}.

\membersection{wxButton::wxButton}\label{constrbutton}

\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},\\
  \param{long}{ style = 0}, \param{char *}{name = ``button"}}

\func{void}{wxButton}{\param{wxPanel *}{parent}, \param{wxFunction}{ func}, \param{wxBitmap *}{wxBitmap},\\
  \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``button"}}

Constructor, creating and showing a button. The parent must be a valid
panel or dialog box pointer.

{\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. See \helpref{wxFunction}{wxfunction}.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

If {\it width} or {\it height} are omitted (or are less than zero), an
appropriate size will be used for the item.  The {\it style} parameter
is reserved for future use. The {\it name} parameter is used to associate
a name with the item, allowing the application user to set Motif resource values
for individual buttons.

If the first form is used, the {\it label} will be shown on the button.
If the seond form is used, the {\it bitmap} will be used.

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

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

Destructor, destroying the button.

\membersection{wxButton::Create}

\func{void}{Create}{\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{long}{ style = 0}, \param{char *}{name = ``button"}}

\func{void}{Create}{\param{wxPanel *}{parent}, \param{wxFunction}{ func}, \param{wxBitmap *}{wxBitmap},\\
  \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``button"}}

Button creation functions called by the button constructors. Call these
when a derived button class uses the zero-argument {\bf wxButton}
constructor, but can reuse the existing button creation code.
See \helpref{wxButton::wxButton}{constrbutton} for details.

\membersection{wxButton::SetDefault}\label{wxbuttonsetdefault}

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

This sets the button 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 and Motif, pressing return causes the default button to
be depressed when the return key is pressed. See also \helpref{wxWindow::SetFocus}{winsetfocus}
which sets the keyboard focus for windows and text panel items, \helpref{wxPanel::OnDefaultAction}{wxpanelondefaultaction}
and \helpref{wxPanel::GetDefaultItem}{wxpanelgetdefaultitem}.

Note that under Motif, calling this function immediately after
creation of a button and before the creation of other buttons
will cause misalignment of the row of buttons, since default
buttons are larger. To get around this, call {\it SetDefault}\rtfsp
after you have created a row of buttons: wxWindows will
then set the size of all buttons currently on the panel to
the same size.

\membersection{wxButton::SetLabel}\label{wxbuttonsetlabel}

\func{void}{SetLabel}{\param{wxBitmap *}{label}}

Sets the bitmap for a bitmap button.

\section{\class{wxCanvas}: wxWindow}\label{wxcanvas}

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} boolean member variable.

When you draw onto a canvas, you are really drawing onto a {\it device
context} (see \helpref{wxDC}{wxdc}, \helpref{wxCanvasDC}{wxcanvasdc}).
Although you can use the members of wxCanvas for drawing,
it is much better to get the device context from the canvas
(see \helpref{GetDC}{wxcanvasgetdc}) and draw into that. Then,
code which can draw into one device context can be reused for others,
such as PostScript or memory device contexts (see \helpref{wxPostScriptDC}{wxpostscriptdc}
and \helpref{wxMemoryDC}{wxmemorydc}).

\membersection{wxCanvas::wxCanvas}\label{constrcanvas}

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

Constructor.

The parameters {\it x}, {\it y}, {\it width} and {\it height}
can be omitted on construction if the position and size will later
be set (for example by a application frame's {\bf OnSize} callback,
or if there is only one subwindow for the frame, in which case the
subwindow fills the frame).

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

\begin{twocollist}
\twocolitem{wxBORDER}{Gives the canvas a thin border (Windows 3 and Motif only).}
\twocolitem{wxRETAINED}{Gives the canvas a wxWindows-implemented backing store, making
repainting much faster but at a potentially costly memory premium (XView and Motif only).}
\twocolitem{wxBACKINGSTORE}{Gives the canvas an X-implemented backing store
(XView and Motif only). The X server may choose to ignore this request, whereas
wxRETAINED is always implemented under X.}
\end{twocollist}

The {\it name} parameter is used to associate a name with the canvas,
allowing the application user to set Motif resources for individual
canvases.

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

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

Destructor.

\membersection{wxCanvas::AllowDoubleClick}\label{allowdoubleclick}

\func{void}{AllowDoubleClick}{\param{Bool}{ allow}}

Allows or disables double click handling on a canvas (Motif, Windows 3.1 and WIN32).
The default is FALSE. Note that this feature has not been rigorously tested.

See also \helpref{wxMouseEvent::ButtonDClick}{buttondclick}.

\membersection{wxCanvas::BeginDrawing}

\func{void}{BeginDrawing}{\void}

Allows optimization of drawing code under Windows 3.1 and WIN32. Enclose
drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
calls.

\membersection{wxCanvas::Create}

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

Creates the canvas for two-step construction. Derived classes
should call or replace this function. See \helpref{wxCanvas::wxCanvas}{constrcanvas}
for details.

\membersection{wxCanvas::Clear}

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

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

\membersection{wxCanvas::DestroyClippingRegion}\label{wxcanvasdestroyclippingregion}

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

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

\membersection{wxCanvas::DrawArc}

\func{void}{DrawArc}{\param{float}{ x1}, \param{float}{ y1}, \param{float}{ x2}, \param{float}{ y2}, \param{float}{xc}, \param{float}{yc}}

Draws an arc, centred on ({\it xc, yc}), with starting point ({\it x1, y1})
and ending at ({\it x2, y2}).   The current pen is used for the outline
and the current brush for filling the shape.

\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},\\
  \param{int }{fill\_style = wxODDEVEN\_RULE}}

\func{void}{DrawPolygon}{\param{wxList *}{points}, \param{float}{ xoffset = 0},
\param{float}{ yoffset = 0}, \param{int }{fill\_style = wxODDEVEN\_RULE}}

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 last argument specifies the fill rule: {\bf wxODDEVEN\_RULE} (the
default) or {\bf wxWINDING\_RULE}.

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 automatically closes the first and last points.

\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.

If {\it radius} is positive, the value is assumed to be the
radius of the rounded corner. If {\it radius} is negative,
the absolute value is assumed to be the {\it proportion} of the smallest
dimension of the rectangle. This means that the corner can be
a sensible size relative to the size of the rectangle, and also avoids
the strange effects X produces when the corners are too big for
the rectangle.

\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}\label{wxcanvasdrawtext}

\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::EnableScrolling}\label{wxcanvasenablescrolling}

\func{void}{EnableScrolling}{\param{Bool}{ xScrolling}, \param{Bool}{ yScrolling}}

Enable or disable Windows scrolling in the given direction, where in
this context scrolling is the physical transfer of bits up or down the
screen when a scroll event occurs. If the application scrolls by a
variable amount (e.g. if there are different font sizes) then physical
scrolling messes up the display.

\membersection{wxCanvas::EndDrawing}

\func{void}{EndDrawing}{\void}

Allows optimization of drawing code under Windows 3.1 and WIN32. Enclose
drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
calls.

\membersection{wxCanvas::GetDC}\label{wxcanvasgetdc}

\func{wxCanvasDC *}{GetDC}{\void}

Get a pointer to the canvas's device context. See \helpref{wxDC}{wxdc}
and \helpref{wxCanvasDC}{wxcanvasdc}.

\membersection{wxCanvas::GetScrollUnitsPerPage}\label{wxcanvasgetscrollunits}

\func{void}{GetScrollUnitsPerPage}{\param{int *}{x\_page}, \param{int *}{y\_page}}

Get the number of units per page, in each direction, as set
by \helpref{wxCanvas::SetScrollbars}{wxcanvassetscrollbars}. A value of zero indicates no
scrolling in that direction.

\membersection{wxCanvas::GetVirtualSize}\label{wxcanvasgetvirtualsize}

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

Gets the size in device units of the scrollable canvas area (as
opposed to the client size, which is the area of the canvas currently
visible).

Use \helpref{wxDC::DeviceToLogicalX}{wxdcdevicetologicalx} and \helpref{wxDC::DeviceToLogicalY}{wxdcdevicetologicaly}
to translate these units to logical units.

\membersection{wxCanvas::IntDrawLine}

\func{void}{IntDrawLine}{\param{int}{ x1}, \param{int}{ y1}, \param{int}{ x2},
\param{int}{ y2}}

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

\membersection{wxCanvas::IntDrawLines}

\func{void}{IntDrawLines}{\param{int}{ n}, \param{wxIntPoint}{ points[]}, \param{int}{ xoffset = 0}, \param{int}{ yoffset = 0}}

Draw lines using an array of {\it points} of size {\it n}. The current pen is used
for drawing the lines.  The programmer is responsible for deleting the list of points.

\membersection{wxCanvas::IsRetained}

\func{Bool}{IsRetained}{\void}

TRUE if the canvas has a backing bitmap.

\membersection{wxCanvas::OnChar}\label{wxcanvasonchar}

\func{void}{OnChar}{\param{wxKeyEvent\& }{event}}

This default handler interprets cursor key movement and scrolls the
canvas accordingly.  Override the function to change this behaviour
(see \helpref{wxWindow::OnChar}{winonchar} for details).

\membersection{wxCanvas::OnEvent}\label{wxcanvasonevent}

\func{void}{OnEvent}{\param{wxMouseEvent\&}{ event}}

Sent to the canvas when the user has initiated an event with the mouse.
Derive your own class to handle this message. See \helpref{wxCanvas::OnChar}{wxcanvasonchar}
for character events, and also \helpref{wxMouseEvent}{wxmouseevent} for how to access
event information.

\membersection{wxCanvas::OnPaint}

\func{void}{OnPaint}{\void}

Sent to the canvas when the canvas must be refreshed. Derive your own
class to handle this message.

\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).

See also \helpref{wxCanvas::SetScrollbars}{wxcanvassetscrollbars}.

\membersection{wxCanvas::SetBackground}

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

Sets the current background brush for the canvas, used for the pixels
between dotted or dashed lines.  The brush should not be deleted while
being used by a canvas. All brushes are deleted automatically when the
application terminates.

See also \helpref{wxBrush}{wxbrush}.

\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.

See also \helpref{wxCanvas::DestroyClippingRegion}{wxcanvasdestroyclippingregion}.

\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.

See also \helpref{wxBrush}{wxbrush}.

\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.

See also \helpref{wxFont}{wxfont}, \helpref{wxCanvas::DrawText}{wxcanvasdrawtext}.

\membersection{wxCanvas::SetLogicalFunction}

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

Sets the current logical function for the canvas.  This determines how
a source pixel (from a pen or brush colour, or source device context if using \helpref{wxDC::Blit}{wxdcblit})
combines with a destination pixel in the current device context.

The possible values
and their meaning in terms of source and destination pixel values are
as follows:

\begin{verbatim}
wxAND                 src AND dst
wxAND_INVERT          (NOT src) AND dst
wxAND_REVERSE         src AND (NOT dst)
wxCLEAR               0
wxCOPY                src
wxEQUIV               (NOT src) XOR dst
wxINVERT              NOT dst
wxNAND                (NOT src) OR (NOT dst)
wxNOR                 (NOT src) AND (NOT dst)
wxNO_OP               dst
wxOR                  src OR dst
wxOR_INVERT           (NOT src) OR dst
wxOR_REVERSE          src OR (NOT dst)
wxSET                 1
wxSRC_INVERT          NOT src
wxXOR                 src XOR dst
\end{verbatim}

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}\label{wxcanvassetpen}

\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.

See also \helpref{wxPen}{wxpen}.

\membersection{wxCanvas::SetScrollbars}\label{wxcanvassetscrollbars}

\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}, \param{int }{x\_pos = 0}, \param{int}{ y\_pos = 0}}

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.

{\it x\_pos} and {\it y\_pos} optionally specify a position to scroll to immediately.

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}

See also \helpref{wxCanvas::EnableScrolling}{wxcanvasenablescrolling},
\rtfsp\helpref{wxCanvas::GetScrollUnitsPerPage}{wxcanvasgetscrollunits}, \helpref{wxCanvas::GetVirtualSize}{wxcanvasgetvirtualsize}.

\membersection{wxCanvas::SetTextBackground}\label{wxcanvassettextbackground}

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

Sets the current text background colour for the canvas.  Do not
delete {\it colour}. See also \helpref{wxCanvas::SetTextForeground}{wxcanvassettextforeground}.

\membersection{wxCanvas::SetTextForeground}\label{wxcanvassettextforeground}

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

Sets the current text foreground colour for the canvas. Do not
delete {\it colour}.  See also \helpref{wxCanvas::SetTextBackground}{wxcanvassettextbackground}.

\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
\rtfsp{\it y} will be greater than zero.  Combined with \helpref{wxWindow::GetClientSize}{wingetclientsize},
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.

See also \helpref{wxCanvas::SetScrollbars}{wxcanvassetscrollbars}.

\membersection{wxCanvas::WarpPointer}

\func{void}{WarpPointer}{\param{int}{ x}, \param{int}{ y}}

Moves the pointer to the given position on the canvas.

\section{\class{wxCanvasDC}: wxDC}\label{wxcanvasdc}

A canvas device context is automatically created when a canvas is created.
It can be retrieved from a canvas with \helpref{wxCanvas::GetDC}{wxcanvasgetdc} and then
drawn into. See \helpref{wxDC}{wxdc} for further information on device contexts.

\membersection{wxCanvasDC::wxCanvasDC}

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

Constructor for internal use only.

\section{\class{wxCheckBox}: wxItem}\label{wxcheckbox}

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

\membersection{wxCheckBox::wxCheckBox}\label{constrcheckbox}

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

Constructor, used when deriving from this class.

\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},\\
  \param{long}{ style = 0}, \param{char *}{name = ``checkBox"}}

\func{void}{wxCheckBox}{\param{wxPanel *}{parent}, \param{wxFunction}{ func},
  \param{wxBitmap *}{bitmap}, \\\param{int}{ x = -1}, \param{int}{ y = -1},
  \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``checkBox"}}

Constructor, creating and showing a checkbox.

{\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.

In the second form, if {\it label} is non-NULL, it is used as the label
for the checkbox. In the third form, a bitmap is provided instead of
a text label.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

If {\it width} or {\it height} are omitted (or are less than zero), an
appropriate size will be used for the check box.

The {\it style} parameter is reserved for future use.

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual checkboxes.

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

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

Destructor, destroying the checkbox.

\membersection{wxCheckBox::Create}

\func{Bool}{Create}{\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{long}{ style = 0}, \param{char *}{name = ``checkBox"}}

\func{Bool}{Create}{\param{wxPanel *}{parent}, \param{wxFunction}{ func},
  \param{char *}{bitmap}, \\\param{int}{ x = -1}, \param{int}{ y = -1},
  \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``checkBox"}}

Creates the checkbox for two-step construction. Derived classes
should call or replace this function. See \helpref{wxCheckBox::wxCheckBox}{constrcheckbox}
for details.

\membersection{wxCheckBox::GetValue}

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

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

\membersection{wxCheckBox::SetLabel}\label{wxcheckboxsetlabel}

\func{void}{SetLabel}{\param{wxBitmap *}{label}}

Sets the bitmap for a bitmap checkbox.

\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}\label{wxchoice}

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.

See also \helpref{wxListBox}{wxlistbox}.

\membersection{wxChoice::wxChoice}\label{constrchoice}

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

Constructor, for use by derived classes.

\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[]},\\
  \param{long}{ style = 0}, \param{char *}{name = ``choice"}}

Constructor, creating and showing a 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.

If {\it label} is non-NULL, it is used as the label for the choice item.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

If {\it width} or {\it height} are omitted (or are less than zero), an
appropriate size will be used for the choice.

{\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.

The {\it style} parameter is reserved for future use.

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual choice items.

\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::Create}

\func{Bool}{Create}{\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[]}\\
  \param{long}{ style = 0}, \param{char *}{name = ``choice"}}

Creates the choice for two-step construction. Derived classes
should call or replace this function. See \helpref{wxChoice::wxChoice}{constrchoice}
for further details.

\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::GetString}

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

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

\section{\class{wxClient}: wxIPCObject}\label{wxclient}

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

To create a client which can communicate with a suitable server,
you need to derive a class from wxConnection and another from wxClient.
The custom wxConnection class will intercept communications in
a `conversation' with a server, and the custom wxServer is required
so that a user-overriden \helpref{wxClient::OnMakeConnection}{wxclientonmakeconnection} member can return
a wxConnection of the required class, when a connection is made.

For example:

\begin{verbatim}
class MyConnection: public wxConnection
{
 public:
  MyConnection(void)::wxConnection(ipc_buffer, 3999) {}
  ~MyConnection(void) { }
  Bool OnAdvise(char *topic, char *item, char *data, int size, int format)
  { wxMessageBox(topic, data); }
};

class MyClient: public wxClient
{
 public:
  MyClient(void) {}
  wxConnection *OnMakeConnection(void) { return new MyConnection; }
};

\end{verbatim}

Here, {\bf MyConnection} will respond to \helpref{OnAdvise}{wxconnectiononadvise} messages sent
by the server.

When the client application starts, it must first call \helpref{wxIPCInitialize}{wxipcinitialize}
before creating an instance of the derived wxClient. In the following, command line
arguments are used to pass the host name (the name of the machine the server is running
on) and the server name (identifying the server process). Calling \helpref{wxClient::MakeConnection}{wxclientmakeconnection}
implicitly creates an instance of {\bf MyConnection} if the request for a
connection is accepted, and the client then requests an {\it Advise} loop
from the server, where the server calls the client when data has changed.

\begin{verbatim}
  wxIPCInitialize();

  char *server = "4242";
  char hostName[256];
  wxGetHostName(hostName, sizeof(hostName));

  char *host = hostName;

  if (argc > 1)
    server = argv[1];
  if (argc > 2)
    host = argv[2];

  // Create a new client
  MyClient *client = new MyClient;
  the_connection = (MyConnection *)client->MakeConnection(host, server, "IPC TEST");

  if (!the_connection)
  {
    wxMessageBox("Failed to make connection to server", "Client Demo Error");
    return NULL;
  }
  the_connection->StartAdvise("Item");
\end{verbatim}

See also \helpref{wxServer}{wxserver}, \helpref{wxConnection}{wxconnection},
the chapter on interprocess communication in the user manual, and
the programs in {\tt samples/ipc}.

\membersection{wxClient::wxClient}

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

Constructs a client object.

\membersection{wxClient::MakeConnection}\label{wxclientmakeconnection}

\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 overriding
the \helpref{wxClient::OnMakeConnection}{wxclientonmakeconnection} member to return your own
derived connection object.

\membersection{wxClient::OnMakeConnection}\label{wxclientonmakeconnection}

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

The type of \helpref{wxConnection}{wxconnection} returned from a \helpref{wxClient::MakeConnection}{wxclientmakeconnection} 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.

The advantage of deriving your own connection class is that it will
enable you to intercept messages initiated by the server, such
as \helpref{wxConnection::OnAdvise}{wxconnectiononadvise}. You may also want to
store application-specific data in instances of the new class.

\section{\class{wxColour}: wxObject}\label{wxcolour}

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}{wxcolourdatabase} for how a pointer to a predefined,
named colour may be returned instead of creating a new colour.

Valid RGB values are in the range 0 to 255.

\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::$=$}\label{wxcolourequal}

\func{wxColour\&}{$=$}{\param{wxColour\&}{ src}}

Assignment from source to destination colour.

\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::Ok}

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

Returns TRUE if the colour object is valid.

\membersection{wxColour::Set}

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

Sets the RGB value.

\section{\class{wxColourDatabase}: wxObject}\label{wxcolourdatabase}

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.

wxWindows' colour handling under XView and Motif prior to Version 1.50
was poor, due to a bug in the code which allocates colours. This has
now been fixed and a greater range of colours may be allocated.
However, if a very wide range of colours is used in an application,
wxWindows may still fail to allocate a colour, so it is best to choose
a fixed number of colours, pens or brushes rather than allocate
colours when needed.

See also \helpref{wxColour}{wxcolour}.

\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{wxColourMap}: wxObject}\label{wxcolourmap}

Colourmap functionality is incomplete, and will be extended in the future.
Currently, colourmaps may be returned from some wxWindows libraries
that load bitmaps (e.g. wxImage, DIB). To display a bitmap, its colourmap
should normally be set for that window.

There are some strict rules for colourmap useage. A colourmap should
never be deleted before being deselected from a window or device
context (although it may be used for several windows and device
contexts simultaneously). So, call \helpref{wxDC::SetColourMap}{wxdcsetcolourmap}\rtfsp
with a NULL argument to make sure that its original (probably system)
colourmap is restored.

If you are relying on wxWindows to clean up your bitmaps on program
exit, then you must be extra vigilant about cleaning up colourmaps
before bitmaps (and windows) are deleted. So it may not be an option
to use global objects, where you cannot be sure of the order
that C++ destroys objects; use dynamically created and destroyed
objects instead.

\membersection{wxColourMap::wxColourMap}

\func{void}{wxColourMap}{\void}

Constructor.

\membersection{wxColourMap::\destruct{wxColourMap}}

\func{void}{\destruct{wxColourMap}}{\void}

Destructor.

If you have to delete the colourmap (for example, you are creating a lot of
them), then call \helpref{wxDC::SetColourMap}{wxdcsetcolourmap} with a NULL argument
to ensure that the old colourmap is restored, and the current colourmap is selected
out of the device context.

\membersection{wxColourMap::Create}

\func{Bool}{Create}{\param{const int}{ n}, \param{const char *}{red},\\
 \param{const char *}{green}, \param{const char *}{blue}}

Creates a colourmap from arrays of size {\it n}, one for each
red, blue or green component. Implemented only under Windows.

\section{\class{wxCommandEvent}: wxEvent}\label{wxcommandevent}

This event class contains information about panel item command events.
It is passed to \helpref{wxFunction}{wxfunction} panel item callbacks. It
can also be constructed by an application and used with \helpref{wxSendEvent}{wxsendevent}
to simulate a user command in a panel item.

\membersection{wxCommandEvent::clientData}

\member{char *}{clientData}

Contains a pointer to client data for listboxes and choices, if the event
was a selection.

\membersection{wxCommandEvent::commandInt}

\member{int}{ commandInt}

Contains an integer identifier corresponding to a listbox, choice or
radiobox selection (only if the event was a selection, not a
deselection), or a Boolean value representing the value of a checkbox.

\membersection{wxCommandEvent::commandString}

\member{char *}{commandString}

Contains a string corresponding to a listbox or choice selection.

\membersection{wxCommandEvent::extraLong}

\member{long}{ extraLong}

Extra information. If the event comes from a listbox selection, it is
a Boolean determining whether the event was a selection (TRUE) or a
deselection (FALSE). A listbox deselection only occurs for
multiple-selection boxes, and in this case the index and string values
are indeterminate and the listbox must be examined by the application.

\membersection{wxCommandEvent::wxCommandEvent}

\func{void}{wxCommandEvent}{\param{WXTYPE}{ commandEventType}}

Constructor. {\it commandEventType} may be one of the following:

\begin{itemize}
\item {\bf wxEVENT\_TYPE\_BUTTON\_COMMAND}
\item {\bf wxEVENT\_TYPE\_CHECKBOX\_COMMAND}
\item {\bf wxEVENT\_TYPE\_CHOICE\_COMMAND}
\item {\bf wxEVENT\_TYPE\_LISTBOX\_COMMAND}
\item {\bf wxEVENT\_TYPE\_TEXT\_COMMAND}
\item {\bf wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND}
\item {\bf wxEVENT\_TYPE\_MULTITEXT\_COMMAND}
\item {\bf wxEVENT\_TYPE\_MENU\_COMMAND}
\item {\bf wxEVENT\_TYPE\_SLIDER\_COMMAND}
\item {\bf wxEVENT\_TYPE\_RADIOBOX\_COMMAND}
\item {\bf wxEVENT\_TYPE\_SET\_FOCUS}
\item {\bf wxEVENT\_TYPE\_KILL\_FOCUS}
\end{itemize}

\membersection{wxCommandEvent::Checked}

\func{Bool}{Checked}{\void}

Returns TRUE or FALSE for a checkbox selection event.

\membersection{wxCommandEvent::GetClientData}

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

Returns client data pointer for a listbox or choice selection event
(not valid for a deselection).

\membersection{wxCommandEvent::GetSelection}

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

Returns item index for a listbox or choice selection event (not valid for
a deselection).

\membersection{wxCommandEvent::GetString}

\func{char *}{GetString}{\void}

Returns item string for a listbox or choice selection event (not valid for
a deselection).

\membersection{wxCommandEvent::IsSelection}

\func{Bool}{IsSelection}{\void}

For a listbox or choice event, returns TRUE if it is a selection, FALSE if it
is a deselection.

\section{\class{wxConnection}: wxObject}\label{wxconnection}

A wxConnection object represents the connection between a client and a
server. It can be created by making a connection using a\rtfsp
\helpref{wxClient}{wxclient} object, or by the acceptance of a connection by a\rtfsp
\helpref{wxServer}{wxserver} object. The bulk of a DDE (Dynamic Data Exchange)
conversation (available in both Windows and UNIX) is controlled by
calling members in a {\bf wxConnection} object or by overriding its
members.

An application should normally derive a new connection class from
wxConnection, in order to override the communication event handlers
to do something interesting.

See \helpref{wxClient}{wxclient}, \helpref{wxServer}{wxserver}, and
the chapter on interprocess communication in the user manual.

\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 \helpref{wxServer::OnAcceptConnection}{wxserveronacceptconnection}
and/or \helpref{wxClient::OnMakeConnection}{wxclientonmakeconnection} 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 \helpref{wxConnection::OnAdvise}{wxconnectiononadvise}
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 \helpref{wxConnection::Poke}{wxconnectionpoke} in that respect). Causes the
server connection's \helpref{wxConnection::OnExecute}{wxconnectiononexecute} 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 \helpref{wxConnection::OnDisconnect}{wxconnectionondisconnect} 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}\label{wxconnectiononadvise}

\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}\label{wxconnectionondisconnect}

\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}\label{wxconnectiononexecute}

\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}\label{wxconnectiononpoke}

\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}\label{wxconnectiononrequest}

\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 \helpref{wxConnection::Request}{wxconnectionrequest}. The server
should respond by returning a character string from {\bf OnRequest},
or NULL to indicate no data.

\membersection{wxConnection::OnStartAdvise}\label{wxconnectiononstartadvise}

\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}\label{wxconnectiononstopadvise}

\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}\label{wxconnectionpoke}

\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 \helpref{wxConnection::OnPoke}{wxconnectiononpoke} member
to be called. Returns TRUE if successful.

\membersection{wxConnection::Request}\label{wxconnectionrequest}

\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 \helpref{wxConnection::OnRequest}{wxconnectiononrequest} member to be called. Returns a
character string (actually a pointer to the connection's buffer) if
successful, NULL otherwise.

\membersection{wxConnection::StartAdvise}\label{wxconnectionstartadvise}

\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 \helpref{wxConnection::OnStartAdvise}{wxconnectiononstartadvise}
member to be called. Returns TRUE if the server okays it, FALSE
otherwise.

\membersection{wxConnection::StopAdvise}\label{wxconnectionstopadvise}

\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 \helpref{wxConnection::OnStopAdvise}{wxconnectiononstopadvise} member
to be called. Returns TRUE if the server okays it, FALSE otherwise.

\section{\class{wxCursor}: wxObject}\label{wxcursor}

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}{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 \helpref{::wxSetCursor}{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}{\void}

\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}\label{wxdc}

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
\rtfsp{\bf Colour} Bool member variable. To override wxWindows monochrome
graphics drawing behaviour, set this member to TRUE.

From version 1.5, this class is abstract and cannot be used to create
device context objects. Instead, use the derived classes \helpref{wxPostScriptDC}{wxpostscriptdc},
\rtfsp\helpref{wxMetaFileDC}{wxmetafiledc}, \helpref{wxMemoryDC}{wxmemorydc} or \helpref{wxPrinterDC}{wxprinterdc}
(Windows only) for constructing new device contexts.  \helpref{wxCanvasDC}{wxcanvasdc}
is a context that cannot be created by the user but can be retrieved from
a \helpref{wxCanvas}{wxcanvas} by using \helpref{wxCanvas::GetDC}{wxcanvasgetdc}.

When writing code to draw into a device context, use {\bf wxDC} as a
parameter whenever possible, to allow the most general use of your
drawing code.  You can then pass a device context object of any
derived type. See the demo in {\tt samples/hello} for code which
uses this device-independent method of drawing.

Derived types of {\bf wxDC} have documentation for specific features
only, so refer to this section for most device context information.

\membersection{wxDC::wxDC}

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

Constructor.

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

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

Destructor.

\membersection{wxDC::BeginDrawing}

\func{void}{BeginDrawing}{\void}

Allows optimization of drawing code under Windows 3.1 and WIN32. Enclose
drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
calls.

\membersection{wxDC::Blit}\label{wxdcblit}

\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{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}).
See \helpref{wxMemoryDC}{wxmemorydc} for typical usage.

\membersection{wxDC::Clear}

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


\membersection{wxDC::DestroyClippingRegion}\label{wxdcdestroyclippingregion}

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

Destroys the current clipping region so that none of the DC is clipped.
See also \helpref{wxDC::SetClippingRegion}{wxdcsetclippingregion}.

\membersection{wxDC::DeviceToLogicalX}\label{wxdcdevicetologicalx}

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

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

\membersection{wxDC::DeviceToLogicalY}\label{wxdcdevicetologicaly}

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

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

\membersection{wxDC::DrawArc}

\func{void}{DrawArc}{\param{float}{ x1}, \param{float}{ y1}, \param{float}{ x2}, \param{float}{ y2}, \param{float}{xc}, \param{float}{yc}}

Draws an arc, centred on ({\it xc, yc}), with starting point ({\it x1, y1})
and ending at ({\it x2, y2}).   The current pen is used for the outline
and the current brush for filling the shape.

\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}\label{wxdcdrawicon}

\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.

\membersection{wxDC::DrawLine}\label{wxdcdrawline}

\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},\\
  \param{int }{fill\_style = wxODDEVEN\_RULE}}

\func{void}{DrawPolygon}{\param{wxList *}{points}, \param{float}{ xoffset = 0}, \param{float}{ yoffset = 0},\\
  \param{int }{fill\_style = wxODDEVEN\_RULE}}

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 last argument specifies the fill rule: {\bf wxODDEVEN\_RULE} (the
default) or {\bf wxWINDING\_RULE}.

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 automatically closes the first and last points.

\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.

If {\it radius} is positive, the value is assumed to be the
radius of the rounded corner. If {\it radius} is negative,
the absolute value is assumed to be the {\it proportion} of the smallest
dimension of the rectangle. This means that the corner can be
a sensible size relative to the size of the rectangle, and also avoids
the strange effects X produces when the corners are too big for
the rectangle.

\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}\label{wxdcdrawtext}

\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.

The coordinates refer to the top-left corner of the rectangle bounding
the string. See \helpref{wxDC::GetTextExtent}{wxdcgettextextent} for how
to get the dimensions of a text string, which can be used to position the
text more precisely.

\membersection{wxDC::EndDoc}

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

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

\membersection{wxDC::EndDrawing}

\func{void}{EndDrawing}{\void}

Allows optimization of drawing code under Windows 3.1 and WIN32. Enclose
drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
calls.

\membersection{wxDC::EndPage}

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

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

\membersection{wxDC::GetBackground}

\func{wxBrush *}{GetBackground}{\void}

Gets the brush used for painting the background (see \helpref{wxDC::SetBackground}{wxdcsetbackground}).

\membersection{wxDC::GetBrush}

\func{wxBrush *}{GetBrush}{\void}

Gets the current brush (see \helpref{wxDC::SetBrush}{wxdcsetbrush}).

\membersection{wxDC::GetFont}

\func{wxFont *}{GetFont}{\void}

Gets the current font (see \helpref{wxDC::SetFont}{wxdcsetfont}).

\membersection{wxDC::GetLogicalFunction}

\func{int}{GetLogicalFunction}{\void}

Gets the current logical function (see \helpref{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}).

\membersection{wxDC::GetMapMode}

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

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

\membersection{wxDC::GetSize}\label{wxdcgetsize}

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

For a PostScript device context, this gets the maximum size of graphics
drawn so far on the device context.

For a Windows printer device context, this gets the horizontal and vertical
resolution. It can be used to scale graphics to fit the page when using
a Windows printer device context. For example, if {\it maxX} and {\it maxY}
represent the maximum horizontal and vertical `pixel' values used in your
application, the following code will scale the graphic to fit on the
printer page:

\begin{verbatim}
  float w, h;
  dc.GetSize(&w, &h);
  float scaleX=(float)(maxX/w);
  float scaleY=(float)(maxY/h);
  dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY)).
\end{verbatim}

\membersection{wxDC::GetPen}

\func{wxPen *}{GetPen}{\void}

Gets the current pen (see \helpref{wxDC::SetPen}{wxdcsetpen}).

\membersection{wxDC::GetTextBackground}

\func{wxColour\&}{GetTextBackground}{\void}

Gets the current text background colour (see \helpref{wxDC::SetTextBackground}{wxdcsettextbackground}).

\membersection{wxDC::GetTextExtent}\label{wxdcgettextextent}

\func{void}{GetTextExtent}{\param{char *}{string}, \param{float *}{w}, \param{float *}{h},\\
  \param{float *}{descent = NULL}, \param{float *}{externalLeading = NULL}}

Gets the dimensions of the string using the currently selected font.
\rtfsp{\it string} is the text string to measure, {\it w} and {\it h} are
the total width and height respectively, {\it descent} is the
dimension from the baseline of the font to the bottom of the
descender, and {\it externalLeading} is any extra vertical space added
to the font by the font designer (usually is zero).

See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}.

\membersection{wxDC::GetTextForeground}

\func{wxColour\&}{GetTextForeground}{\void}

Gets the current text foreground colour (see \helpref{wxDC::SetTextForeground}{wxdcsettextforeground}).

\membersection{wxDC::IntDrawLine}

\func{void}{IntDrawLine}{\param{int}{ x1}, \param{int}{ y1}, \param{int}{ x2},
\param{int}{ y2}}

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

\membersection{wxDC::IntDrawLines}

\func{void}{IntDrawLines}{\param{int}{ n}, \param{wxIntPoint}{ points[]}, \param{int}{ xoffset = 0}, \param{int}{ yoffset = 0}}

Draw lines using an array of {\it points} of size {\it n}. The current pen is used
for drawing the lines.  The programmer is responsible for deleting the list of points.

\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::MaxX}

\func{float}{MaxX}{\void}

Gets the maximum horizontal extent used in drawing commands so far.

\membersection{wxDC::MaxY}

\func{float}{MaxY}{\void}

Gets the maximum vertical extent used in drawing commands so far.

\membersection{wxDC::MinX}

\func{float}{MinX}{\void}

Gets the minimum horizontal extent used in drawing commands so far.

\membersection{wxDC::MinY}

\func{float}{MinY}{\void}

Gets the minimum vertical extent used in drawing commands so far.

\membersection{wxDC::Ok}

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

Returns TRUE if the DC is ok to use.

\membersection{wxDC::SetBackground}\label{wxdcsetbackground}

\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::SetBackgroundMode}\label{wxdcsetbackgroundmode}

\func{void}{SetBackgroundMode}{\param{int}{ mode}}

{\it mode} may be one of wxSOLID and wxTRANSARENT. This setting determines
whether text will be drawn with a background colour or not.

\membersection{wxDC::SetClippingRegion}\label{wxdcsetclippingregion}

\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.

See also \helpref{wxDC::DestroyClippingRegion}{wxdcdestroyclippingregion}.

\membersection{wxDC::SetColourMap}\label{wxdcsetcolourmap}

\func{void}{SetColourMap}{\param{wxColourMap *}{colourMap}}

If this is a canvas DC or memory DC, assigns the given colourmap to the window
or bitmap associated with the DC. If the argument is NULL, the current
colourmap is selected out of the device context, and the original colourmap
restored, allowing the current colourmap to be destroyed safely.

See \helpref{wxColourMap}{wxcolourmap} for further details.

\membersection{wxDC::SetBrush}\label{wxdcsetbrush}

\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.

If the argument is NULL, the current brush is selected out of the device
context, and the original brush restored, allowing the current brush to
be destroyed safely.

See also \helpref{wxBrush}{wxbrush}.

\membersection{wxDC::SetFont}\label{wxdcsetfont}

\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.

If the argument is NULL, the current font is selected out of the device
context, and the original font restored, allowing the current font to
be destroyed safely.

See also \helpref{wxFont}{wxfont}.

\membersection{wxDC::SetLogicalFunction}\label{wxdcsetlogicalfunction}

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

Sets the current logical function for the canvas.  This determines how
a source pixel (from a pen or brush colour, or source device context if
using \helpref{wxDC::Blit}{wxdcblit}) combines with a destination pixel in the
current device context.

The possible values
and their meaning in terms of source and destination pixel values are
as follows:

\begin{verbatim}
wxAND                 src AND dst
wxAND_INVERT          (NOT src) AND dst
wxAND_REVERSE         src AND (NOT dst)
wxCLEAR               0
wxCOPY                src
wxEQUIV               (NOT src) XOR dst
wxINVERT              NOT dst
wxNAND                (NOT src) OR (NOT dst)
wxNOR                 (NOT src) AND (NOT dst)
wxNO_OP               dst
wxOR                  src OR dst
wxOR_INVERT           (NOT src) OR dst
wxOR_REVERSE          src OR (NOT dst)
wxSET                 1
wxSRC_INVERT          NOT src
wxXOR                 src XOR dst
\end{verbatim}

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}\label{wxdcsetmapmode}

\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{wxDC::SetUserScale}{wxdcsetuserscale}) 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{twocollist}
\twocolitem{MM\_TWIPS}{Each logical unit is 1/20 of a point, or 1/1440 of
  an inch.}
\twocolitem{MM\_POINTS}{Each logical unit is a point, or 1/72 of an inch.}
\twocolitem{MM\_METRIC}{Each logical unit is 1 mm.}
\twocolitem{MM\_LOMETRIC}{Each logical unit is 1/10 of a mm.}
\twocolitem{MM\_TEXT}{Each logical unit is 1 pixel.}
\end{twocollist}

\membersection{wxDC::SetPen}\label{wxdcsetpen}

\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.

If the argument is NULL, the current pen is selected out of the device
context, and the original pen restored, allowing the current pen to
be destroyed safely.

\membersection{wxDC::SetTextBackground}\label{wxdcsettextbackground}

\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}\label{wxdcsettextforeground}

\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}\label{wxdcsetuserscale}

\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}\label{wxdialogbox}

A dialog box is similar to a panel, in that it is a window which can
be used for placing panel items, 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,
and two modal dialogs may not be open simultaneously.

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. See the discussion about dialogs in
the user manual.

For a set of dialog convenience functions, including file selection, see
\rtfsp\helpref{Dialog functions}{dialogfunctions}.

See also \helpref{wxPanel}{wxpanel} and \helpref{wxWindow}{wxwindow} for inherited
member functions.

\membersection{wxDialogBox::wxDialogBox}\label{constrdialog}

\func{void}{wxDialogBox}{\param{wxWindow *}{parent}, \param{char *}{title},
\param{Bool}{ modal=FALSE},\\ \param{int}{ x=300}, \param{int}{ y=300}, 
  \param{int}{ width=500}, \param{int}{ height=500},\\
  \param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\\
  \param{char *}{name = ``dialogBox"}}

Constructor. The {\it parent} of the dialog box can be NULL, a frame or
a dialog box.

If {\it title} is non-NULL, it is placed on the window frame.

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

The {\it style} parameter may be a combination of the following, using the bitwise `or' operator:

\begin{twocollist}
\twocolitem{wxABSOLUTE\_POSITIONING}{A hint to the windowing system not to try automatic layout
  (Motif only). {\it This is now obsolete from version 1.60.}}
\twocolitem{wxCAPTION}{Puts a caption on the dialog box (Motif only).}
%\twocolitem{wxSTAY\_ON\_TOP}{Stay on top of other windows (Windows only).}
\twocolitem{wxSYSTEM\_MENU}{Display a system menu (Motif only).}
\twocolitem{wxTHICK\_FRAME}{Display a thick frame around the window (Motif only).}
\twocolitem{wxRESIZE\_BORDER}{Display a resizeable frame around the window (Motif only).}
\twocolitem{wxVSCROLL}{Give the dialog box a vertical scrollbar (XView only).}
\twocolitem{wxDEFAULT\_DIALOG\_STYLE}{Equivalent to wxCAPTION $\|$ wxSYSTEM\_MENU $\|$ wxTHICK\_FRAME}
\end{twocollist}

Note that none take effect under Windows, only wxVSCROLL works under XView,
and for Motif the MWM (the Motif Window Manager) should be running for any to work.

The {\it name} parameter is used to associate a name with the window,
allowing the application user to set Motif resource values for
individual dialog boxes.

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

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

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

\membersection{wxDialog::Centre}

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

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

\membersection{wxDialogBox::Create}

\func{void}{Create}{\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},\\
  \param{long}{ style = wxCAPTION $\|$ wxSYSTEM\_MENU $\|$ wxTHICK\_FRAME},\\
  \param{char *}{name = ``dialogBox"}}

Used for two-step dialog box construction. See \helpref{wxDialogBox::wxDialogBox}{constrdialog}
for details.

\membersection{wxDialogBox::GetTitle}

\func{char *}{GetTitle}{\void}

Gets a temporary pointer to the title of the dialog box.

\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
\rtfsp{\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::SetTitle}

\func{void}{SetTitle}{\param{char *}{ title}}

Sets the title of the dialog box.

\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{wxEnhDialogBox}: wxDialogBox}

The purpose of the wxEnhDialogBox class is to make it easy to
provide a common look for all dialog boxes of an application. The
wxEnhDialogBox separates the dialog box into four areas:

\begin{itemize}
\item the pin area
\item the user area
\item the command area
\item the status area
\end{itemize}

For now, these panels are tiled vertically, but in future there may a
style flag to allow placement of the command area to the right of the dialog, as
is common in Windows applications.

The pin area is borrowed from the pushpin metaphor of XView, and can be
disabled via a compilation flag. Again, a flag style is perhaps more
judicious and may be implemented in future.

The user area is left free for the application programmer.

The command area contains command buttons which are centered automatically
by the \helpref{wxEnhDialogBox::Fit}{wxenhdialogfit} method.

The status area provides a way to display status messages, as in XView.

All areas can have distints fonts sets, currently controlled by a compilation
flag. The pushpin can be replaced by a Cancel button (automatically created)
if WANT\_CANCEL\_BUTTON is defined when compiling.

\membersection{wxEnhDialogBox::wxEnhDialogBox}

\func{void}{wxEnhDialogBox}{\param{wxFrame *}{frame}, \param{char *}{title},\\
 \param{Bool }{modal = FALSE}, \param{wxFunction }{fun = NULL}, \param{int }{space = -1},\\
 \param{int }{x = 0}, \param{int }{y = 0}, \param{int }{width = 10}, \param{int }{height = 10},\\
 \param{char *}{name = "Shell"}}

Constructor. {\it fun} is called when the user dismiss the window by
using the pin or the cancel button. If {\it space} is greater than zero, it is
used as panel horizontal spacing for the command area.

\membersection{wxEnhDialogBox::\destruct{wxEnhDialogBox}}

\func{void}{\destruct{wxEnhDialogBox}}{\void}

Destructor.

\membersection{wxEnhDialogBox::userPanel}

\member{wxPanel *}{userPanel}

User application items must be created in this panel.

\membersection{wxEnhDialogBox::SetStatus}

\func{void}{SetStatus}{\param{char *}{label=NULL}}

Display text in the staus area.

\membersection{wxEnhDialogBox::AddCmd}

\func{wxButton *}{AddCmd}{\param{char *}{label}, \param{wxFunction }{fun=NULL},\\
  \param{int }{tag = 0}}

\func{wxButton *}{AddCmd}{\param{wxBitmap *}{bitmap}, \param{wxFunction }{fun=NULL},\\
  \param{int }{tag = 0}}

Adds a command button in the command area, and returns its identifier. The
client data part of the button is initialized with {\it tag}.
Buttons are aranged horizontally, from left to right. If WANT\_CANCEL\_BUTTON
is defined at compile time, a first button is automatically created, with
the label ``Cancel''.

\membersection{wxEnhDialogBox::GetCmd}

\func{wxButton *}{GetCmd}{\param{int }{n}}

Returns the identifier of the {\it n}th wxButton in the command area
(starting at 0).

\membersection{wxEnhDialogBox::SetPin}

\func{void}{SetPin}{\param{Bool }{flag}}

Set the pushpin to the given state. The state of the pushpin controls the way
the ::Show() method works. Usually, setting the pin to TRUE indicates an
error. Please note that this works even if you have compiled with
WANT\_CANCEL\_BUTTON.

\membersection{wxEnhDialogBox::Show}

\func{void}{Show}{\param{Bool }{show}, \param{Bool }{flag = FALSE}}

Dismiss or popup the dialog box. If {\it show} is FALSE, the dialog box
is dismissed only if the pushpin current state is FALSE. If {\it show}
is TRUE, the dialog box is popped, and the pushpin is initialized in the
state {\it flag}.

\membersection{wxEnhDialogBox::Fit}\label{wxenhdialogfit}

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

Fits the dialog box to its contents, and centres command buttons in the
command area. The status area is created when Fit is called, so do not
call SetStatus before fitting.


\section{\class{wxEvent}: wxObject}

An event is a structure holding information about an event passed to a
callback or member function. {\bf wxEvent} used to be a multipurpose
event object, and is now an abstract base class for events such
as \helpref{wxCommandEvent}{wxcommandevent} (for panel item commands)
and \helpref{wxMouseEvent}{wxmouseevent} (for mouse events on windows).

\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::eventClass}

\member{WXTYPE}{ eventClass}

The C++ class of the event, such as wxTYPE\_COMMAND\_EVENT.
A single class may have many `types'; it would be tedious to define
a new C++ class for each type of similar event.

\membersection{wxEvent::eventHandle}

\member{char *}{eventHandle}

Handle of an underlying windowing system event handle, such as
XEvent. Not guaranteed to be instantiated.

\membersection{wxEvent::eventObject}

\member{wxObject *}{eventObject}

The object (usually a window) that the event was generated from,
or should be sent to.

\membersection{wxEvent::eventType}

\member{WXTYPE}{ eventType}

The type of the event, such as wxEVENT\_TYPE\_BUTTON\_COMMAND.

\membersection{wxEvent::ReadEvent}

\func{pure virtual Bool}{ReadEvent}{\param{istream\&}{ stream}}

Reads the event from the given input stream.

\membersection{wxEvent::WriteEvent}

\func{pure virtual Bool}{WriteEvent}{\param{ostream\&}{ stream}}

Writes the event to the given output stream.

\section{\class{wxFont}: wxObject}\label{wxfont}

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{twocollist}
\twocolitem{Point size}{This is the standard way of referring to text size.}
\twocolitem{Family}{Supported families are:
  {\bf wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN}.
  {\bf wxMODERN} is a fixed pitch font; the others are either fixed or variable pitch.}
\twocolitem{Style}{The value can be {\bf wxNORMAL, wxSLANT} or {\bf wxITALIC}.}
\twocolitem{Weight}{The value can be {\bf wxNORMAL, wxLIGHT} or {\bf wxBOLD}.}
\twocolitem{Underlining}{The value can be TRUE or FALSE.}
\end{twocollist}

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}, \param{Bool}{ underline = FALSE}}

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.

Underlining only works under Windows 3 at present.

See also \helpref{wxDC::SetFont}{wxdcsetfont}, \helpref{wxDC::DrawText}{wxdcdrawtext}
and \helpref{wxDC::GetTextExtent}{wxdcgettextextent}.

All fonts are automatically added to the global pointer {\bf wxTheFontList}.
Call \helpref{wxFontList::FindOrCreateFont}{findorcreatefont} to return
a previously-created font if possible.

\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.

If you have to delete the font (for example, you are creating a lot of
them), then call \helpref{wxDC::SetFont}{wxdcsetfont} with a NULL argument
to ensure that the old font is restored, and the current font is selected
out of the device context.

\membersection{wxFont::GetFamily}

\func{int}{GetFamily}{\void}

Gets the font family. See \helpref{wxFont}{wxfont} for a list of valid
family identifiers.

\membersection{wxFont::GetPointSize}

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

Gets the point size.

\membersection{wxFont::GetStyle}

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

Gets the font style.  See \helpref{wxFont}{wxfont} for a list of valid
styles.

\membersection{wxFont::GetUnderlined}

\func{Bool}{GetUnderlined}{\void}

TRUE if the font is underlined.

\membersection{wxFont::GetWeight}

\func{int}{GetWeight}{\void}

Gets the font weight.   See \helpref{wxFont}{wxfont} for a list of valid
weight identifiers.

\section{\class{wxFontList}: wxList}\label{wxfontlist}

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

\membersection{wxFontList::wxFontList}

\func{void}{wxFontList}{\void}

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

\membersection{wxFontList::AddFont}

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

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

\membersection{wxFontList::FindOrCreateFont}\label{findorcreatefont}

\func{wxFont *}{FindOrCreateFont}{\param{int}{ point\_size}, \param{int}{ family}, \param{int}{ style}, \param{int}{ weight}, \param{Bool}{ underline = FALSE}}

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

\membersection{wxFontList::RemoveFont}

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

Used by wxWindows to remove a font from the list.

\section{\class{wxForm}: wxObject}\label{form}

\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, Revert and
Help 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. Pressing Help cause the
OnHelp member to be called, which by default does nothing. 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{twocollist}
\twocolitem{wxFORM\_DEFAULT}{Let wxWindows choose a suitable panel item.}
\twocolitem{wxFORM\_SINGLE\_LIST}{Use a single-selection listbox. Default for
string item with a one-of constraint.}
\twocolitem{wxFORM\_CHOICE}{Use a choice item.}
\twocolitem{wxFORM\_CHECKBOX}{Use a checkbox. Default for boolean item.}
\twocolitem{wxFORM\_TEXT}{Use a single-line text item. Default for floating
point item, and for string and integer items with no constraints.}
\twocolitem{wxFORM\_MULTITEXT}{Use a multi-line text item.}
\twocolitem{wxFORM\_RADIOBOX}{Use a radiobox with a one-of constraint.}
\twocolitem{wxFORM\_SLIDER}{Use a slider. Default for integer item with range
constraint.}
\end{twocollist}

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
\rtfsp{\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}{\param{int}{ useButtons = wxFORM\_BUTTON\_ALL},\\
  \param{int}{ placeButtons = wxFORM\_BUTTON\_AT\_TOP}}

Constructor. The value of {\it useButtons} determines which buttons are
automatically created, and must be a bit list of the following
identifiers:

\begin{itemize}
\item wxFORM\_BUTTON\_OK
\item wxFORM\_BUTTON\_CANCEL
\item wxFORM\_BUTTON\_HELP
\item wxFORM\_BUTTON\_UPDATE
\item wxFORM\_BUTTON\_REVERT
\item wxFORM\_BUTTON\_ALL
\end{itemize}

wxFORM\_BUTTON\_ALL is the same as specifying all buttons except
wxFORM\_BUTTON\_HELP.

{\it placeButtons} may be used to specify whether the form buttons are
placed the top or bottom of the form, and may be one of:

\begin{itemize}
\item wxFORM\_BUTTON\_AT\_TOP
\item wxFORM\_BUTTON\_AT\_BOTTOM
\end{itemize}

\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}\label{wxformadd}

\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::AssociatePanel}\label{wxformassociate}

\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::Delete}

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

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

\membersection{wxForm::FindItem}

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

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

\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::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::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{int}{ style = 0}, \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).
\rtfsp{\it style} may be wxHORIZONTAL or wxVERTICAL (for label orientation).
\rtfsp{\it help\_string} is 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{int}{ style = 0}, \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).
\rtfsp{\it style} may be wxHORIZONTAL or wxVERTICAL (for label orientation).
\rtfsp{\it help\_string} is 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{int}{ style = 0},
  \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).
\rtfsp{\it style} may be wxHORIZONTAL or wxVERTICAL (for label orientation).
\rtfsp{\it help\_string} is 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{int}{ style = 0}, \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).
\rtfsp{\it style} may be wxHORIZONTAL or wxVERTICAL (for label orientation).
\rtfsp{\it help\_string} is 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{int}{ style = 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).
\rtfsp{\it style} may be wxHORIZONTAL or wxVERTICAL (for label orientation).
\rtfsp{\it help\_string} is 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{wxFormItem: wxObject}}\label{wxformitem}

A form item is a data structure for representing a panel item (control, widget) in a form.
It is returned from {\bf wxMakeForm...} function and normally you will not need a handle
to it except to pass it to \helpref{wxForm::Add}{wxformadd}. However, you may wish
to get the actual panel item from the form item, for example to disable the panel item.
In which case, save a handle to the form item, then call (for
example) \helpref{wxFormItem::GetPanelItem}{wxformitemgetitem} {\it after} you
have associated the form and the panel or dialog box.

\membersection{wxFormItem::GetPanelItem}\label{wxformitemgetitem}

\func{wxItem *}{GetPanelItem}{\void}

Gets the panel item for this form item. Must only be called {\it after}\rtfsp
\helpref{wxForm::AssociatePanel}{wxformassociate} has been called.

\section{\class{wxFrame}: wxWindow}\label{wxframe}

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 \helpref{wxFrame::OnClose}{wxframeonclose} 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 the user manual.

A frame may contain the subwindows \helpref{wxCanvas}{wxcanvas}, \helpref{wxPanel}{wxpanel}
and \helpref{wxTextWindow}{wxtextwindow}.

\membersection{wxFrame::wxFrame}\label{constrframe}

\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{long}{ style = wxSDI $\|$ wxDEFAULT\_FRAME}, \param{char *}{name = ``frame"}}

Constructor.  The {\it parent} parameter can be NULL or an existing frame;
if an existing frame is used under Windows 3, the child frame is always on top
of the parent, and will be iconized when the parent is iconized.

If {\it title} is non-NULL, it is placed on the window frame.

The style parameter may be a combination of the following, using the bitwise `or' operator.

\begin{twocollist}
\twocolitem{wxICONIZE}{Display the frame iconized (minimized) (Windows only).}
\twocolitem{wxCAPTION}{Puts a caption on the frame (Windows and XView only).}
\twocolitem{wxDEFAULT\_FRAME}{Defined as {\bf (wxMINIMIZE\_BOX $\|$ wxMAXIMIZE\_BOX $\|$ wxTHICK\_FRAME $\|$ wxSYSTEM\_MENU $\|$ wxCAPTION)}.}
\twocolitem{wxMDI\_CHILD}{Specifies a Windows MDI (multiple document interface) child frame.}
\twocolitem{wxMDI\_PARENT}{Specifies a Windows MDI (multiple document interface) parent frame.}
\twocolitem{wxMINIMIZE}{Identical to {\bf wxICONIZE}.}
\twocolitem{wxMINIMIZE\_BOX}{Displays a minimize box on the frame (Windows and Motif only).}
\twocolitem{wxMAXIMIZE}{Displays the frame maximized (Windows only).}
\twocolitem{wxMAXIMIZE\_BOX}{Displays a maximize box on the frame (Windows and Motif only).}
\twocolitem{wxSDI}{Specifies a normal SDI (single document interface) frame.}
\twocolitem{wxSTAY\_ON\_TOP}{Stay on top of other windows (Windows only).}
\twocolitem{wxSYSTEM\_MENU}{Displays a system menu (Windows and Motif only).}
\twocolitem{wxTHICK\_FRAME}{Displays a thick frame around the window (Windows and Motif only).}
\twocolitem{wxRESIZE\_BORDER}{Displays a resizeable border around the window (Motif only).}
\twocolitem{wxTINY\_CAPTION\_HORIZ}{Under Windows 3.1, displays a small horizontal caption if USE\_ITSY\_BITSY is
set to 1 in wx\_setup.h and the Microsoft ItsyBitsy library has been compiled. Use instead of
wxCAPTION.}
\twocolitem{wxTINY\_CAPTION\_VERT}{Under Windows 3.1, displays a small vertical caption if USE\_ITSY\_BITSY is
set to 1 in wx\_setup.h and the Microsoft ItsyBitsy library has been compiled. Use instead of
wxCAPTION.}
\end{twocollist}

For Motif, the MWM (the Motif Window Manager) should be running for any styles to work
(otherwise all styles take effect).

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual windows.

\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::Command}

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

Simulate a menu command. {\it id} is the identifier for a menu item.

\membersection{wxFrame::Create}

\func{void}{Create}{\param{wxFrame *}{parent}, \param{char *}{title}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = wxSDI $\|$ wxDEFAULT\_FRAME}, \param{char *}{name = ``frame"}}

Used in two-step frame construction. See \helpref{wxFrame::wxFrame}{constrframe}
for further details.

\membersection{wxFrame::CreateStatusLine}\label{wxframecreatestatusline}

\func{void}{CreateStatusLine}{\param{int}{ number = 1}}

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.

The default is to create one field the width of the frame; specify a
value between 1 and 5 to create a multi-field status line.

See alo \helpref{wxFrame::SetStatusText}{wxframesetstatustext}.

\membersection{wxFrame::Fit}

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

Reize the frame to just fit around the subwindows. If a frame has only
one subwindow, that subwindow will be resized by the default \helpref{wxFrame::OnSize}{wxframeonsize}
member to fit inside the frame.

\membersection{wxFrame::GetTitle}\label{wxframegettitle}

\func{char *}{GetTitle}{\void}

Gets a temporary pointer to the frame title. See
\helpref{wxFrame::SetTitle}{wxframesettitle}.

\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::LoadAccelerators}

\func{void}{LoadAccelerators}{\param{char *}{resource}}

Loads keyboard accelerators for this frame (Windows only). Accelerator
tables map keystrokes onto control and menu identifiers, so the
programmer does not have to explicitly program this correspondence.

See the hello demo ({\tt hello.cc} and {\tt hello.rc}) for
an example of accelerator usage. This is a fragment from {\tt hello.rc}:

\begin{verbatim}
#define HELLO_LOAD_FILE  111

menus_accel ACCELERATORS
{

"^L", HELLO_LOAD_FILE

}
\end{verbatim}

\membersection{wxFrame::Maximize}

\func{void}{Maximize}{\param{Bool }{maximize}}

Maximizes the frame if {\it maximize} is TRUE, otherwise restores it
(Windows 3.1 only).

\membersection{wxFrame::OnClose}\label{wxframeonclose}

\func{Bool}{OnClose}{\void}

Sent to the frame when the user has tried to close the window using the
window manager (X) or system menu (Windows).  If TRUE is returned by
\rtfsp{\bf OnClose}, the frame will be deleted by the system, otherwise the
attempt will be ignored. Derive your own class to handle this message;
the default handler returns FALSE.

This member is a good place to delete other frames which are
conceptually or actually subframes of this frame, since if all frames
are not deleted, the application cannot exit. This is the top-level
\rtfsp{\bf OnClose} handler for the `hello' demo:

\begin{verbatim}
Bool MyFrame::OnClose(void)
{
  if (subframe)
    delete subframe;

  return TRUE;
}
\end{verbatim}

When quitting the application from inside the application, for example
from a menu item, call the frame's {\bf OnClose} member before deleting
the frame. wxWindows then causes the application to exit without further
ado. For example:

\begin{verbatim}
// Intercept menu commands
void MyFrame::OnMenuCommand(int id)
{
  switch (id)
  {
    ...
    case HELLO_QUIT:
    {
      OnClose();
      delete this;
      break;
    }
    ...
  }
}
\end{verbatim}

\membersection{wxFrame::OnMenuCommand}\label{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. For example:

\begin{verbatim}
// Intercept menu commands
void MyFrame::OnMenuCommand(int id)
{
  switch (id)
  {
    case HELLO_LOAD_FILE:
    {
      char *s = wxFileSelector("Load text file", NULL, NULL, NULL, "*.txt");
      if (s)
        frame->text_window->LoadFile(s);
      break;
    }
    case HELLO_QUIT:
    {
      OnClose();
      delete this;
      break;
    }
    case HELLO_PRINT_EPS:
    {
      wxPostScriptDC dc(NULL, TRUE);
      if (dc.Ok())
      {
        dc.StartDoc("Hello printout");
        dc.StartPage();
        Draw(dc, TRUE);
        dc.EndPage();
        dc.EndDoc();
      }
      break;
    }
    case HELLO_ABOUT:
    {
      (void)wxMessageBox("wxWindows GUI library demo", "About wxHello", wxOK|wxCENTRE);
      break;
    }
  }
}
\end{verbatim}

\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.

The default {\bf OnMenuSelect} member puts the menu item help string
on the status line, if a status line has been created.

This function is called under Windows 3 and Motif, but not XView.

\membersection{wxFrame::OnSize}\label{wxframeonsize}

\func{void}{OnSize}{\param{int}{ w}, \param{int}{ h}}

Called when the user or application resizes the frame. The parameters
give the total size of the frame. The default {\bf OnSize} member
looks for a single subwindow, and if one is found, resizes it to fit
inside the frame. Override this member if more complex behaviour
is required (for example, if there are several subwindows).

\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_MDIPARENTFRAME ICON icon1.ico
wxSTD_MDICHILDFRAME  ICON icon2.ico
\end{verbatim}

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

To assign an icon to all SDI frames, include a line similar to the
following:

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

See also \helpref{wxIcon}{wxicon}.

\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).

See also \helpref{wxMenuBar}{wxmenubar}, \helpref{wxMenu}{wxmenu}.

\membersection{wxFrame::SetStatusText}\label{wxframesetstatustext}

\func{void}{SetStatusText}{\param{char *}{ text}, \param{int}{ number = 0}}

Sets the status line text and redraws the status line. Use an empty (not NULL) string
to clear the status line. Optionally use {\it number} to specify a
field in the status line, starting from zero and consistent with the number
of fields specified in \helpref{wxFrame::CreateStatusLine}{wxframecreatestatusline}.

\membersection{wxFrame::SetTitle}\label{wxframesettitle}

\func{void}{SetTitle}{\param{char *}{ title}}

Sets the frame title. See \helpref{wxFrame::GetTitle}{wxframegettitle}.

\membersection{wxFrame::StatusLineExists}\label{wxframestatuslineexists}

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

Returns TRUE if the status line has previously been created.
See \helpref{wxFrame::CreateStatusLine}{wxframecreatestatusline}, \helpref{wxFrame::SetStatusText}{wxframesetstatustext}.

\section{\class{wxFunction}}\label{wxfunction}.

The type of a panel item callback function.

\membersection{wxFunction}

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

The type of a panel item callback function. The first parameter is a reference
to the object, and the second is a command event structure.
See \helpref{wxItem}{wxitem}, \helpref{wxCommandEvent}{wxcommandevent}.

\section{\class{wxIcon}: wxObject}\label{wxicon}

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
#include "aiai.xbm"
#endif
#ifdef wx_msw
  wxIcon *icon = new wxIcon("aiai");
#endif
#ifdef wx_x
  wxIcon *icon = new wxIcon(aiai_bits, aiai_width, aiai_height);
#endif
\end{verbatim}

See also \helpref{wxDC::DrawIcon}{wxdcdrawicon}, \helpref{wxBitmap}{wxbitmap}.

\membersection{wxIcon::wxIcon}

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

\func{void}{wxIcon}{\param{char}{ 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}\label{wxhashtable}

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.

See also \helpref{wxList}{wxlist}.

\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
description for \helpref{wxNode}{wxnode}. 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}\label{wxhelpinstance}

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}.

If you give TRUE to the constructor, you can use the native help system
where appropriate (currently under Windows only). Omit the file extension
to allow wxWindows to choose the appropriate file for the platform.

\membersection{wxHelpInstance::wxHelpInstance}

\func{void}{wxHelpInstance}{\param{Bool}{ native}}

Constructs a help instance object, but does not invoke wxHelp.
If {\it native} is TRUE, tries to use the native help system where
possible (Windows Help under Windows 3.1, wxHelp on other platforms).

\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.

You may omit the file extension, and in fact this is recommended if you
wish to support .xlp files under X and .hlp under Windows.

\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.
If using Windows Help, displays the file at the given context number.

\membersection{wxHelpInstance::DisplayContents}

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

If wxHelp is not running, runs wxHelp (or Windows Help) 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 (or Windows Help) is not running, runs wxHelp (or Windows
Help), 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 (wxHelp)
or the first topic is displayed (Windows Help).

\membersection{wxHelpInstance::LoadFile}

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

If wxHelp (or Windows Help) is not running, runs wxHelp (or Windows
Help), 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
(no effect if Windows Help is being used instead).

\membersection{wxHelpInstance::Quit}

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

If wxHelp is running, quits wxHelp by disconnecting (no effect for Windows
Help).

\section{\class{wxIntPoint}: wxObject}\label{wxintpoint}

A {\bf wxIntPoint} is a useful data structure for graphics operations.
It contains integer point {\it x} and {\it y} members.
See also \helpref{wxPoint}{wxpoint} for a floating point version.

\membersection{wxIntPoint::wxIntPoint}

\func{void}{wxIntPoint}{\void}

\func{void}{wxIntPoint}{\param{int}{ x}, \param{int}{ y}}

Create a point.

\member{int}{ x}

\member{int}{ y}

Members of the {\bf wxIntPoint} object.

\section{\class{wxItem}: wxWindow}\label{wxitem}

This is the base class for any widget or control which can be placed on a panel
or dialog box.

The following styles may be used for any panel item:

\begin{twocollist}
\twocolitem{wxFIXED\_LENGTH}{The label of the item is created with a width
proportional to the length of the label string, regardless of proportional
font in use. This allows alignment of items if all items are given labels
of the same length.}
\end{twocollist}

\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::Command}

\func{void}{Command}{\param{wxCommandEvent}{ event}}

Simulate the effect of the user issuing a command to the item. See \helpref{wxCommandEvent}{wxcommandevent}.

\membersection{wxItem::GetBackgroundColour}

\func{wxColour *}{GetBackgroundColour}{\void}

Gets the item background colour (Motif only).

\membersection{wxItem::GetButtonColour}

\func{wxColour *}{GetButtonColour}{\void}

Gets the item button colour (Motif only).

\membersection{wxItem::GetLabelColour}

\func{wxColour *}{GetLabelColour}{\void}

Gets the item label colour (Motif only).

\membersection{wxItem::GetLabel}

\func{char *}{GetLabel}{\void}

Gets a temporary pointer to the item's label.

\membersection{wxItem::SetBackgroundColour}

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

Sets the item background colour (Motif only).

\membersection{wxItem::SetButtonColour}

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

Sets the item button's colour (Motif only).

\membersection{wxItem::SetLabel}

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

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

\membersection{wxItem::SetLabelColour}

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

Sets the item label's colour (Motif only).

\section{\class{wxKeyEvent}: wxEvent}\label{wxkeyevent}

This event class contains information about key events. See \helpref{wxCanvas::OnChar}{wxcanvasonchar}.

\membersection{wxKeyEvent::controlDown}

\member{Bool}{ controlDown}

TRUE if control is pressed down.

\membersection{wxKeyEvent::keyCode}

\member{long}{ keyCode}

Virtual keycode.

\membersection{wxKeyEvent::shiftDown}

\member{Bool}{ shiftDown}

TRUE if shift is pressed down.

\membersection{wxKeyEvent::wxKeyEvent}

\func{void}{wxKeyEvent}{\param{WXTYPE}{ keyEventType}}

Constructor. Currently, the only valid event type is wxEVENT\_TYPE\_CHAR.

\membersection{wxKeyEvent::ControlDown}

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

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

\membersection{wxKeyEvent::KeyCode}

\func{long}{KeyCode}{\void}

Returns the virtual key code. ASCII events return normal ASCII values,
while non-ASCII events return values such as {\bf WXK\_LEFT} for the
left cursor key. See {\tt common.h} for a full list of the virtual key codes.

\membersection{wxKeyEvent::Position}

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

Obtains the position at which the key was pressed.

\membersection{wxKeyEvent::ShiftDown}

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

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

\section{\class{wxList}: wxObject}\label{wxlist}

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}{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}{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
\rtfsp{\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{wxNode *}{Member}{\param{wxObject *}{object}}

Returns the node associated with {\it object} if it is in the list, NULL otherwise.

\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}\label{wxlistbox}

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).

Please note that under XView, the height of a listbox cannot be set
accurately, since internally, the number of rows must be used to set
the height. So it is unlikely that the value returned by {\it GetSize} will
be the same as passed to {\it SetSize}.

See also \helpref{wxChoice}{wxchoice}.

\membersection{wxListBox::wxListBox}\label{constrlistbox}

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

Constructor, for deriving classes.

\func{void}{wxListBox}{\param{wxPanel *}{parent}, \param{wxFunction}{ func}, \param{char *}{label},\\
  \param{Bool}{ multiple\_selection = wxSINGLE}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{long}{ style = 0}, \param{char *}{name = ``listBox"}}

Constructor, creating and showing a 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.

If {\it label} is non-NULL, it will be used as the listbox label.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

If {\it width} or {\it height} are omitted (or are less than zero), an
appropriate size will be used for the list box.

{\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 a bit list of some of the following:

\begin{twocollist}
\twocolitem{wxSINGLE}{Single-selection list.}
\twocolitem{wxMULTIPLE}{Multiple-selection list.}
\twocolitem{wxEXTENDED}{Extended-selection list (Motif only).}
\twocolitem{wxNEEDED\_SB}{Create scrollbars if needed.}
\twocolitem{wxALWAYS\_SB}{Create scrollbars immediately.}
\end{twocollist}

{\it style} is a bit list of some of the following:

\begin{twocollist}
\twocolitem{wxNEEDED\_SB}{Create scrollbars if needed.}
\twocolitem{wxALWAYS\_SB}{Create scrollbars immediately.}
\twocolitem{wxHSCROLL}{Create horizontal scrollbar if contents are two wide (Windows only).}
\end{twocollist}

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual listboxes.

\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::Create}

\func{Bool}{Create}{\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[]},\\
  \param{long}{ style = 0}, \param{char *}{name = ``listBox"}}

Creates the listbox for two-step construction. Derived classes
should call or replace this function. See \helpref{wxListBox::wxListBox}{constrlistbox}
for further details.

\membersection{wxListBox::Delete}

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

Delete the nth element in the list box.

\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::GetClientData}

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

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

\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::Selected}

\func{Bool}{Selected}{\param{int}{ n}}

Returns TRUE if the given item is selected, FALSE otherwise.

\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::SetFirstItem}

\func{void}{SetFirstItem}{\param{int}{ n}}
\func{void}{SetFirstItem}{\param{char *}{item}}

Set the specified item to be the first visible item (not XView).

\membersection{wxListBox::SetSelection}

\func{void}{SetSelection}{\param{int}{ n}, \param{Bool}{select = TRUE}}

Selects or deselects the given item.

\membersection{wxListBox::SetStringSelection}

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

Sets the choice by passing the desired string.

\membersection{wxListBox::GetString}

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

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

\section{\class{wxMemoryDC}: wxObject}\label{wxmemorydc}

A memory device context provides a means to draw graphics onto a bitmap.

A bitmap must be selected into the new memory DC before it may be used
for anything.  Typical usage is as follows:

\begin{verbatim}
  // Create a memory DC
  wxMemoryDC temp_dc;
  temp_dc.SelectObject(test_bitmap);

  // We can now draw into the memory DC...
  // Copy from this DC to another DC.
  old_dc.Blit(250, 50, BITMAP_WIDTH, BITMAP_HEIGHT, temp_dc, 0, 0);
\end{verbatim}

Note that the memory DC {\it must} be deleted before a bitmap
can be reselected into another memory DC.

See also \helpref{wxBitmap}{wxbitmap}, \helpref{wxDC}{wxdc}, \helpref{wxCanvasDC}{wxcanvasdc}.

\membersection{wxMemoryDC::wxMemoryDC}

\func{void}{wxMemoryDC}{\void}

Constructs a new memory device context.

\func{void}{wxMemoryDC}{\param{wxCanvasDC *}{oldDC}}

Constructs a new memory device context with similar attributes to the
given canvas device context.

Use the {\it Ok} member to test whether the constructor was successful
in creating a useable device context. Don't forget to select a bitmap
into the DC before drawing on it.

\membersection{wxMemoryDC::SelectObject}

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

Selects the given bitmap into the device context, to use as the memory
bitmap. Selecting the bitmap into a memory DC allows you to draw into
the DC (and therefore the bitmap) and also to use {\bf Blit} to copy
the bitmap to a canvas. For this purpose, you may find \helpref{wxDC::DrawIcon}{wxdcdrawicon}
easier to use instead.

If the argument is NULL, the current bitmap is selected out of the device
context, and the original bitmap restored, allowing the current bitmap to
be destroyed safely.

\section{\class{wxMenu}: wxItem}\label{wxmenu}

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).  Menus may be used to construct either menu bars or popup menus.

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.

See also \helpref{wxFrame::OnMenuCommand}{onmenucommand} and \helpref{wxWindow::PopupMenu}{popupmenu}.

\membersection{wxMenu::wxMenu}

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

The first argument is presently ignored. The second argument is 
a callback function if the menu is used as a popup using \helpref{wxWindow::PopupMenu}{popupmenu}.

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

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

Destructor, destroying the menu.

\membersection{wxMenu::Append}\label{wxmenuappend}

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

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

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). From version 1.50k, this can be used dynamically, i.e. after initial
creation of a menu or menubar.

Each form can take an optional help string, which can be accessed using
\rtfsp{\bf wxMenu::GetHelpString}. The default {\bf wxFrame::OnMenuSelect} member
uses this help string to give help on the menu item currently under the
cursor.

See the {\tt hello.cc} demo for an example of using {\bf Append} dynamically
to implement a file history facility. See also \helpref{wxMenu::SetLabel}{wxmenusetlabel}.

\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::Check}

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

If {\it flag} is TRUE, checks the given menu item, else unchecks it.
Windows 3, Motif.

\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). Windows 3, Motif, XView.

\membersection{wxMenu::FindItem}

\func{int}{FindItem}{\param{char *}{itemString}}

Finds the menu item id for a menu item string, or -1 if none found.
Any special menu codes are stripped out of source and target strings
before matching.

\membersection{wxMenu::FindItemForId}

\func{wxMenuItem *}{FindItemForId}{\param{int}{ itemId}}

Finds the menu item object associated with the given menu item identifier,
returning NULL if not found.

\membersection{wxMenu::GetHelpString}

\func{char *}{GetHelpString}{\param{int}{ itemId}}

Gets a temporary pointer to the help string associated with the menu
item identifer (or NULL if there is no help string or the item was not
found).

\membersection{wxMenu::GetLabel}

\func{char *}{GetLabel}{\param{int}{ id}}

Gets a temporary pointer to the label of the given menu item; copy this for
long-term use. {\it id} is the identifier given to \helpref{wxMenu::Append}{wxmenuappend}.

\membersection{wxMenu::GetTitle}

\func{char *}{GetTitle}{\void}

Gets a temporary pointer to the title of the menu.

\membersection{wxMenu::SetHelpString}

\func{void}{SetHelpString}{\param{int}{ itemId}, \param{char *}{helpString}}

Sets the help string associated with the menu item identifer.

\membersection{wxMenu::SetLabel}\label{wxmenusetlabel}

\func{void}{SetLabel}{\param{int}{ id}, \param{char *}{label}}

Sets the label of the given menu item (using the identifier used to
append the item to the menu).

See the {\tt hello.cc} demo for an example of using this command to
implement a file history facility. See also \helpref{wxMenu::Append}{wxmenuappend}.


\membersection{wxMenu::SetTitle}

\func{void}{SetTitle}{\param{char *}{title}}

Sets the title of the menu.


\section{\class{wxMenuBar}: wxItem}\label{wxmenubar}

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::Check}

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

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

\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). Windows 3, Motif. Only use this when the menu bar has been
associated with a frame; otherwise, use the wxMenu equivalent call.

\membersection{wxMenuBar::EnableTop}

\func{void}{EnableTop}{\param{int}{ pos}, \param{Bool}{ flag}}

If {\it flag} is TRUE, enables the menu at the given position, else
disables it (greys it). Only use this when the menu bar has been
associated with a frame.

\membersection{wxMenuBar::FindMenuItem}

\func{int}{FindMenuItem}{\param{char *}{menuString}, \param{char *}{itemString}}

Finds the menu item id for a menu name/menu item string pair, or -1 if none found.
Any special menu codes are stripped out of source and target strings
before matching.

\membersection{wxMenuBar::FindItemById}

\func{wxMenuItem *}{FindItemById}{\param{int}{ itemId}}

Finds the menu item object associated with the given menu item identifier,
returning NULL if not found.

\membersection{wxMenuBar::GetHelpString}

\func{char *}{GetHelpString}{\param{int}{ itemId}}

Gets the help string associated with the menu item identifer (or NULL if
there is no help string or the item was not found).

\membersection{wxMenuBar::GetLabel}

\func{char *}{GetLabel}{\param{int}{ itemId}}

Returns a temporary pointer to the label of the given menu item. Use only
after the menubar has been associated with a frame with {\bf
wxFrame::SetMenuBar}.

\membersection{wxMenuBar::GetLabelTop}

\func{char *}{GetLabelTop}{\param{int}{ pos}}

Returns a temporary pointer to the label of the given top-level menu. {\it
pos} is the position of a menu on the menu bar. Use only after the
menubar has been associated with a frame with {\bf wxFrame::SetMenuBar}.

\membersection{wxMenuBar::SetHelpString}

\func{void}{SetHelpString}{\param{int}{ itemId}, \param{char *}{helpString}}

Sets the help string associated with the menu item identifer.

\membersection{wxMenuBar::SetLabel}

\func{void}{SetLabel}{\param{int}{ itemId}, \param{char *}{label}}

Sets the label of the given menu item. Use only after the menubar
has been associated with a frame with {\bf wxFrame::SetMenuBar}.

\membersection{wxMenuBar::SetLabelTop}

\func{void}{SetLabelTop}{\param{int}{ pos}, \param{char *}{label}}

Sets the label of the given top-level menu. {\it pos} is the position of
a menu on the menu bar. Use only after the menubar has been associated
with a frame with {\bf wxFrame::SetMenuBar}.

\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}\label{constrmessage}

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

Constructor, used for deriving classes.

\func{void}{wxMessage}{\param{wxPanel *}{panel}, \param{char *}{message}, \param{int }{x = -1}, \param{int }{y = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``message"}}

Creates and displays a simple text message. {\it message} is the initial
value of the message.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual message items.

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

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

Destroys the message.

\membersection{wxMessage::Create}

\func{Bool}{Create}{\param{wxPanel *}{panel}, \param{char *}{message}, \param{int }{x = -1}, \param{int }{y = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``message"}}

Creates the listbox for two-step construction. Derived classes
should call or replace this function. See \helpref{wxMessage::wxMessage}{constrmessage}
for further details.

\section{\class{wxMetaFile}: wxObject}\label{wxmetafile}

A {\bf 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}{\param{char *}{filename = NULL}}

Constructor. If a filename is given, the Windows disk metafile is
read in. Check whether this was performed successfully by
using the \helpref{wxMetaFile::Ok}{wxmetafileok} member.

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

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

Destructor.

\membersection{wxMetaFile::Ok}\label{wxmetafileok}

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

Returns TRUE if the metafile is valid.

\membersection{wxMetaFile::Play}\label{wxmetafileplay}

\func{Bool}{Play}{\param{wxDC *}{dc}}

Plays the metafile into the given device context, returning
TRUE if successful.

\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.

Below is a example of metafle, metafile device context and clipboard use
from the {\tt hello.cc} example. Note the way the metafile dimensions
are passed to the clipboard, making use of the device context's ability
to keep track of the maximum extent of drawing commands.

\begin{verbatim}
  wxMetaFileDC dc;
  if (dc.Ok())
  {
    Draw(dc, FALSE);
    wxMetaFile *mf = dc.Close();
    if (mf)
    {
      Bool success = mf->SetClipboard((int)(dc.MaxX() + 10), (int)(dc.MaxY() + 10));
      delete mf;
    }
  }
\end{verbatim}

\section{\class{wxMetaFileDC}: wxDC}\label{wxmetafiledc}

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
\rtfsp{\bf wxDC}. The \helpref{wxMetaFileDC::Close}{wxmetafiledcclose} 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}{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).

Note that a metafile saved to disk is in standard Windows metafile format,
and cannot be imported into most applications. To make it importable,
call the function \helpref{::wxMakeMetaFilePlaceable}{wxmakemetafileplaceable} after
closing your disk-based metafile device context.

\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}\label{wxmetafiledcclose}

\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{wxMouseEvent}: wxEvent}\label{wxmouseevent}

This event class contains information about mouse events, particularly
events received by canvases. See \helpref{wxCanvas::OnEvent}{wxcanvasonevent}.

\membersection{wxMouseEvent::controlDown}

\member{Bool}{ controlDown}

TRUE if control key is pressed down.

\membersection{wxMouseEvent::leftDown}

\member{Bool}{ leftDown}

TRUE if the left mouse button is currently pressed down.

\membersection{wxMouseEvent::middleDown}

\member{Bool}{ middleDown}

TRUE if the middle mouse button is currently pressed down.

\membersection{wxMouseEvent::rightDown}

\member{Bool}{ rightDown}

TRUE if the right mouse button is currently pressed down.

\membersection{wxMouseEvent::leftDown}

\member{Bool}{ leftDown}

TRUE if the left mouse button is currently pressed down.

\membersection{wxMouseEvent::shiftDown}

\member{Bool}{ shiftDown}

TRUE if shift is pressed down.

\membersection{wxMouseEvent::x}

\member{float}{ x}

X-coordinate of the event.

\membersection{wxMouseEvent::y}

\member{float}{ y}

Y-coordinate of the event.

\membersection{wxMouseEvent::wxMouseEvent}

\func{void}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType}}

Constructor. Valid event types are:

\begin{itemize}
\item {\bf wxEVENT\_TYPE\_ENTER\_WINDOW}
\item {\bf wxEVENT\_TYPE\_LEAVE\_WINDOW}
\item {\bf wxEVENT\_TYPE\_LEFT\_DOWN}
\item {\bf wxEVENT\_TYPE\_LEFT\_UP}
\item {\bf wxEVENT\_TYPE\_LEFT\_DCLICK}
\item {\bf wxEVENT\_TYPE\_MIDDLE\_DOWN}
\item {\bf wxEVENT\_TYPE\_MIDDLE\_UP}
\item {\bf wxEVENT\_TYPE\_MIDDLE\_DCLICK}
\item {\bf wxEVENT\_TYPE\_RIGHT\_DOWN}
\item {\bf wxEVENT\_TYPE\_RIGHT\_UP}
\item {\bf wxEVENT\_TYPE\_RIGHT\_DCLICK}
\item {\bf wxEVENT\_TYPE\_MOTION}
\end{itemize}

\membersection{wxMouseEvent::Button}

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

Returns TRUE if the identified mouse button is changing state. Valid
values of {\it button} are 1, 2 or 3 for left, middle and right
buttons respectively.

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

\membersection{wxMouseEvent::ButtonDClick}\label{buttondclick}

\func{Bool}{ButtonDClick}{\param{int}{ but = -1}}

If the argument is omitted, this returns TRUE if the event was a mouse
double click event. Otherwise the argument specifies which double click event
was generated (1, 2 or 3 for left, middle and right buttons respectively).

Under Windows 3.1, a double click always follows a down-up sequence. On
the other supported platforms (WIN32, Motif, but not XView) the double click
event occurs on its own. See also \helpref{wxCanvas::AllowDoubleClick}{allowdoubleclick}.

\membersection{wxMouseEvent::ButtonDown}

\func{Bool}{ButtonDown}{\param{int}{ but = -1}}

If the argument is omitted, this returns TRUE if the event was a mouse
button down event. Otherwise the argument specifies which button-down event
was generated (1, 2 or 3 for left, middle and right buttons respectively).

\membersection{wxMouseEvent::ButtonUp}

\func{Bool}{ButtonUp}{\param{int}{ but = -1}}

If the argument is omitted, this returns TRUE if the event was a mouse
button up event. Otherwise the argument specifies which button-up event
was generated (1, 2 or 3 for left, middle and right buttons respectively).

\membersection{wxMouseEvent::ControlDown}

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

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

\membersection{wxMouseEvent::Dragging}

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

Returns TRUE if this was a dragging event (motion while a button is depressed).

\membersection{wxMouseEvent::Entering}\label{entering}

\func{Bool}{Entering}{\void}

Returns TRUE if the mouse was entering the canvas (Windows 3.1, WIN32 and Motif).

See also \helpref{wxMouseEvent::Leaving}{leaving}.

\membersection{wxMouseEvent::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{wxMouseEvent::Leaving}\label{leaving}

\func{Bool}{Leaving}{\void}

Returns TRUE if the mouse was leaving the canvas (Windows 3.1, WIN32 and Motif).

See also \helpref{wxMouseEvent::Entering}{entering}.

\membersection{wxMouseEvent::LeftDown}

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

Returns TRUE if the left mouse button changed to down.

\membersection{wxMouseEvent::LeftIsDown}

\func{Bool}{LeftIsDown}{\void}

Returns TRUE if the left mouse button is currently down, independent
of the current event type.

\membersection{wxMouseEvent::LeftUp}

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

Returns TRUE if the left mouse button changed to up.

\membersection{wxMouseEvent::MiddleDown}

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

Returns TRUE if the middle mouse button changed to down.

\membersection{wxMouseEvent::MiddleIsDown}

\func{Bool}{MiddleIsDown}{\void}

Returns TRUE if the middle mouse button is currently down, independent
of the current event type.

\membersection{wxMouseEvent::MiddleUp}

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

Returns TRUE if the middle mouse button changed to up.

\membersection{wxMouseEvent::Moving}

\func{Bool}{Moving}{\void}

Returns TRUE if this was a motion event (no buttons depressed).

\membersection{wxMouseEvent::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
\rtfsp{\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{wxMouseEvent::RightDown}

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

Returns TRUE if the right mouse button changed to down.

\membersection{wxMouseEvent::RightIsDown}

\func{Bool}{RightIsDown}{\void}

Returns TRUE if the right mouse button is currently down, independent
of the current event type.

\membersection{wxMouseEvent::RightUp}

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

Returns TRUE if the right mouse button changed to up.


\membersection{wxMouseEvent::ShiftDown}

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

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

\section{\class{wxMultiText}: wxText}

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

If the {\it style} parameter is wxHSCROLL, a horizontal scrollbar
will be displayed. If wxHSCROLL is omitted, only a vertical
scrollbar is displayed, and lines will be wrapped. This parameter
is ignored under XView.

\membersection{wxMultiText::GetValue}

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

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

The first form gets a temporary pointer to the current value; copy this for
long-term use. 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}\label{wxnode}

A node structure used in linked lists (see \helpref{wxList}{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.

\membersection{wxObject::\_\_type}\label{objecttype}

\member{WXTYPE}{ \_\_type}

Data member used for storing dynamic type information. Most wxWindows
classes set this member to an appropriate type, which may be overridden
in derived classes. Optionally set this in your constructor. The type
may be checked using \helpref{::wxSubType}{wxsubtype}.

Note the double underscore prefixing this name, in order to minimize clashes
with application code. There is no accessor function for this member, and
its scope is public.

See also \helpref{wxTypeTree}{wxtypetree}.

\section{\class{wxPanel}: wxWindow}\label{wxpanel}

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}\label{constrpanel}

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

Constructor, for deriving classes.

\func{void}{wxPanel}{\param{wxFrame *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``panel"}}

\func{void}{wxPanel}{\param{wxPanel *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``panel"}}

Constructor.

The parameters {\it x}, {\it y}, {\it width} and {\it height} can be
omitted on construction if the position and size will later be set (for
example by a application frame's {\bf OnSize} callback, or if there is
only one subwindow for the frame, in which case the subwindow fills the
frame).

The style parameter may be a combination of the following, using the bitwise `or' operator.

\begin{twocollist}
\twocolitem{wxABSOLUTE\_POSITIONING}{A hint to the windowing system not to try native
Windowing system layout (Motif only). {\it This is now obsolete.}}
\twocolitem{wxBORDER}{Draws a thin border around the panel.}
\twocolitem{wxVSCROLL}{Gives the dialog box a vertical scrollbar (XView only).}
\end{twocollist}

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual panels.

The parent window may be a panel in Motif and Windows, but not XView.

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

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

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

\membersection{wxPanel::Create}

\func{void}{Create}{\param{wxFrame *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1}, \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = 0}, \param{char *}{name = ``panel"}}

Used in two-step panel construction. See \helpref{wxPanel::wxPanel}{constrpanel}
for further details.

\membersection{wxPanel::Fit}

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

Resize the panel to just fit around the panel items. Also works for dialog boxes.

\membersection{wxPanel::GetButtonFont}

\func{wxFont *}{GetButtonFont}{\void}

Get the current font for drawing panel item values.

\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::GetDefaultItem}\label{wxpanelgetdefaultitem}

\func{wxButton *}{GetDefaultItem}{\void}

Retrieves the default button, previously set with \helpref{wxButton::SetDefault}{wxbuttonsetdefault}.

\membersection{wxPanel::GetHorizontalSpacing}

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

Gets the horizontal spacing for placing items on a panel.

\membersection{wxPanel::GetLabelFont}

\func{wxFont *}{GetLabelFont}{\void}

Get the current font for drawing panel item labels.

\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::OnDefaultAction}\label{wxpanelondefaultaction}

\func{void}{OnDefaultAction}{\param{wxItem *}{item}}

Called when the user initiates the default action for a panel or
dialog box, for example by double clicking on a listbox. {\it item}
is the panel item which caused the default action.


The default behaviour for this member is to retrieve the default button
for the panel, and send it a command event, as if the user had clicked
on the button. This gives default listbox double-click behaviour under
Motif and Windows 3. The default code is as follows:

\begin{verbatim}
void wxbPanel::OnDefaultAction(wxItem *initiatingItem)
{
  wxButton *but = GetDefaultItem();
  if (but)
  {
    wxCommandEvent event(wxEVENT_TYPE_BUTTON_COMMAND);
    but->Command(event);
  }
}
\end{verbatim}

\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::SetButtonFont}

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

Specify the font for drawing panel item values (not XView).

\membersection{wxPanel::SetLabelFont}

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

Specify the font for drawing panel item labels (not XView).

\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{\class{wxPathList}: wxList}\label{wxpathlist}

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 \helpref{wxPenList}{wxpenlist}.

\membersection{wxPen::wxPen}\label{wxpen}

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

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

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

Constructs a pen, uninitialized, 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.

If you have to delete the pen (for example, you are creating a lot of
them), then call \helpref{wxDC::SetPen}{wxdcsetpen} with a NULL argument
to ensure that the old pen is restored, and the current pen is selected
out of the device context.

\membersection{wxPen::GetCap}

\func{int}{GetCap}{\void}

Returns the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
\rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.

\membersection{wxPen::GetColour}

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

Returns a reference to the pen colour.

\membersection{wxPen::GetJoin}

\func{int}{GetJoin}{\void}

Returns the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
\rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.

\membersection{wxPen::GetStipple}

\func{wxBitmap *}{GetStipple}{\void}

Gets the stipple bitmap.

\membersection{wxPen::GetStyle}

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

Returns the pen style.

\membersection{wxPen::GetWidth}

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

Returns the pen width.

\membersection{wxPen::SetCap}

\func{void}{SetCap}{\param{int}{cap\_style}}

Sets the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
\rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.

\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::SetJoin}

\func{void}{SetJoin}{\param{int}{join\_style}}

Sets the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
\rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.

\membersection{wxPen::SetStipple}

\func{void}{SetStipple}{\param{wxBitmap *}{ stipple}}

Sets the bitmap for stippling.

\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}\label{wxpenlist}

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}\label{wxpoint}

A {\bf wxPoint} is a useful data structure for graphics operations.
It simply contains floating point {\it x} and {\it y} members.
See also \helpref{wxIntPoint}{wxintpoint} for an integer version.

\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{wxPostScriptDC}: wxDC}\label{wxpostscriptdc}

This defines the wxWindows Encapsulated PostScript device context,
which can write PostScript files on any platform. See \helpref{wxDC}{wxdc} for
descriptions of the member functions.

\membersection{wxPostScriptDC::wxPostScriptDC}

\func{void}{wxPostScriptDC}{\param{char *}{output}, \param{Bool }{interactive = TRUE}}

Constructor. {\it output} is an optional file for printing to, and if
\rtfsp{\it interactive} is TRUE a dialog box will be displayed for adjusting
various parameters.

Use the {\it Ok} member to test whether the constructor was successful
in creating a useable device context.

See \helpref{Printer settings}{printersettings} for functions to set and
get PostScript printing settings.

\section{\class{wxPrinterDC}: wxDC}\label{wxprinterdc}

A printer device context is specific to Windows, and allows access to
any printer with a Windows driver. See \helpref{wxDC}{wxdc} for further information
on device contexts, and \helpref{wxDC::GetSize}{wxdcgetsize} for advice on
achieving the correct scaling for the page.

\membersection{wxPrinterDC::wxPrinterDC}

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

Constructor.  With three NULLs, the default printer dialog is
displayed. {\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.

\section{\class{wxRadioBox}: wxItem}\label{wxradiobox}

A radio box item is used to select one of number of mutually exclusive
choices.  It is displayed as a vertical column or horizontal row of
labelled buttons.

\membersection{wxRadioBox::wxRadioBox}\label{constrradiobox}

\func{void}{wxRadioBox}{\void}

Constructor, for use by derived classes.

\func{void}{wxRadioBox}{\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[]}, \param{int}{ majorDim = 0}, \param{long}{ style = 0}, \param{char *}{name = ``radioBox"}}

\func{void}{wxRadioBox}{\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{wxBitmap *}{choices[]}, \param{int}{ majorDim = 0}, \param{long}{ style = 0}, \param{char *}{name = ``radioBox"}}

Constructor, creating and showing a radiobox.

{\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.

If {\it label} is non-NULL, it will be used to label the radiobox.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

If {\it width} or {\it height} are omitted (or are less than zero), an
appropriate size will be used for the radiobox.

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

{\it majorDim} specifies the number of rows for a two-dimensional
radiobox.

{\it style} specifies a bitwise-or list of styles (none so far).

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual radioboxes.

\membersection{wxRadioBox::\destruct{wxRadioBox}}

\func{void}{\destruct{wxRadioBox}}{\void}

Destructor, destroying the radiobox item.

\membersection{wxRadioBox::Create}

\func{Bool}{Create}{\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[]}, \param{int}{ majorDim = 0}, \param{long}{ style = 0}, \param{char *}{name = ``radioBox"}}

\func{Bool}{Create}{\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{wxBitmap *}{choices[]}, \param{int}{ majorDim = 0}, \param{long}{ style = 0}, \param{char *}{name = ``radioBox"}}

Creates the choice for two-step construction. Derived classes
should call or replace this function. See \helpref{wxRadioBox::wxRadioBox}{constrradiobox}
for further details.

\membersection{wxRadioBox::Enable}

\func{void}{Enable}{\param{Bool}{ enable}}

Enables or disables the entire radiobox.

\func{void}{Enable}{\param{int}{ n}, \param{Bool}{ enable}}

Enables or disables an individual button in the radiobox (does nothing
in XView).

\membersection{wxRadioBox::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{wxRadioBox::GetSelection}

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

Gets the id (position) of the selected string.

\membersection{wxRadioBox::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{wxRadioBox::Number}

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

Returns the number of choices in the radiobox.

\membersection{wxRadioBox::SetSelection}

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

Sets the choice by passing the desired string position.

\membersection{wxRadioBox::SetStringSelection}

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

Sets the choice by passing the desired string.

\membersection{wxRadioBox::Show}

\func{void}{Show}{\param{int }{item}, \param{Bool}{ show}}

Shows or hides individual radio box controls.

\membersection{wxRadioBox::GetString}

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

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

\section{\class{wxServer}: wxIPCObject}\label{wxserver}

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 the chapter on IPC in the user manual.}

\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}\label{wxserveronacceptconnection}

\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}\label{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.

\membersection{wxSlider::wxSlider}\label{constrslider}

\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}, \param{long}{ style = 0}, \param{char *}{name = ``slider"}}

Constructor, creating and showing a horizontal slider.

{\it func} may be NULL; otherwise it is used as the callback for the
slider.  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.

If {\it label} is non-NULL, it will be used to label the slider.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

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

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual sliders.

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

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

Destructor, destroying the slider.

\membersection{wxSlider::Create}

\func{void}{Create}{\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}, \param{long}{ style = 0}, \param{char *}{name = ``slider"}}

Used for two-step slider construction. See \helpref{wxSlider::wxSlider}{constrslider}
for further details.

\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}\label{wxstringlist}

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
\rtfsp{\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}

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

The callback function specified for the text item will be called
for the following events:

\begin{itemize}
\item wxEVENT\_TYPE\_TEXT\_COMMAND (text has changed)
\item wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (enter has been pressed:
if the wxPROCESS\_ENTER style is used)
\item under Windows, wxEVENT\_TYPE\_SET\_FOCUS, wxEVENT\_TYPE\_KILL\_FOCUS when
the focus changes.
\end{itemize}

\membersection{wxText::wxText}\label{constrtext}

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

Constructor, for deriving classes.

\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},\\
  \param{long}{ style = 0}, \param{char *}{name = ``text"}}

Constructor, creating and showing a text item with the given string
value. 

{\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.

If {\it label} is non-NULL, it will be used to label the text item.

The parameters {\it x} and {\it y} are used to specify an absolute
position, or a position after the previous panel item if omitted or
default.

If {\it width} or {\it height} are omitted (or are less than zero), an
appropriate size will be used for the item.

if {\it style} is wxPROCESS\_ENTER, the callback function will
receive the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND. Note
that this will break tab traversal for this panel item under
Windows.

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual text items.

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

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

Destructor, destroying the text item.

\membersection{wxText::Create}

\func{Bool}{Create}{\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},\\
  \param{long}{ style = 0}, \param{char *}{name = ``text"}}

Creates the text item for two-step construction. Derived classes
should call or replace this function. See \helpref{wxText::wxText}{constrtext}
for further details.

\membersection{wxText::GetValue}

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

Gets a pointer to the current value. Copy this for long-term use.

\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}\label{wxtextwindow}

A text window is a subwindow of a frame, offering some basic ability
to display scrolling text. Editing is possible under all platforms,
but if editing is required under Windows, the {\bf wxNATIVE\_IMPL} style
should be included. This is because the default implementation is
a read-only text window that can display more than the 64K or so
of text allowed using the standard edit control.

Some manipulation functions take integer positions, starting from zero.

Many of these functions are currently platform-specific, and have yet
to be fully implemented or tested.

\membersection{wxTextWindow::wxTextWindow}\label{constrtextwindow}

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

Constructor, for deriving classes.

\func{void}{wxTextWindow}{\param{wxFrame *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1}, \param{long}{ style = 0}, \param{char *}{name = ``textWindow"}}

Constructor.

The parameters {\it x}, {\it y}, {\it width} and {\it height} can be
omitted on construction if the position and size will later be set (for
example by a application frame's {\bf OnSize} callback, or if there is
only one subwindow for the frame, in which case the subwindow fills the
frame).

{\it style} is a bit list of some of the following:

\begin{twocollist}
\twocolitem{wxBORDER}{Use this style to draw a thin border in Windows 3 (non-native
implementation only).}
\twocolitem{wxNATIVE\_IMPL}{Use this style to allow editing under Windows 3.1, albeit
with a 64K limitation.}
\twocolitem{wxREADONLY}{Use this style to disable editing.}
\end{twocollist}

The {\it name} parameter is used to associate a name with the item,
allowing the application user to set Motif resource values for
individual text windows.

\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::Create}

\func{Bool}{Create}{\param{wxFrame *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1}, \param{long}{ style = 0}, \param{char *}{name = ``textWindow"}}

Creates the text item for two-step construction. Derived classes
should call or replace this function. See \helpref{wxTextWindow::wxTextWindow}{constrtextwindow}
for further details.

\membersection{wxTextWindow::Copy}

\func{Bool}{Copy}{\void}

Copies the selected text onto the clipboard.

Motif and Windows only.

\membersection{wxTextWindow::Cut}

\func{Bool}{Cut}{\void}

Copies the selected text onto the clipboard, and then
deletes the text from the window.

Motif and Windows only.

\membersection{wxTextWindow::DiscardEdits}

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

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

\membersection{wxTextWindow::GetContents}

\func{char *}{GetContents}{\void}

Gets a pointer to a newly allocated buffer containing the text window contents.
Free the buffer with the C++ delete operator.

\membersection{wxTextWindow::GetInsertionPoint}

\func{long}{GetInsertionPoint}{\void}

Gets the current insertion point.

Motif and XView only.

\membersection{wxTextWindow::GetLastPosition}

\func{long}{GetLastPosition}{\void}

Gets the position representing the end of the text window contents.

Motif and XView only.

\membersection{wxTextWindow::GetLineLength}

\func{int}{GetLineLength}{\param{long}{ lineNo}}

Gets the length of the specified line (starting from zero).

\membersection{wxTextWindow::GetLineText}

\func{int}{GetLineText}{\param{long}{ lineNo}, \param{char *}{buffer}}

Puts the contents of the specified line (starting from zero) into
the given buffer, returning the number of characters copied.

\membersection{wxTextWindow::GetNumberOfLines}

\func{int}{GetNumberOfLines}{\void}

Gets the number of lines in the text window buffer.

\membersection{wxTextWindow::SetSelection}

\func{void}{Highlight}{\param{long }{from}, \param{long }{to}}

Selects the text between {\it from} and {\it to}.

\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.

\membersection{wxTextWindow::Paste}

\func{Bool}{Paste}{\void}

Pastes text from the clipboard into the text window.

Motif and Windows only.

\membersection{wxTextWindow::PositionToXY}

\func{long}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}

Converts given character and line position to a position.

Motif and Windows only.

\membersection{wxTextWindow::Remove}

\func{void}{Remove}{\param{long }{from}, \param{long }{to}}

Removes the text between {\it from} and {\it to}.

\membersection{wxTextWindow::Replace}

\func{void}{Replace}{\param{long }{from}, \param{long }{to}, \param{char *}{value}}

Replaces the text between {\it from} and {\it to} with {\it value}.

\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::SetFont}

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

Sets the font for the text window.

Windows and Motif only.

\membersection{wxTextWindow::SetEditable}

\func{void}{SetEditable}{\param{Bool}{ editable}}

Determines whether the text window is user-editable

\membersection{wxTextWindow::SetInsertionPoint}

\func{void}{SetInsertionPoint}{\param{long}{ pos}}

Sets the current insertion point to {\it pos}.

\membersection{wxTextWindow::SetInsertionPointEnd}

\func{void}{SetInsertionPointEnd}{\void}

Sets the current insertion point to the end of the text.

Motif and XView only.

\membersection{wxTextWindow::ShowPosition}

\func{void}{ShowPosition}{\param{long}{ pos}}

Makes the line containing the given position visible.

Motif and XView only.

\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 \helpref{\cinsert}{textcinsert} for more convenient ways of writing to the
window.

\membersection{wxTextWindow::XYToPosition}

\func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}

Converts given character and line position to a position.

\membersection{wxTextWindow::\cinsert}\label{textcinsert}

\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 = new wxTextWindow(my_frame);

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

\section{\class{wxTimer}: wxObject}\label{wxtimer}

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.

See also \helpref{::wxStartTimer}{wxstarttimer} and \helpref{::wxGetElapsedTime}{wxgetelapsedtime}
for stopwatch functions.

\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::Interval}

\func{int}{Interval}{\void}

Returns the current interval for the timer.

\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{wxTypeTree}: wxList}\label{wxtypetree}

wxTypeTree implements an explicit type hierarchy which can be useful for
querying C++ types at run-time, usually by calling \helpref{wxSubType}{wxsubtype}
using the \helpref{wxObject::\_\_type}{objecttype} member.

A type is added to the global variable {\bf wxAllTypes}; wxWindows adds
its own standard types on initialization, in {\bf wxInitStandardTypes},
but the application can add its own.

The standard wxWindows types, grouped by functionality, are:

\begin{itemize}
\item wxTYPE\_ANY
\item wxTYPE\_OBJECT (an alias for wxTYPE\_ANY)
\item wxTYPE\_WINDOW
\item wxTYPE\_DIALOG\_BOX
\item wxTYPE\_ITEM
\item wxTYPE\_PANEL
\item wxTYPE\_CANVAS
\item wxTYPE\_TEXT\_WINDOW
\item wxTYPE\_FRAME
\item wxTYPE\_BUTTON
\item wxTYPE\_TEXT
\item wxTYPE\_MESSAGE
\item wxTYPE\_CHOICE
\item wxTYPE\_LIST\_BOX
\item wxTYPE\_SLIDER
\item wxTYPE\_CHECK\_BOX
\item wxTYPE\_MENU
\item wxTYPE\_MENU\_BAR
\item wxTYPE\_MULTI\_TEXT
\item wxTYPE\_RADIO\_BOX
\item wxTYPE\_EVENT
\item wxTYPE\_DC
\item wxTYPE\_DC\_CANVAS
\item wxTYPE\_DC\_POSTSCRIPT
\item wxTYPE\_DC\_PRINTER
\item wxTYPE\_DC\_METAFILE
\item wxTYPE\_DC\_MEMORY
\item wxTYPE\_MOUSE\_EVENT
\item wxTYPE\_KEY\_EVENT
\item wxTYPE\_COMMAND\_EVENT
\item wxTYPE\_PEN
\item wxTYPE\_BRUSH
\item wxTYPE\_FONT
\item wxTYPE\_ICON
\item wxTYPE\_BITMAP
\item wxTYPE\_METAFILE
\item wxTYPE\_TIMER
\item wxTYPE\_COLOUR
\item wxTYPE\_COLOURMAP
\item wxTYPE\_CURSOR
\item wxTYPE\_DDE\_CLIENT
\item wxTYPE\_DDE\_SERVER
\item wxTYPE\_DDE\_CONNECTION
\item wxTYPE\_HELP\_INSTANCE
\item wxTYPE\_LIST
\item wxTYPE\_STRING\_LIST
\item wxTYPE\_HASH\_TABLE
\item wxTYPE\_NODE
\item wxTYPE\_APP
\end{itemize}

\membersection{wxTypeTree::wxTypeTree}

\func{void}{wxTypeTree}{\void}

Constructor. Used by wxWindows only, since there only one instance of this
class.

\membersection{wxTypeTree::AddType}

\func{void}{AddType}{\param{WXTYPE}{ newType}, \param{WXTYPE}{ parentType}, \param{char *}{name}}

Adds a type to the hierarchy. {\it newType} is the type being registered,
\rtfsp{\it parentType} is the parent type, and {\it name} is an identifier
(which can used in error messages). The top (root) type is wxTYPE\_ANY.

Example:

\begin{verbatim}
wxAllTypes.AddType(wxTYPE_WINDOW, wxTYPE_ANY,     "window");
wxAllTypes.AddType(wxTYPE_PANEL,  wxTYPE_WINDOW,  "panel");
wxAllTypes.AddType(wxTYPE_CANVAS, wxTYPE_WINDOW,  "canvas");
\end{verbatim}

\membersection{wxTypeTree::GetName}

\func{char *}{GetName}{\param{WXTYPE }{typ}}

Gets a temporary pointer to the name of the given type, or NULL if the type
is not found.

\section{\class{wxWindow}: wxObject}\label{wxwindow}

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::CaptureMouse}

\func{void}{CaptureMouse}{\void}

Directs all mouse input to this window. Call {\bf ReleaseMouse} to
release the capture.

\membersection{wxWindow::Center}

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

See \helpref{Centre}{wincentre}.

\membersection{wxWindow::Centre}\label{wincentre}

\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::ClientToScreen}

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

Converts the values pointed to by {\it x} and {\it y} to screen
coordinates from coordinates relative to this window.

\membersection{wxWindow::DestroyChildren}

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

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

\membersection{wxWindow::DragAcceptFiles}\label{windragacceptfiles}

\func{void}{DragAcceptFiles}{\void}

Under Windows, makes the window eligible for a {\bf OnDropFiles} event.

\membersection{wxWindow::Enable}

\func{void}{Enable}{\param{Bool}{ enable}}

Enable or disable the window, so input has no effect.

\membersection{wxWindow::GetCharHeight}

\func{float}{GetCharHeight}{\void}

Get the character height for this window.

\membersection{wxWindow::GetCharWidth}

\func{float}{GetCharWidth}{\void}

Get the average character width for this window.

\membersection{wxWindow::GetChildren}

\func{wxList *}{GetChildren}{\void}

Returns a temporary pointer to a list of the window's children.

\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}\label{wingetclientsize}

\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::GetGrandParent}

\func{wxWindow *}{GetGrandParent}{\void}

Returns the grandparent of a window, if any.

\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::GetLabel}

\func{char *}{GetLabel}{\void}

Generic way of getting a label from any window, perhaps for
identification purposes. Some windows do not have labels (such as
subwindows), but frames, dialogs and panel items all have labels,
where the interpretation of what constitutes a label differs from
class to class. This can be useful for meta-programs (such as testing
tools or special-needs access programs) which need to identify windows
by name rather than visually.

\membersection{wxWindow::GetParent}

\func{wxWindow *}{GetParent}{\void}

Returns the parent of a window, if any.

\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}\label{winonchar}

\func{void}{OnChar}{\param{wxKeyEvent\&}{ ch}}

Sent to the window when the user has pressed a key. See \helpref{wxKeyEvent}{wxkeyevent} for
details.

For a list of the wxWindows virtual key codes, see the include file {\tt base/common.h}.
Note that the ASCII values do not have explicit key codes: they are passed as ASCII
values.

See also \helpref{wxWindow::OnEvent}{winonevent} for mouse event notification. {\bf OnChar} is
currently applicable to canvas subwindows only.

\membersection{wxWindow::OnDropFiles}

\func{void}{OnDropFiles}{\param{int}{ n}, \param{char *}{files[]}, \param{int}{ x}, \param{int}{ y}}

Under Windows, called when files have been dragged from the file manager to the window.
\rtfsp{\it files} is an array of {\it n} strings, and {\it x} and {\it y} give the mouse position
where the drop occurred. The window must have previously been enabled for dropping by calling
\rtfsp\helpref{wxWindow::DragAcceptFiles}{windragacceptfiles}.

\membersection{wxWindow::OnEvent}\label{winonevent}

\func{void}{OnEvent}{\param{wxMouseEvent\&}{ 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{wxWindow::OnChar}{winonchar} for character
events, and also \helpref{wxMouseEvent}{wxmouseevent} 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::PopupMenu}\label{popupmenu}

\func{Bool}{PopupMenu}{\param{wxMenu *}{menu}, \param{float }{x}, \param{float }{y}}

Pops up the given menu at the specified coordinates, relative to this
window, and returns control when the user has dismissed the menu. If a
menu item is selected, the callback defined for the menu is called with
wxMenu and wxCommandEvent reference arguments. The callback should access
the commandInt member of the event to check the selected menu identifier.

Valid only for subwindows (panels, canvases and text windows).

See also \helpref{wxMenu}{wxmenu}.

{\bf IMPORTANT NOTE:} under Motif, there is sometimes
a problem with popping up a menu for second and subsequent
times. It is not yet known what causes this problem and
under what circumstances. If it happens in your application,
please use the function {\it FakePopupMenu} under Motif. For
example:

\begin{verbatim}
#ifdef wx_motif
  FakePopupMenu(menu, x, y);
#else
  PopupMenu(menu, x, y);
#endif
\end{verbatim}

{\it FakePopupMenu} will show a choice dialog instead
of a popup menu; note that it only works with single-level
menus, and ignores submenus.

\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::Refresh}

\func{void}{Refresh}{\void}

Repaint the window (Motif and XView only).

\membersection{wxWindow::ReleaseMouse}

\func{void}{ReleaseMouse}{\void}

Releases mouse input captured with {\bf CaptureMouse}.

\membersection{wxWindow::ScreenToClient}

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

Converts the values pointed to by {\it x} and {\it y} to window
coordinates from screen coordinates.

\membersection{wxWindow::SetFocus}\label{winsetfocus}

\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::SetColourMap}

\func{void}{SetColourMap}{\param{wxColourMap *}{colourMap}}

Assigns the given colourmap to the window.

See \helpref{wxColourMap}{wxcolourmap} for further details.

\membersection{wxWindow::SetCursor}\label{winsetcursor}

\func{wxCursor *}{SetCursor}{\param{wxCursor *}{cursor}}

Sets the window's cursor, returning the previous cursor (if any). This
function applies to all subwindows.

See also \helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor}.

\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}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}}

\section{File functions}\label{filefunctions}

See also \helpref{wxPathList}{wxpathlist}.

\membersection{::DirExists}

\func{Bool}{DirExists}{\param{char *}{dirname}}

Returns TRUE if the directory exists.

\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 a temporary pointer to the filename for a full path.
Copy this pointer for long-term use.

\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 a temporary pointer to the directory part of the filename. Copy this
pointer for long-term use.

\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{::wxGetHostName}\label{wxgethostname}

\func{Bool}{wxGetHostName}{\param{char *}{buf}, \param{int }{sz}}

Copies the current host machine's name into the supplied buffer.

Under Windows or NT, this function first looks in the environment
variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
in the {\bf wxWindows} section of the WIN.INI file is tried.

Returns TRUE if successful, FALSE otherwise.

\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}

\func{Bool}{wxGetEmailAddress}{\param{char *}{buf}, \param{int }{sz}}

Copies the user's email address into the supplied buffer, by
concatenating the values returned by \helpref{wxGetHostName}{wxgethostname}\rtfsp
and \helpref{wxGetUserId}{wxgetuserid}.

Returns TRUE if successful, FALSE otherwise.

\membersection{::wxGetUserId}\label{wxgetuserid}

\func{Bool}{wxGetUserId}{\param{char *}{buf}, \param{int }{sz}}

Copies the current user id into the supplied buffer.

Under Windows or NT, this function first looks in the environment
variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
in the {\bf wxWindows} section of the WIN.INI file is tried.

Returns TRUE if successful, FALSE otherwise.

\membersection{::wxGetUserName}\label{wxgetusername}

\func{Bool}{wxGetUserName}{\param{char *}{buf}, \param{int }{sz}}

Copies the current user name into the supplied buffer.

Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
in the {\bf wxWindows} section of the WIN.INI file. If PenWindows
is running, the entry {\bf Current} in the section {\bf User} of
the PENWIN.INI file is used.

Returns TRUE if successful, FALSE otherwise.

\membersection{::wxGetWorkingDirectory}

\func{char *}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}}

Copies the current working directory into the buffer if supplied, or
copies the working directory into new storage if the buffer is NULL.

{\it sz} is the size of the buffer if supplied.

\membersection{::wxGetTempFileName}

\func{char *}{wxGetTempFileName}{\param{char *}{prefix}, \param{char *}{buf=NULL}}

Makes a temporary filename based on {\it prefix}, opens and closes the file,
and places the name in {\it buf}. If {\it buf} is NULL, new store
is allocated for the temporary filename using {\it new}.

Under Windows, the filename will include the drive and name of the
directory allocated for temporary files (usually the contents of the
TEMP variable). Under UNIX, the {\tt /tmp} directory is used.

It is the application's responsibility to create and delete the file.

\membersection{::wxIsWild}\label{wxiswild}

\func{Bool}{wxIsWild}{\param{char *}{pattern}}

Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.

\membersection{::wxMatchWild}\label{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}{wxiswild}.

\membersection{::wxMkdir}

\func{Bool}{wxMkdir}{\param{char *}{dir}}

Makes the directory {\it dir}, returning TRUE if successful.

\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.

\membersection{::wxRmdir}

\func{Bool}{wxRmdir}{\param{char *}{dir}}

Removes the directory {\it dir}, 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 {\it delete} operator.

\membersection{::StringMatch}

\func{Bool}{StringMatch}{\param{char *}{s1}, \param{char *}{s2},\\
  \param{Bool}{ subString = TRUE}, \param{Bool}{ exact = FALSE}}

Returns TRUE if the substring {\it s1} is found within {\it s2},
ignoring case if {\it exact} is FALSE. If {\it subString} is FALSE,
no substring matching is done.

\section{Dialog functions}\label{dialogfunctions}

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 or Motif) the wrong window frame may be brought to
the front when the dialog box is popped up.

\membersection{::wxFileSelector}\label{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{wxWindow *}{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}

\membersection{::wxGetTextFromUser}

\func{char *}{wxGetTextFromUser}{\param{char *}{message}, \param{char *}{caption = ``Input text"},\\
  \param{char *}{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
  \param{int}{ x = -1}, \param{int}{ y = -1}, \param{Bool}{ centre = TRUE}}

Pop up a dialog box with title set to {\it caption}, message {\it message}, and a
\rtfsp{\it default\_value}.  The user may type in text and press OK to return this text,
or press Cancel to return NULL.

If {\it centre} is TRUE, the message text (which may include new line characters)
is centred; if FALSE, the message is left-justified.

\membersection{::wxGetMultipleChoice}

\func{int}{wxGetMultipleChoice}{\param{char *}{message}, \param{char *}{caption}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{int }{nsel}, \param{int *}{selection},
  \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{Bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}

Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
listbox. The user may choose one or more item(s) and press OK or Cancel.

The number of initially selected choices, and array of the selected indices,
are passed in; this array will contain the user selections on exit, with
the function returning the number of selections. {\it selection} must be
as big as the number of choices, in case all are selected.

If Cancel is pressed, -1 is returned.

{\it choices} is an array of {\it n} strings for the listbox.

If {\it centre} is TRUE, the message text (which may include new line characters)
is centred; if FALSE, the message is left-justified.

\membersection{::wxGetSingleChoice}

\func{char *}{wxGetSingleChoice}{\param{char *}{message}, \param{char *}{caption}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{Bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}

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.

If {\it centre} is TRUE, the message text (which may include new line characters)
is centred; if FALSE, the message is left-justified.

\membersection{::wxGetSingleChoiceIndex}

\func{int}{wxGetSingleChoiceIndex}{\param{char *}{message}, \param{char *}{caption}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{Bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}

As {\bf wxGetSingleChoice} but returns the index representing the selected string.
If the user pressed cancel, -1 is returned.

\membersection{::wxGetSingleChoiceData}

\func{char *}{wxGetSingleChoiceData}{\param{char *}{message}, \param{char *}{caption}, \param{int}{ n}, \param{char *}{choices[]},\\
  \param{char *}{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\
  \param{int}{ y = -1}, \param{Bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}

As {\bf wxGetSingleChoice} but takes an array of client data pointers
corresponding to the strings, and returns one of these pointers.

\membersection{::wxMessageBox}\label{wxmessagebox}

\func{int}{wxMessageBox}{\param{char *}{message}, \param{char *}{caption = ``Message"}, \param{int}{ style = wxOK $\|$ wxCENTRE},\\
  \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}

General purpose message dialog.  {\it style} may be a bit list of the
following identifiers:

\begin{twocollist}
\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
wxCANCEL.}
\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
wxYES\_NO or wxOK.}
\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
\twocolitem{wxCENTRE}{Centres the text.}
\twocolitem{wxICON\_EXCLAMATION}{Under Windows, displays an exclamation mark symbol.}
\twocolitem{wxICON\_HAND}{Under Windows, displays a hand symbol.}
\twocolitem{wxICON\_QUESTION}{Under Windows, displays a question mark symbol.}
\twocolitem{wxICON\_INFORMATION}{Under Windows, displays an information symbol.}
\end{twocollist}

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, to cater for large messages.

Under Windows, the native MessageBox function is used unless wxCENTRE
is specified in the style, in which case a generic function is used.
This is because the native MessageBox function cannot centre text.
The symbols are not shown when the generic function is used.

\section{GDI functions}\label{gdifunctions}

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{::wxDisplayDepth}

\func{int}{wxDisplayDepth}{\void}

Returns the depth of the display (a value of 1 denotes a monochrome display).

\membersection{::wxMakeMetaFilePlaceable}\label{wxmakemetafileplaceable}

\func{Bool}{wxMakeMetaFilePlaceable}{\param{char *}{filename}, \param{float }{minX}, \param{float }{minY},
 \param{float }{maxX}, \param{float }{maxY}, \param{float }{scale=1.0}}

Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetaFileDC}{wxmetafiledc})
makes it into a placeable metafile by prepending a header containing the given
bounding box. The bounding box may be obtained from a device context after drawing
into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.

In addition to adding the placeable metafile header, this function adds
the equivalent of the following code to the start of the metafile data:

\begin{verbatim}
 SetMapMode(dc, MM_ANISOTROPIC);
 SetWindowOrg(dc, minX, minY);
 SetWindowExt(dc, maxX - minX, maxY - minY);
\end{verbatim}

This simulates the MM\_TEXT mapping mode, which wxWindows assumes.

Placeable metafiles may be imported by many Windows applications, and can be
used in RTF (Rich Text Format) files.

{\it scale} allows the specification of scale for the metafile.

This function is only available under Windows.

\membersection{::wxSetCursor}\label{wxsetcursor}

\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}

Globally sets the cursor; only has an effect in Windows 3.
See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{winsetcursor}.

\section{System event functions}

The wxWindows system event implementation is incomplete and
experimental, but is intended to be a platform-independent way of
intercepting and sending events, including defining
application-specific events and handlers.

Ultimately it is intended to be used as a way of testing wxWindows
applications using scripts, although there are currently
problems with this (especially with modal dialogs).

All this is documented more to provoke comments and suggestions, and
jog my own memory, rather than to be used, since it has not been
tested. However {\bf wxSendEvent} will probably work if you
instantiate the event structure properly for a command event type (see
the code in {\tt wb\_panel.cc} for \helpref{wxPanel::OnDefaultAction}{wxpanelondefaultaction}\rtfsp
which uses {\bf wxSendEvent} to send a command to the default button).

\membersection{::wxAddPrimaryEventHandler}

\func{Bool}{wxAddPrimaryEventHandler}{\param{wxEventHandler}{ handlerFunc}}

Add a primary event handler---the normal event handler for this
event. For built-in events, these would include moving and resizing
windows. User-defined primary events might include the code to
select an image in a diagram (which could of course be achieved by a series
of external events for mouse-clicking, but would be more difficult to specify
and less robust).

Returns TRUE if it succeeds.

An event handler takes a pointer to a wxEvent and a boolean flag which is
TRUE if the event was externally generated, and returns a boolean which is
TRUE if that event was handled.

\membersection{::wxAddSecondaryEventHandler}

\func{Bool}{wxAddSecondaryEventHandler}{\param{wxEventHandler}{ handlerFunc}, \param{Bool}{ pre},\\
  \param{Bool}{ override}, \param{Bool }{append}}

Add a secondary event handler, pre = TRUE iff it should be called before the
event is executed. override = TRUE iff the handler is allowed to override
all subsequent events by returning TRUE. Returns TRUE if succeeds.

A secondary event handler is an application-defined handler that may
intercept normal events, possibly overriding them. A primary event handler
provides the normal behaviour for the event.

An event handler takes a pointer to a wxEvent and a boolean flag which is
TRUE if the event was externally generated, and returns a boolean which is
TRUE if that event was handled.

\membersection{::wxNotifyEvent}

\func{Bool}{wxNotifyEvent}{\param{wxEvent\&}{ event}, \param{Bool}{ pre}}

Notify the system of the event you are about to execute/have just
executed.  If TRUE is returned and pre = TRUE, the calling code should
not execute the event (since it has been intercepted by a handler and
vetoed).

These events are always internal, because they're generated from within
the main application code.

\membersection{::wxRegisterEventClass}

\func{void}{wxRegisterEventClass}{\param{WXTYPE}{ eventClassId},\param{WXTYPE}{ superClassId},\\
  \param{wxEventConstructor}{ constructor}, \param{char *}{description}}

Register a new event class (derived from wxEvent), giving the new
event class type, its superclass, a function for creating a new event
object of this class, and an optional description.

\membersection{::wxRegisterEventName}

\func{void}{wxRegisterEventName}{\param{WXTYPE}{ eventTypeId},\param{WXTYPE}{ eventClassId},\\
  \param{char *}{eventName}}

Register the name of the event. This will allow a simple command
language where giving the event type name and some arguments will
cause a new event of class {\it eventClassId} to be created, with given
event type, and some arguments, allows an event to be dynamically
constructed and sent.

\membersection{::wxRegisterExternalEventHandlers}

\func{void}{wxRegisterExternalEventHandlers}{\void}

Define this and link before wxWindows library to allow registering
events from `outside' the main application.

\membersection{::wxRemoveSecondaryEventHandler}

\func{Bool}{wxRemoveSecondaryEventHandler}{\param{wxEventHandler}{ handlerFunc}, \param{Bool}{ pre}}

Remove a secondary event handler. Returns TRUE if it succeeds.

\membersection{::wxSendEvent}\label{wxsendevent}

\func{Bool}{wxSendEvent}{\param{wxEvent\&}{ event}, \param{Bool}{ external}}

Send an event to the system; usually it will be external, but set
external to FALSE if calling from within the main application in
response to other events.

Returns TRUE if the event was processed.

\section{Printer settings}\label{printersettings}

The following functions are used to control PostScript printing. Under
Windows, PostScript output can only be sent to a file.

\membersection{::wxGetPrinterCommand}

\func{char *}{wxGetPrinterCommand}{\void}

Gets the printer command used to print a file. The default is {\tt lpr}.

\membersection{::wxGetPrinterFile}

\func{char *}{wxGetPrinterFile}{\void}

Gets the PostScript output filename.

\membersection{::wxGetPrinterMode}

\func{int}{wxGetPrinterMode}{\void}

Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
The default is PS\_PREVIEW.

\membersection{::wxGetPrinterOptions}

\func{char *}{wxGetPrinterOptions}{\void}

Gets the additional options for the print command (e.g. specific printer). The default is nothing.

\membersection{::wxGetPrinterOrientation}

\func{int}{wxGetPrinterOrientation}{\void}

Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.

\membersection{::wxGetPrinterPreviewCommand}

\func{char *}{wxGetPrinterPreviewCommand}{\void}

Gets the command used to view a PostScript file. The default depends on the platform.

\membersection{::wxGetPrinterScaling}

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

Gets the scaling factor for PostScript output. The default is 1.0, 1.0.

\membersection{::wxGetPrinterTranslation}

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

Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.

\membersection{::wxSetPrinterCommand}

\func{void}{wxSetPrinterCommand}{\param{char *}{command}}

Sets the printer command used to print a file. The default is {\tt lpr}.

\membersection{::wxSetPrinterFile}

\func{void}{wxSetPrinterFile}{\param{char *}{filename}}

Sets the PostScript output filename.

\membersection{::wxSetPrinterMode}

\func{void}{wxSetPrinterMode}{\param{int }{mode}}

Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
The default is PS\_PREVIEW.

\membersection{::wxSetPrinterOptions}

\func{void}{wxSetPrinterOptions}{\param{char *}{options}}

Sets the additional options for the print command (e.g. specific printer). The default is nothing.

\membersection{::wxSetPrinterOrientation}

\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}

Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.

\membersection{::wxSetPrinterPreviewCommand}

\func{void}{wxSetPrinterPreviewCommand}{\param{char *}{command}}

Sets the command used to view a PostScript file. The default depends on the platform.

\membersection{::wxSetPrinterScaling}

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

Sets the scaling factor for PostScript output. The default is 1.0, 1.0.

\membersection{::wxSetPrinterTranslation}

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

Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.

\section{Miscellaneous}\label{miscellany}

\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{::wxBeginBusyCursor}\label{wxbeginbusycursor}

\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}

Changes the cursor to the given cursor for all windows in the application.
Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
to its previous state. These two calls can be nested, and a counter
ensures that only the outer calls take effect.

See also \helpref{wxIsBusy}{wxisbusy}.

\membersection{::wxBell}

\func{void}{wxBell}{\void}

Ring the system bell.

\membersection{::wxDebugMsg}

\func{void}{wxDebugMsg}{\param{char *}{fmt}, \param{...}{}}

Display a debugging message; under Windows, this will appear on the
debugger command window, and under UNIX, it will be written to standard
error.

The syntax is identical to {\bf printf}: pass a format string and a
variable list of arguments.

Note that under Windows, you can see the debugging messages without a
debugger if you have the DBWIN debug log application that comes with
Microsoft C++.

\membersection{::wxDisplaySize}

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

Gets the physical size of the display in pixels.

\membersection{::wxError}\label{wxerror}

\func{void}{wxError}{\param{char *}{msg}, \param{char *}{title = "wxWindows Internal Error"}}

Displays {\it msg} and continues. This writes to standard error under
UNIX, and pops up a message box under Windows. Used for internal
wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.

\membersection{::wxEndBusyCursor}\label{wxendbusycursor}

\func{void}{wxEndBusyCursor}{\void}

Changes the cursor back to the original cursor, for all windows in the application.
Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.

See also \helpref{wxIsBusy}{wxisbusy}.

\membersection{::wxExecute}\label{wxexecute}

\func{Bool}{wxExecute}{\param{char *}{command}, \param{Bool }{sync = FALSE}}

\func{Bool}{wxExecute}{\param{char **}{argv}, \param{Bool }{sync = FALSE}}

Executes another program in UNIX or Windows.

The first form takes a command string, such as {\tt "emacs file.txt"}.

The second form takes an array of values: a command, any number of
arguments, terminated by NULL.

If {\it sync} is FALSE (the default), flow of control immediately returns.
If TRUE, the current application waits until the other program has terminated.

See also \helpref{wxShell}{wxshell}.

\membersection{::wxExit}\label{wxexit}

\func{void}{wxExit}{\void}

Exits application after calling \helpref{wxApp::OnExit}{apponexit}.
Should only be used in an emergency: normally the top-level frame
should be deleted (after deleting all other frames) to terminate the
application. See \helpref{wxFrame::OnClose}{wxframeonclose} and \helpref{wxApp}{wxapp}.

\membersection{::wxFatalError}\label{wxfatalerror}

\func{void}{wxFatalError}{\param{char *}{msg}, \param{char *}{title = "wxWindows Fatal Error"}}

Displays {\it msg} and exits. This writes to standard error under UNIX,
and pops up a message box under Windows. Used for fatal internal
wxWindows errors. See also \helpref{wxError}{wxerror}.

\membersection{::wxFindFirstFile}\label{wxfindfirstfile}

\func{char *}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}}

This function does directory searching; returns the first file
that matches the path {\it spec}, or NULL. Use \helpref{wxFindNextFile}{wxfindnextfile} to
get the next matching file.

{\it spec} may contain wildcards.

{\it flags} is reserved for future use.

The returned filename is a pointer to static memory so should
not be freed.

{\it Note:} this function is not implemented for Borland C++ or Windows NT.

For example:

\begin{verbatim}
  char *f = wxFindFirstFile("/home/project/*.*");
  while (f)
  {
    ...
    f = wxFindNextFile();
  }
\end{verbatim}

\membersection{::wxFindNextFile}\label{wxfindnextfile}

\func{char *}{wxFindFirstFile}{\void}

Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.

{\it Note:} this function is not implemented for Borland C++ or Windows NT.

\membersection{::wxFindMenuItemId}

\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{char *}{menuString}, \param{char *}{itemString}}

Find a menu item identifier associated with the given frame's menu bar.

\membersection{::wxFindWindowByLabel}

\func{wxWindow *}{wxFindWindowByLabel}{\param{wxWindow *}{parent}, \param{char *}{label}}

Find a window by its label. Depending on the type of window, the label may be a window title
or panel item label. If {\it parent} is NULL, the search will start from all top-level
frames and dialog boces; if non-NULL, the search will be limited to the given window hierarchy.
The search is recursive in both cases.

\membersection{::wxGetHomeDir}

\func{char *}{wxGetHomeDir}{\param{char *}{buf}}

Fills the buffer with a string representing the user's home directory (UNIX only).

\membersection{::wxGetHostName}

\func{Bool}{wxGetHostName}{\param{char *}{buf}, \param{int}{ bufSize}}

Copies the host name of the machine the program is running on into the
buffer {\it buf}, of maximum size {\it bufSize}, returning TRUE if
successful. Under UNIX, this will return a machine name. Under Windows,
this returns ``windows''.

\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}

\func{long}{wxGetElapsedTime}{\param{Bool}{ resetTimer = TRUE}}

Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.

If {\it resetTimer} is TRUE (the default), the timer is reset to zero
by this call.

See also \helpref{wxTimer}{wxtimer}.

\membersection{::wxGetFreeMemory}

\func{long}{wxGetFreeMemory}{\void}

Returns the amount of free memory in Kbytes under environments which
support it, and -1 if not supported. Currently, returns a positive value
under Windows, and -1 under UNIX.

\membersection{::wxGetOsVersion}

\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}

Gets operating system version information.

\begin{twocollist}
\twocolitemruled{Platform}{Return tyes}
\twocolitem{XView}{Return value is wxXVIEW\_X, {\it major} is X version, {\it minor} is X revision.}
\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
\twocolitem{Windows NT}{Return value is wxWINDOWS\_NT, {\it major} is 3, {\it minor} is 1.}
\twocolitem{WIN32s}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
\end{twocollist}

\membersection{::wxGetResource}\label{wxgetresource}

\func{Bool}{wxGetResource}{\param{char *}{section}, \param{char *}{entry},
 \param{char **}{value}, \param{char *}{file = NULL}}

\func{Bool}{wxGetResource}{\param{char *}{section}, \param{char *}{entry},
 \param{float *}{value}, \param{char *}{file = NULL}}

\func{Bool}{wxGetResource}{\param{char *}{section}, \param{char *}{entry},
 \param{long *}{value}, \param{char *}{file = NULL}}

\func{Bool}{wxGetResource}{\param{char *}{section}, \param{char *}{entry},
 \param{int *}{value}, \param{char *}{file = NULL}}

Gets a resource value from the resource database (for example, WIN.INI, or
.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
otherwise the specified file is used.

Under X, if an application class (wxApp::wx\_class) has been defined,
it is appended to the string /usr/lib/X11/app-defaults/ to try to find
an applications default file when merging all resource databases.

The reason for passing the result in an argument is that it
can be convenient to define a default value, which gets overridden
if the value exists in the resource file. It saves a separate
test for that resource's existence, and it also allows
the overloading of the function for different types.

See also \helpref{wxWriteResource}{wxwriteresource}.

\membersection{::wxGetUserId}

\func{Bool}{wxGetUserId}{\param{char *}{buf}, \param{int}{ bufSize}}

Copies the user's login identity (such as ``jacs'') into the buffer {\it
buf}, of maximum size {\it bufSize}, returning TRUE if successful.
Under Windows, this returns ``user''.

\membersection{::wxGetUserName}

\func{Bool}{wxGetUserName}{\param{char *}{buf}, \param{int}{ bufSize}}

Copies the user's name (such as ``Julian Smart'') into the buffer {\it
buf}, of maximum size {\it bufSize}, returning TRUE if successful.
Under Windows, this returns ``unknown''.

\membersection{::wxIPCInitialize}\label{wxipcinitialize}

\func{void}{wxIPCInitialize}{\void}

Initializes for interprocess communication operation. May
be called multiple times without harm.

See also \helpref{wxServer}{wxserver}, \helpref{wxClient}{wxclient}, \helpref{wxConnection}{wxconnection}
and the relevant section of the user manual.

\membersection{::wxIsBusy}\label{wxisbusy}

\func{Bool}{wxIsBusy}{\void}

Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
\helpref{wxEndBusyCursor}{wxendbusycursor} calls.

\membersection{::wxShell}\label{wxshell}

\func{Bool}{wxShell}{\param{const char *}{command = NULL}}

Executes a command in an interactive shell window. If no command is
specified, then just the shell is spawned.

See also \helpref{wxExecute}{wxexecute}.

\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{::wxStripMenuCodes}

\func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}}

Strips any menu codes from {\it in} and places the result
in {\it out}. Menu codes include \& (mark the next character with an underline
as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).

\membersection{::wxStartTimer}\label{wxstarttimer}

\func{void}{wxStartTimer}{\void}

Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.

See also \helpref{wxTimer}{wxtimer}.

\membersection{::wxSubType}\label{wxsubtype}

\func{Bool}{wxSubType}{\param{WXTYPE}{ type1}, \param{WXTYPE}{ type2}}

TRUE if {\it type1} is a subtype of, or the same type as, {\it type2}. This can
be useful when determining whether an object is an instance of a class derived from
some other class, and its usage can make for generic code.

See also \helpref{wxTypeTree}{wxtypetree} and \helpref{wxObject::\_\_type}{objecttype}.

Example:

\begin{verbatim}
  wxNode *node = GetChildren()->First();
  while (node)
  {
    // Find a child that's a subwindow, but not a dialog box.
    wxWindow *child = (wxWindow *)node->Data();
    if ((wxSubType(child->__type, wxTYPE_PANEL) &&
         !wxSubType(child->__type, wxTYPE_DIALOG_BOX)) ||
        wxSubType(child->__type, wxTYPE_TEXT_WINDOW) ||
        wxSubType(child->__type, wxTYPE_CANVAS))
    {
      child->SetFocus();
      return;
    }
    node = node->Next();
  }
\end{verbatim}

\membersection{::wxToLower}\label{wxtolower}

\func{char}{wxToLower}{\param{char }{ch}}

Converts the character to lower case. This is implemented as a macro for efficiency.

\membersection{::wxToUpper}\label{wxtoupper}

\func{char}{wxToUpper}{\param{char }{ch}}

Converts the character to upper case. This is implemented as a macro for efficiency.

\membersection{::wxWriteResource}\label{wxwriteresource}

\func{Bool}{wxWriteResource}{\param{char *}{section}, \param{char *}{entry},
 \param{char *}{value}, \param{char *}{file = NULL}}

\func{Bool}{wxWriteResource}{\param{char *}{section}, \param{char *}{entry},
 \param{float }{value}, \param{char *}{file = NULL}}

\func{Bool}{wxWriteResource}{\param{char *}{section}, \param{char *}{entry},
 \param{long }{value}, \param{char *}{file = NULL}}

\func{Bool}{wxWriteResource}{\param{char *}{section}, \param{char *}{entry},
 \param{int }{value}, \param{char *}{file = NULL}}

Writes a resource value into the resource database (for example, WIN.INI, or
.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
otherwise the specified file is used.

Under X, the resource databases are cached until the internal function
\rtfsp{\bf wxFlushResources} is called automatically on exit, when
all updated resource databases are written to their files.

Note that it is considered bad manners to write to the .Xdefaults
file under UNIX, although the WIN.INI file is fair game under Windows.

See also \helpref{wxGetResource}{wxgetresource}.

\membersection{::wxYield}

\func{Bool}{wxYield}{\void}

Yields control to pending messages in the windowing system (has no
effect under XView or Motif). This can be useful, for example, when a
time-consuming process writes to a text window. Without an occasional
yield, the text window will not be updated properly, and (since Windows
multitasking is cooperative) other processes will not respond.

Caution should be exercised, however, since yielding may allow the
user to perform actions which are not compatible with the current task.
Disabling menu items or whole menus during processing can avoid unwanted
reentrance of code.

