\chapter{Alphabetical class reference}\label{classref}
\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}%

\overview{Writing a wxWindows application: a rough guide}{roughguide}

\helponly{
\sethotspotcolour{off}%
\large{
\helpref{Notes on using the reference}{referencenotes}\\
\helpref{Guide to functions}{functions}
\sethotspotcolour{on}%
}}

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

\overview{wxApp overview}{wxappoverview}

The {\bf wxApp} class represents the application itself.

\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::work\_proc}

\member{void *}{work\_proc}

Set this member to the address of a function that takes a pointer to {\bf wxApp}.
It will be called whenever the system is idle and can be used to schedule
background tasks.

\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::GetAppName}\label{wxappgetappname}

\func{char *}{GetAppName}{\void}

Returns the application name. wxWindows sets this to a reasonable default before
calling wxApp::OnInit, but the application can reset it at will.

\membersection{wxApp::GetClassName}\label{wxappgetclassname}

\func{void}{SetClassName}{\param{char *}{name}}

Gets the class name of the application. The class name may be used in a platform specific
manner to refer to the application.

\membersection{wxApp::GetPrintMode}\label{wxappgetprintmode}

\func{Bool}{GetPrintMode}{\void}

Returns the print mode: see \helpref{SetPrintMode}{wxappsetprintmode}.

\membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}

\func{wxWindow *}{GetTopWindow}{\void}

Returns a pointer to the top window (as returned by wxApp::OnInit). This may return NULL
if called before the end of wxApp::OnInit.

\membersection{wxApp::MainLoop}

\func{void}{ExitMainLoop}{\void}

Call this to explicitly exit the main message (event) loop.
You should normally exit the main loop (and the application) by deleting
the frame returned from wxApp::OnInit.

\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{int}{OnExit}{\void}

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

\membersection{wxApp::OnCharHook}\label{wxapponcharhook}

\func{Bool}{OnCharHook}{\param{wxKeyEvent\&}{ ch}}

This member is called (under Windows only) to allow the window to intercept keyboard events
before they are processed by child windows. The default implementation
forwards the message to the currently active window.
The function should returns TRUE to indicate the
character has been processed, or FALSE to allow default processing.

See also \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxEvtHandler::OnChar}{wxevthandleronchar},\rtfsp
\helpref{wxEvtHandler::OnCharHook}{wxevthandleroncharhook}, \helpref{wxDialogBox::OnCharHook}{wxdialogboxoncharhook}.

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

\membersection{wxApp::SetAppName}\label{wxappsetappname}

\func{void}{SetAppName}{\param{char *}{name}}

Sets the name of the application. The name may be used in dialogs
(for example by the document/view framework). A default name is set by
wxWindows.

\membersection{wxApp::SetClassName}\label{wxappsetclassname}

\func{void}{SetClassName}{\param{char *}{name}}

Sets the class name of the application. This may be used in a platform specific
manner to refer to the application.

\membersection{wxApp::SetPrintMode}\label{wxappsetprintmode}

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

Sets the print mode determining what printing facilities will be
used by the printing framework.

\begin{itemize}\itemsep=0pt
\item wxPRINT\_WINDOWS: under Windows, use Windows printing (wxPrinterDC). This is the
default under Windows.
\item wxPRINT\_POSTSCRIPT: use PostScript printing (wxPostScriptDC). This is the
default for non-Windows platforms.
\end{itemize}

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

\overview{Overview}{wxbitmapoverview}

This class encapsulates the concept of a platform-dependent bitmap,
either monochrome or colour.

\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 **}{bits}}

Constructs a bitmap from pixmap (XPM) data, if wxWindows has been configured
to incorporate this feature.

To use this constructor, you must first include an XPM file. For
example, assuming that the file {\tt mybitmap.xpm} contains an XPM array
of character pointers called mybitmap:

\begin{verbatim}
#include "mybitmap.xpm"

...

wxBitmap *bitmap = new wxBitmap(mybitmap);
\end{verbatim}

\func{void}{wxBitmap}{\param{char *}{name}, \param{long}{flags}}

Constructs a bitmap from a file or resource. {\it name} can refer
to a resource name under Windows 3, or a filename under Windows 3 and X.

Under Windows, {\it flags} defaults to wxBITMAP\_TYPE\_BMP\_RESOURCE $\|$ wxBITMAP\_DISCARD\_COLOURMAP.
Under X, {\it flags} defaults to wxBITMAP\_TYPE\_XBM $\|$ wxBITMAP\_DISCARD\_COLOURMAP.

The meaning of {\it name} is determined by the {\it flags} parameter which
may be a bit list of {\bf wxBITMAP\_DISCARD\_COLOURMAP} (meaning the colourmap read,
if any, should be thrown away) and one of:

\begin{itemize}\itemsep=0pt
\item {\bf wxBITMAP\_TYPE\_BMP} Load a Windows bitmap file.
\item {\bf wxBITMAP\_TYPE\_BMP\_RESOURCE} Load a Windows bitmap from the resource database.
\item {\bf wxBITMAP\_TYPE\_GIF} Load a GIF bitmap file.
\item {\bf wxBITMAP\_TYPE\_XBM} Load an X bitmap file.
\item {\bf wxBITMAP\_TYPE\_XPM} Load an XPM bitmap file.
\item {\bf wxBITMAP\_TYPE\_RESOURCE} Load a Windows resource name.
\end{itemize}

The validity of these flags depends on the platform and wxWindows configuration.
If all possible wxWindows settings are used, the Windows platform supports BMP, BMP\_RESOURCE,
XPM\_DATA, and XPM. Under X, the available formats are BMP, GIF, XBM, and XPM.

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

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

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

\membersection{wxBitmap::GetColourMap}\label{wxbitmapgetcolourmap}

\func{wxColourMap *}{GetColourMap}{\void}

Gets the associated colourmap (if any) which may have been loaded from a file
or set for the bitmap.

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

\func{Bool}{LoadFile}{\param{char *}{name}, \param{long}{ flags}}

Loads a bitmap from a file or resource. {\it name} can refer
to a resource name under Windows 3, or a filename under Windows 3 and X.

The meaning of {\it name} is determined by the {\it flags} parameter which
may be a bit list of {\bf wxBITMAP\_DISCARD\_COLOURMAP} (meaning the colourmap read,
if any, should be thrown away) and one of:

\begin{itemize}\itemsep=0pt
\item {\bf wxBITMAP\_TYPE\_BMP} Load a Windows bitmap file
\item {\bf wxBITMAP\_TYPE\_GIF} Load a GIF bitmap file
\item {\bf wxBITMAP\_TYPE\_XBM} Load a Windows bitmap file
\item {\bf wxBITMAP\_TYPE\_XPM} Load an XPM bitmap file
\item {\bf wxBITMAP\_TYPE\_RESOURCE} Load a Windows resource name
\end{itemize}

The validity of these flags depends on the platform and wxWindows configuration.

A colourmap may be associated with the bitmap if one exists (especially for
colour Windows bitmaps), and if the code supports it. You can check
if one has been created by using the \helpref{GetColourMap}{wxbitmapgetcolourmap} member.

\membersection{wxBitmap::Ok}

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

Returns TRUE if the bitmap was successfully created.

\membersection{wxBitmap::SaveFile}

\func{Bool}{SaveFile}{\param{char *}{name}, \param{int}{ type}, \param{wxColourMap *}{cmap}}

Saves a bitmap in the named file.

The type of saved is determined by the {\it type} parameter which may be one of:

\begin{itemize}\itemsep=0pt
\item {\bf wxBITMAP\_TYPE\_BMP} Load a Windows bitmap file
\item {\bf wxBITMAP\_TYPE\_GIF} Load a GIF bitmap file
\item {\bf wxBITMAP\_TYPE\_XBM} Load a Windows bitmap file
\item {\bf wxBITMAP\_TYPE\_XPM} Load an XPM bitmap file
\item {\bf wxBITMAP\_TYPE\_RESOURCE} Load a Windows resource name
\end{itemize}

The validity of these flags depends on the platform and wxWindows configuration.

If a colourmap is supplied, it may be used when saving the bitmap. If this
parameter is NULL and there is a colourmap associated with the bitmap, this
internal colourmap may be used instead.

\membersection{wxBitmap::SetColourMap}

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

Sets the associated colourmap: it will be deleted in the wxBitmap
constructor, so if you do not wish it to be deleted automatically,
reset the colourmap to NULL before the bitmap is deleted.

\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 one of:

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

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}{wxbrushlist} 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 (see \helpref{wxBrush::SetStyle}{wxbrushsetstyle}).
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}\itemsep=0pt
\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}\label{wxbrushsetstyle}

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

Sets the brush style, one of:

\begin{itemize}\itemsep=0pt
\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{wxbrushlist}

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.
See \helpref{wxBrush::SetStyle}{wxbrushsetstyle} for a list of styles.

\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}\rtfsp
which sets the keyboard focus for windows and text panel items, \helpref{wxPanel::OnDefaultAction}{wxpanelondefaultaction}\rtfsp
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{wxButtonBar}: wxToolBar}\label{wxbuttonbar}

\overview{Overview}{wxbuttonbaroverview}

A wxButtonBar very similar to the \helpref{wxToolBar}{wxtoolbar}, but
is optimized for use under MS Windows, giving a more attractive appearance
and better feedback. Include the file {\tt wx\_bbar.h} to use this class.

\membersection{wxButtonBar::GetDefaultButtonHeight}

\func{float}{GetDefaultButtonHeight}{\void}

Returns the real height of the button (bitmap height plus the extra for
3D effects).

\membersection{wxButtonBar::GetDefaultButtonWidth}

\func{float}{GetDefaultButtonWidth}{\void}

Returns the real width of the button (bitmap width plus the extra for
3D effects).

\membersection{wxButtonBar::SetDefaultSize}

\func{void}{SetDefaultSize}{\param{float}{ width}, \param{float}{ height}}

Sets the default size of the button bitmap. The default is 16x15 pixels.

\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{wxWindow *}{parent}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = wxRETAINED}, \param{char *}{name = ``canvas"}}

Constructor.

Under Windows and Motif, the parent can be either a frame or panel.
Under XView, the parent must be a frame.

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}\itemsep=0pt
\twocolitem{wxBORDER}{Gives the canvas a thin border (Windows 3 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.}
\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).}
\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::Clear}

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

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

\membersection{wxCanvas::Create}

\func{void}{Create}{\param{wxWindow *}{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}\rtfsp
for details.

\membersection{wxCanvas::CrossHair}\label{wxcanvascrosshair}

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

Displays a cross hair using the current pen. This is a vertical
and horizontal line the height and width of the canvas, centred
on the given point.

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

\func{void}{FloodFill}{\param{float}{ x}, \param{float}{ y}, \param{wxColour *}{colour}, \param{int}{ style=wxFLOOD\_SURFACE}}

Flood fills the canvas starting from the given point, in the given colour,
and using a style:

\begin{itemize}\itemsep=0pt
\item wxFLOOD\_SURFACE: the flooding occurs until a colour other than the given colour is encountered.
\item wxFLOOD\_BORDER: the area to be flooded is bounded by the given colour.
\end{itemize}

{\it Note:} this function is available in MS Windows only.

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

The member {\it keyCode} contains the key pressed.

See \helpref{wxEvtHandler::OnChar}{wxevthandleronchar} for more 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}\rtfsp
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.

There is currently (1.61 beta e) an experimental method for optimizing painting,
by retrieving the rectangles that have been damaged and only repainting
these. The rectangles are in terms of the client area, and are unscrolled,
so you will need to do some calculations using the current view
position to obtain logical, scrolled units.

Here is an example of using the update iterator:

\begin{verbatim}
// Called when canvas needs to be repainted.
void MyCanvas::OnPaint(void)
{
  // Speeds up drawing under Windows.
  GetDC()->BeginDrawing();
  wxCanvasDC *canvdc = GetDC();

  // Find Out where the window is scrolled to
  int vbX,vbY;                     // Top left corner of client
  ViewStart(&vbX,&vbY);

  int vX,vY,vW,vH;                 // Dimensions of client area in pixels
  wxUpdateIterator	upd(this); // get the update rect list

  while (upd)
  {
    vX = upd.GetX();
    vY = upd.GetY();
    vW = upd.GetWidth();
    vH = upd.GetHeight();

    // Alternatively we can do this:
    // wxRectangle rect;
    // upd.GetRect(&rect);

    // Repaint this rectangle
    <some code>

    upd ++ ;
  }
  GetDC()->EndDrawing();
}
\end{verbatim}

\membersection{wxCanvas::OnScroll}\label{wxcanvasonscroll}

\func{void}{OnScroll}{\param{wxCommandEvent\& }{event}}

Override this function to intercept scroll events. This
member function implements the default scroll behaviour. If
you do not call the default function, you will have to manage
all scrolling behaviour including drawing the canvas contents
at an appropriate position relative to the scrollbar.

The {\it commandInt} member of wxCommandEvent is the
position of the scrollbar. The macro WXSCROLLPOS(event) may
be used to access or set this member.

The {\it extraLong} member of wxCommandEvent is wxHORIZONTAL
or wxVERTICAL. The macro WXSCROLLORIENT(event) may be used
to access or set this member.

The {\it eventType} member of wxCommandEvent will be one of:

\begin{twocollist}
\twocolitem{wxEVENT\_TYPE\_SCROLL\_LINEDOWN}{Called when the
scrollbar is incremented by a line, by clicking on the bottom arrow
of a vertical scrollbar or right-hand arrow of a horizontal scrollbar.}
\twocolitem{wxEVENT\_TYPE\_SCROLL\_LINEUP}{Called when the
scrollbar is decremented by a line, by clicking on the top arrow
of a vertical scrollbar or left-hand arrow of a horizontal scrollbar.}
\twocolitem{wxEVENT\_TYPE\_SCROLL\_PAGEDOWN}{Called when the
scrollbar is incremented by a page.}
\twocolitem{wxEVENT\_TYPE\_SCROLL\_PAGEUP}{Called when the
scrollbar is decremented by a page.}
\twocolitem{wxEVENT\_TYPE\_SCROLL\_TOP}{Called when the
scrollbar is set to the top.}
\twocolitem{wxEVENT\_TYPE\_SCROLL\_BOTTOM}{Called when the
scrollbar is set to the bottom.}
\twocolitem{wxEVENT\_TYPE\_SCROLL\_THUMBTRACK}{Called when the
the scrollbar is being dragged.}
\end{twocollist}

Note that not all these messages will be received on a given
platform. For example, under XView, only the thumbtrack event
is ever generated, and so unless the application keeps track of
where the scrollbar was previously, some scrolling optimisations are not
possible.

Under Windows and Motif, all messages may be generated.

\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
wxSRC_AND             AND src (MS Windows Blit only: equivalent to SRCAND)
wxSRC_OR              OR src (MS Windows Blit only: equivalent to SRCPAINT)
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.

\membersection{wxCanvasDC::GetClippingBox}

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

Gets the current rectangular clipping region.

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

\func{int}{GetColumns}{\void}

Gets the number of columns in this choice item.

This is implemented for XView and Motif only.

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

\func{void}{SetColumns}{\param{int}{ n = 1}}

Sets the number of columns in this choice item.

This is implemented for XView and Motif only.

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

\overview{Overview}{wxclassinfooverview}

This class stores meta-information about classes. Instances of this class are
not generally defined directly by an application, but indirectly through use
of macros such as DECLARE\_DYNAMIC\_CLASS and IMPLEMENT\_DYNAMIC\_CLASS.

\membersection{wxClassInfo::wxClassInfo}

\func{void}{wxClassInfo}{\param{char *}{className}, \param{char *}{baseClass1}, \param{char *}{baseClass2},
 \param{int}{ size}, \param{wxObjectConstructorFn }{fn}}

Constructs a wxClassInfo object. The supplied macros implicitly construct objects of this
class, so there is no need to create such objects explicitly in an application.

\membersection{wxClassInfo::CreateObject}

\func{wxObject *}{CreateObject}{\void}

Creates an object of the appropriate kind. Returns NULL if the class has not been declared
dynamically createable (typically, it's an abstract class).

\membersection{wxClassInfo::FindClass}

\func{static wxClassInfo *}{FindClass}{\param{char *}{name}}

Finds the wxClassInfo object for a class of the given string name.

\membersection{wxClassInfo::GetBaseClassName1}

\func{char *}{GetBaseClassName1}{\void}

Returns the name of the first base class (NULL if none).

\membersection{wxClassInfo::GetBaseClassName2}

\func{char *}{GetBaseClassName2}{\void}

Returns the name of the second base class (NULL if none).

\membersection{wxClassInfo::GetClassName}

\func{char *}{GetClassName}{\void}

Returns the string form of the class name.

\membersection{wxClassInfo::GetSize}

\func{int}{GetSize}{\void}

Returns the size of the class.

\membersection{wxClassInfo::InitializeClasses}

\func{static void}{InitializeClasses}{\void}

Initializes pointers in the wxClassInfo objects for fast execution
of IsKindOf. Called in base wxWindows library initialization.

\membersection{wxClassInfo::IsKindOf}

\func{Bool}{IsKindOf}{\param{wxClassInfo *}{info}}

Returns TRUE if this class is a kind of (inherits from) the given class.


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

\overview{Interprocess communications overview}{ipcoverview}

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.

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.

\membersection{wxClient::ValidHost}

\func{Bool}{ValidHost}{\param{char *}{host}}

Returns TRUE if this is a valid host name, FALSE otherwise. This always
returns TRUE under MS Windows.

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

\func{unsigned char}{Blue}{\void}

Returns the blue intensity.

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

\func{unsigned char}{Green}{\void}

Returns the green intensity.

\membersection{wxColour::Ok}

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

Returns TRUE if the colour object is valid.

\membersection{wxColour::Red}

\func{unsigned char}{Red}{\void}

Returns the red intensity.

\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{wxCommand}: wxObject}\label{wxcommand}

\overview{Overview}{wxcommandoverview}

wxCommand is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing
a toolbar button or any other means provided by the application to
change the data or view.

\membersection{wxCommand::wxCommand}

\func{void}{wxCommand}{\param{Bool}{ canUndo = FALSE}, \param{char *}{name = NULL}}

Constructor. wxCommand is an abstract class, so you will need to derive
a new class and call this constructor from your own constructor.

{\it canUndo} tells the command processor whether this command is undo-able. You
can achieve the same functionality by overring the CanUndo member function (if for example
the criteria for undoability is context-dependant).

{\it name} must be supplied for the command processor to display the command name
in the application's edit menu.

\membersection{wxCommand::\destruct{wxCommand}}

\func{void}{\destruct{wxCommand}}{\void}

Destructor.

\membersection{wxCommand::CanUndo}

\func{Bool}{CanUndo}{\void}

Returns TRUE if the command can be undone, FALSE otherwise.

\membersection{wxCommand::Do}

\func{Bool}{Do}{\void}

Override this member function to execute the appropriate action when called.
Return TRUE to indicate that the action has taken place, FALSE otherwise.
Returning FALSE will indicate to the command processor that the action is
not undoable and should not be added to the command history.

\membersection{wxCommand::GetName}

\func{char *}{GetName}{\void}

Returns the command name.

\membersection{wxCommand::Undo}

\func{Bool}{Undo}{\void}

Override this member function to un-execute a previous Do.
Return TRUE to indicate that the action has taken place, FALSE otherwise.
Returning FALSE will indicate to the command processor that the action is
not redoable and no change should be made to the command history.

How you implement this command is totally application dependent, but typical
strategies include:

\begin{itemize}\itemsep=0pt
\item Perform an inverse operation on the last modified piece of
data in the document. When redone, a copy of data stored in command
is pasted back or some operation reapplied. This relies on the fact that
you know the ordering of Undos; the user can never Undo at an arbitrary position
in the command history.
\item Restore the entire document state (perhaps using document transactioning).
Potentially very inefficient, but possibly easier to code if the user interface
and data are complex, and an `inverse execute' operation is hard to write.
\end{itemize}

The docview sample uses the first method, to remove or restore segments
in the drawing.

\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}\rtfsp
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}\itemsep=0pt
\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{wxCommandProcessor}: wxObject}\label{wxcommandprocessor}

\overview{Overview}{wxcommandprocessoroverview}

wxCommandProcessor is a class that maintains a history of wxCommands,
with undo/redo functionality built-in. Derive a new class from this
if you want different behaviour.

\membersection{wxCommandProcessor::wxCommandProcessor}

\func{void}{wxCommandProcessor}{\param{int}{ maxCommands = 100}}

Constructor.

{\it maxCommands} defaults to a rather arbitrary 100, but can be set from 1 to any integer.
If your wxCommand classes store a lot of data, you may wish the limit the number of
commands stored to a smaller number.

\membersection{wxCommandProcessor::\destruct{wxCommandProcessor}}

\func{void}{\destruct{wxCommandProcessor}}{\void}

Destructor.

\membersection{wxCommandProcessor::CanUndo}

\func{Bool}{CanUndo}{\void}

Returns TRUE if the currently-active command can be undone, FALSE otherwise.

\membersection{wxCommandProcessor::ClearCommands}

\func{void}{ClearCommands}{\void}

Deletes all the commands in the list and sets the current command pointer to NULL.

\membersection{wxCommandProcessor::Do}

\func{Bool}{Do}{\void}

Executes (redoes) the current command (the command that has just been undone if any).

\membersection{wxCommandProcessor::GetCommands}

\func{wxList\&}{GetCommands}{\void}

Returns the list of commands.

\membersection{wxCommandProcessor::GetMaxCommands}

\func{int}{GetMaxCommands}{\void}

Returns the maximum number of commands that the command processor stores.

\membersection{wxCommandProcessor::GetEditMenu}

\func{wxMenu *}{GetEditMenu}{\void}

Returns the edit menu associated with the command processor.

\membersection{wxCommandProcessor::Initialize}

\func{void}{Initialize}{\void}

Initializes the command processor, setting the current command to the
last in the list (if any), and updating the edit menu (if one has been
specified).

\membersection{wxCommandProcessor::SetEditMenu}

\func{void}{SetEditMenu}{\param{wxMenu *}{menu}}

Tells the command processor to update the Undo and Redo items on this
menu as appropriate. Set this to NULL if the menu is about to be
destroyed and command operations may still be performed, or the command
processor may try to access an invalid pointer.

\membersection{wxCommandProcessor::Submit}

\func{Bool}{Submit}{\param{wxCommand *}{command}, \param{Bool}{ storeIt}}

Submits a new command to the command processor. The command processor
calls wxCommand::Do to execute the command; if it succeeds, the command
is stored in the history list, and the associated edit menu (if any) updated
appropriately. If it fails, the command is deleted
immediately. Once Submit has been called, the passed command should not
be deleted directly by the application.

{\it storeIt} indicates whether the successful command should be stored
in the history list.

\membersection{wxCommandProcessor::Undo}

\func{Bool}{Undo}{\void}

Undoes the command just executed.






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

\overview{Interprocess communications overview}{ipcoverview}

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 also \helpref{wxClient}{wxclient}, \helpref{wxServer}{wxserver}.

\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}\rtfsp
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}

Default constructor.

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

Construct a cursor by passing an array of bits (XView and Motif only).

\func{void}{wxCursor}{\param{char *}{cursorName}, \param{long}{flags}, \param{int}{hotSpotX=0}, \param{int}{hotSpotY=0}}

Construct a cursor by passing a string resource name or filename.
Under Motif, {\it flags} defaults to wxBITMAP\_TYPE\_XBM $\|$ wxBITMAP\_DISCARD\_COLOURMAP. Under Windows,
it defaults to  wxBITMAP\_TYPE\_CUR\_RESOURCE $\|$ wxBITMAP\_DISCARD\_COLOURMAP.

{\it hotSpotX} and {\it hotSpotY} are currently only used under Windows when loading from an
icon file, to specify the cursor hotspot relative to the top left of the image.

Under X, the permitted cursor types in the {\it flags} bitlist are:

\begin{itemize}\itemsep=0pt
%\item {\bf wxBITMAP\_TYPE\_BMP} Load a Windows bitmap file
%\item {\bf wxBITMAP\_TYPE\_BMP\_RESOURCE} Load a Windows bitmap from the resource database
%\item {\bf wxBITMAP\_TYPE\_GIF} Load a GIF bitmap file
\item {\bf wxBITMAP\_TYPE\_XBM} Load an X bitmap file
\end{itemize}

Under Windows, the permitted types are:

\begin{itemize}\itemsep=0pt
%\item {\bf wxBITMAP\_TYPE\_BMP} Load a Windows bitmap file
%\item {\bf wxBITMAP\_TYPE\_BMP\_RESOURCE} Load a Windows bitmap from the resource database
%\item {\bf wxBITMAP\_TYPE\_GIF} Load a GIF bitmap file
\item {\bf wxBITMAP\_TYPE\_CUR} Load a cursor from a .cur cursor file (only if USE\_RESOURCE\_LOADING\_IN\_MSW
is enabled in wx\_setup.h).
\item {\bf wxBITMAP\_TYPE\_CUR\_RESOURCE} Load a Windows resource (as specified in the .rc file).
\item {\bf wxBITMAP\_TYPE\_ICO} Load a cursor from a .ico icon file (only if USE\_RESOURCE\_LOADING\_IN\_MSW
is enabled in wx\_setup.h). Specify {\it hotSpotX} and {\it hotSpotY}.
\end{itemize}

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

Create a cursor by passing a stock cursor id.
The following stock cursor ids may be used:

\begin{itemize}\itemsep=0pt
\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{wxDatabase}: wxObject}\label{wxdatabase}

\overview{Overview}{wxdatabaseoverview}

Every database object represents an ODBC connection. The connection may be closed and reopened.

\membersection{wxDatabase::wxDatabase}

\func{void}{wxDatabase}{\void}

Constructor. The constructor of the first wxDatabase instance of an
application initializes the ODBC manager.

\membersection{wxDatabase::\destruct{wxDatabase}}

\func{void}{\destruct{wxDatabase}}{\void}

Destructor. Resets and destroys any associated wxRecordSet instances.

The destructor of the last wxDatabase instance will deinitialize
the ODBC manager.

\membersection{wxDatabase::BeginTrans}

\func{Bool}{BeginTrans}{\void}

Not implemented.

\membersection{wxDatabase::Cancel}

\func{void}{Cancel}{\void}

Not implemented.

\membersection{wxDatabase::CanTransact}

\func{Bool}{CanTransact}{\void}
  
Not implemented.


\membersection{wxDatabase::CanUpdate}

\func{Bool}{CanUpdate}{\void}

Not implemented.

\membersection{wxDatabase::Close}

\func{Bool}{Close}{\void}

Resets the statement handles of any associated wxRecordSet objects,
and disconnects from the current data source.

\membersection{wxDatabase::CommitTrans}

\func{Bool}{CommitTrans}{\void}

Commits previous transactions. Not implemented.

\membersection{wxDatabase::ErrorOccured}

\func{Bool}{ErrorOccured}{\void}

Returns TRUE if the last action caused an error.

\membersection{wxDatabase::ErrorSnapshot}

\func{void}{ErrorSnapshot}{\param{HSTMT}{ statement = SQL\_NULL\_HSTMT}}

This function will be called whenever an ODBC error occured. It stores the
error related information returned by ODBC. If a statement handle of the
concerning ODBC action is available it should be passed to the function.

\membersection{wxDatabase::GetDatabaseName}

\func{char *}{GetDatabaseName}{\void}

Returns the name of the database associated with the current connection.

\membersection{wxDatabase::GetDataSource}

\func{char *}{GetDataSource}{\void}

Returns the name of the connected data source.
  
\membersection{wxDatabase::GetErrorClass}

\func{char *}{GetErrorClass}{\void}

Returns the error class of the last error. The error class consists of
five characters where the first two characters contain the class
and the other three characters contain the subclass of the ODBC error.
See ODBC documentation for further details.

\membersection{wxDatabase::GetErrorCode}

\func{wxRETCODE}{GetErrorCode}{\void}

Returns the error code of the last ODBC function call. This will be one of:

\begin{twocollist}\itemsep=0pt
\twocolitem{SQL\_ERROR}{General error.}
\twocolitem{SQL\_INVALID\_HANDLE}{An invalid handle was passed to an ODBC function.}
\twocolitem{SQL\_NEED\_DATA}{ODBC expected some data.}
\twocolitem{SQL\_NO\_DATA\_FOUND}{No data was found by this ODBC call.}
\twocolitem{SQL\_SUCCESS}{The call was successful.}
\twocolitem{SQL\_SUCCESS\_WITH\_INFO}{The call was successful, but further information can be
obtained from the ODBC manager.}
\end{twocollist}

\membersection{wxDatabase::GetErrorMessage}

\func{char *}{GetErrorMessage}{\void}
  
Returns the last error message returned by the ODBC manager.

\membersection{wxDatabase::GetErrorNumber}

\func{long}{GetErrorNumber}{\void}

Returns the last native error. A native error is an ODBC driver dependent
error number.

\membersection{wxDatabase::GetHDBC}

\func{HDBC}{GetHDBC}{\void}

Returns the current ODBC database handle.

\membersection{wxDatabase::GetHENV}

\func{HENV}{GetHENV}{\void}

Returns the ODBC environment handle. 
  
\membersection{wxDatabase::GetUsername}

\func{char *}{GetUsername}{\void}

Returns the current username.

\membersection{wxDatabase::GetPassword}

\func{char *}{GetPassword}{\void}

Returns the password of the current user.

\membersection{wxDatabase::InWaitForDataSource}

\func{Bool}{InWaitForDataSource}{\void}

Not implemented.

\membersection{wxDatabase::IsOpen}

\func{Bool}{IsOpen}{\void}

Returns TRUE if a connection is open.

\membersection{wxDatabase::Open}\label{wxdatabaseopen}

\func{Bool}{Open}{\param{char *}{datasource}, \param{Bool}{ exclusive = FALSE}, \param{Bool }{readOnly = TRUE},
 \param{char *}{username = ``ODBC"}, \param{char *}{password = ``"}}

Connect to a data source. {\it datasource} contains the name of the ODBC data
source. The parameters exclusive and readOnly are not used.

\membersection{wxDatabase::OnSetOptions}

\func{void}{OnSetOptions}{\param{wxRecordSet *}{recordSet}}

Not implemented.  
  
\membersection{wxDatabase::OnWaitForDataSource}

\func{void}{OnWaitForDataSource}{\param{Bool}{ stillExecuting}}

Not implemented.

\membersection{wxDatabase::RollbackTrans}

\func{Bool}{RollbackTrans}{\void}

Sends a rollback to the ODBC driver. Not implemented.

\membersection{wxDatabase::SetDataSource}

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

Sets the name of the data source. Not implemented.
  
\membersection{wxDatabase::SetLoginTimeout}

\func{void}{SetLoginTimeout}{\param{long}{ seconds}}

Sets the time to wait for an user login. Not implemented.
  
\membersection{wxDatabase::SetPassword}

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

Sets the password of the current user. Not implemented.

\membersection{wxDatabase::SetSynchronousMode}

\func{void}{SetSynchronousMode}{\param{Bool }{synchronous}}

Toggles between synchronous and asynchronous mode. Currently only synchronous
mode is supported, so this function has no effect.

\membersection{wxDatabase::SetQueryTimeout}

\func{void}{SetQueryTimeout}{\param{long}{ seconds}}

Sets the time to wait for a response to a query. Not implemented.
 
\membersection{wxDatabase::SetUsername}

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

Sets the name of the current user. Not implemented.


\section{\class{wxDC}: wxObject}\label{wxdc}

\overview{Overview}{dcoverview}

A wxDC is a {\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.

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.

Drawing to a wxDialogBox panel device context outside of a
system-generated OnPaint event {\it requires} this pair of calls to
enclose drawing code. This is because a Windows dialog box does not have
a retained device context associated with it, and selections such as pen
and brush settings would be lost if the device context were obtained and
released for each drawing operation.

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

Clears the device context using the current background brush.

\membersection{wxDC::CrossHair}\label{wxdccrosshair}

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

Displays a cross hair using the current pen. This is a vertical
and horizontal line the height and width of the canvas, centred
on the given point.

\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::DeviceToLogicalXRel}\label{wxdcdevicetologicalxrel}

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

Convert device X coordinate to relative logical coordinate, using the current
mapping mode. Use this function for converting a width, for example.

\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::DeviceToLogicalYRel}\label{wxdcdevicetologicalyrel}

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

Convert device Y coordinate to relative logical coordinate, using the current
mapping mode. Use this function for converting a height, for example.

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

\func{void}{FloodFill}{\param{float}{ x}, \param{float}{ y}, \param{wxColour *}{colour}, \param{int}{ style=wxFLOOD\_SURFACE}}

Flood fills the device context starting from the given point, in the given colour,
and using a style:

\begin{itemize}\itemsep=0pt
\item wxFLOOD\_SURFACE: the flooding occurs until a colour other than the given colour is encountered.
\item wxFLOOD\_BORDER: the area to be flooded is bounded by the given colour.
\end{itemize}

{\it Note:} this function is available in MS Windows only.

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

\func{float}{GetCharHeight}{\void}

Gets the character height of the currently set font.

\membersection{wxDC::GetCharWidth}

\func{float}{GetCharWidth}{\void}

Gets the average character width of the currently set font.

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

\func{Bool}{GetOptimization}{\void}

Returns TRUE if device context optimization is on.
See \helpref{wxDC::SetOptimization}{wxsetoptimization} for details.

\membersection{wxDC::GetPen}

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

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

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

\func{void}{GetSize}{\param{float *}{width}, \param{float *}{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}\rtfsp
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::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}, \param{wxFont *}{font = 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).

The optional parameter {\it font} specifies an alternative
to the currently selected font: but note that this does not
yet work under Windows, so you need to set a font for
the device context first.

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

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

Converts logical X coordinate to relative device coordinate, using the current
mapping mode. Use this for converting a width, for example.

\membersection{wxDC::LogicalToDeviceY}

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

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

\membersection{wxDC::LogicalToDeviceYRel}

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

Converts logical Y coordinate to relative device coordinate, using the current
mapping mode. Use this for converting a height, for example.

\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::SetDeviceOrigin}\label{wxdcsetdeviceorigin}

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

Sets the device origin (i.e., the origin in pixels after scaling has been
applied).

This function may be useful in Windows printing
operations for placing a graphic on a page.

\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::SetOptimization}\label{wxsetoptimization}

\func{void}{SetOptimization}{\param{Bool }{optimize}}

If {\it optimize} is TRUE (the default), this function sets optimization mode on.
This currently means that under X, the device context will not try to set a pen or brush
property if it is known to be set already. This approach can fall down
if non-wxWindows code is using the same device context or window, for example
when the window is a panel on which the windowing system draws panel items.
The wxWindows device context 'memory' will now be out of step with reality.

Setting optimization off, drawing, then setting it back on again, is a trick
that must occasionally be employed.

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

\overview{Overview}{wxdebugcontextoverview}

A class for performing various debugging and memory tracing
operations. Only present in a debugging build of wxWindows,
i.e. if the DEBUG symbol is defined and non-zero.

\membersection{wxDebugContext::Check}

\func{int}{Check}{\void}

Checks the memory blocks for errors, starting from the currently set
checkpoint. Returns the number of errors,
so a value of zero represents success.

Returns -1 if an error was detected that prevents further checking.

\membersection{wxDebugContext::Dump}

\func{Bool}{Dump}{\void}

Performs a memory dump from the currently set checkpoint, writing to the
current debug stream. Calls the Dump member function for each wxObject
derived instance.

\membersection{wxDebugContext::GetCheckPrevious}

\func{Bool}{GetCheckPrevious}{\void}

Returns TRUE if the memory allocator checks all previous memory blocks for errors.
By default, this is FALSE since it slows down execution considerably.

\membersection{wxDebugContext::GetDebugMode}

\func{Bool}{GetDebugMode}{\void}

Returns TRUE if debug mode is on. If debug mode is on, the wxObject new and delete
operators store or use information about memory allocation. Otherwise,
a straight malloc and free will be performed by these operators.

\membersection{wxDebugContext::GetLevel}

\func{int}{GetLevel}{\void}

Gets the debug level (default 1). The debug level is used by the wxTraceLevel function and
the TRACELEVEL macro to specify how detailed the trace information is; setting
a different level will only have an effect if trace statements in the application
specify a value other than one.

\membersection{wxDebugContext::GetStream}

\func{ostream\&}{GetStream}{\void}

Returns the output stream associated with the debug context.

\membersection{wxDebugContext::GetStreamBuf}

\func{streambuf *}{GetStreamBuf}{\void}

Returns a pointer to the output stream buffer associated with the debug context.
There may not necessarily be a stream buffer if the stream has been set
by the user.

\membersection{wxDebugContext::HasStream}

\func{Bool}{HasStream}{\void}

Returns TRUE if there is a stream currently associated
with the debug context.

\membersection{wxDebugContext::PrintClasses}

\func{Bool}{PrintClasses}{\void}

Prints a list of the classes declared in this application, giving derivation
and whether instances of this class can be dynamically created.

\membersection{wxDebugContext::PrintStatistics}

\func{Bool}{PrintStatistics}{\param{Bool}{ detailed = TRUE}}

Performs a statistics analysis from the currently set checkpoint, writing
to the current debug stream. The number of object and non-object
allocations is printed, together with the total size.

If {\it detailed} is TRUE, the function will also print how many
objects of each class have been allocated, and the space taken by
these class instances.


\membersection{wxDebugContext::SetCheckpoint}

\func{void}{SetCheckpoint}{\param{Bool}{ all = FALSE}}

Sets the current checkpoint: Dump and PrintStatistics operations will
be performed from this point on. This allows you to ignore allocations
that have been performed up to this point.

If {\it all} is TRUE, the checkpoint is reset to include all
memory allocations since the program started.

\membersection{wxDebugContext::SetDebugMode}

\func{void}{SetDebugMode}{\param{Bool}{ debug}}

Sets the debug mode on or off. If debug mode is on, the wxObject new and delete
operators store or use information about memory allocation. Otherwise,
a straight malloc and free will be performed by these operators.

By default, debug mode is on if DEBUG is non-zero. If the application
uses this function, it should make sure that all object memory allocated
is deallocated with the same value of debug mode. Otherwise, the
delete operator might try to look for memory information that does not
exist.

\membersection{wxDebugContext::SetFile}

\func{Bool}{SetFile}{\param{char *}{filename}}

Sets the current debug file and creates a stream. This will delete any existing
stream and stream buffer. By default, the debug context stream
outputs to the debugger (Windows) or standard error (other platforms).

\membersection{wxDebugContext::SetLevel}

\func{void}{SetLevel}{\param{int}{ level}}

Sets the debug level (default 1). The debug level is used by the wxTraceLevel function and
the TRACELEVEL macro to specify how detailed the trace information is; setting
a different level will only have an effect if trace statements in the application
specify a value other than one.

\membersection{wxDebugContext::SetCheckPrevious}

\func{void}{SetCheckPrevious}{\param{Bool}{ check}}

Tells the memory allocator to check all previous memory blocks for errors.
By default, this is FALSE since it slows down execution considerably.

\membersection{wxDebugContext::SetStandardError}

\func{Bool}{SetStandardError}{\void}

Sets the debugging stream to be the debugger (Windows) or standard error (other platforms).
This is the default setting. The existing stream will be flushed and deleted.

\membersection{wxDebugContext::SetStream}

\func{void}{SetStream}{\param{ostream *}{stream}, \param{streambuf *}{streamBuf = NULL}}

Sets the stream and optionally, stream buffer associated with the debug context.
This operation flushes and deletes the existing stream (and stream buffer if any).

Do not set this to NULL.


\section{\class{wxDebugStreamBuf}: streambuf}\label{wxdebugstreambuf}

This class allows you to treat debugging output in a similar
(stream-based) fashion on different platforms. Under
Windows, an ostream constructed with this buffer outputs
to the debugger, or other program that intercepts debugging
output. On other platforms, the output goes to standard error (cerr).

For example:

\begin{verbatim}
  wxDebugStreamBuf streamBuf;
  ostream stream(&streamBuf);

  stream << "Hello world!" << endl;
\end{verbatim}


\section{\class{wxDialogBox}: wxPanel}\label{wxdialogbox}

\overview{Overview}{wxdialogboxoverview}

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}

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{wxCAPTION}{Puts a caption on the dialog box (Motif only).}
\twocolitem{wxDEFAULT\_DIALOG\_STYLE}{Equivalent to wxCAPTION $\|$ wxSYSTEM\_MENU $\|$ wxTHICK\_FRAME}
\twocolitem{wxRESIZE\_BORDER}{Display a resizeable frame around the window (Motif only).}
\twocolitem{wxSYSTEM\_MENU}{Display a system menu (Motif only).}
\twocolitem{wxTHICK\_FRAME}{Display a thick frame around the window (Motif only).}
\twocolitem{wxUSER\_COLOURS}{Under Windows, overrides standard control
processing to allow setting of the dialog box background colour.}
\twocolitem{wxVSCROLL}{Give the dialog box a vertical scrollbar (XView only).}
\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 =  = wxDEFAULT\_DIALOG\_STYLE},\\
  \param{char *}{name = ``dialogBox"}}

Used for two-step dialog box construction. See \helpref{wxDialogBox::wxDialogBox}{constrdialog}\rtfsp
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::OnCharHook}\label{wxdialogboxoncharhook}

\func{Bool}{OnCharHook}{\param{wxKeyEvent\&}{ ch}}

This member is called (under Windows only) to allow the window to intercept keyboard events
before they are processed by child windows. The window receives this event from
the default \helpref{wxApp::OnCharHook}{wxapponcharhook} member function if the window
(frame or dialog box) is active. The function should returns TRUE to indicate the
character has been processed, or FALSE to allow default processing. The default
implementation for wxWindow returns FALSE, but the wxDialogBox implementation
checks for WXK\_ESCAPE, calls OnClose and if this returns TRUE, deletes the dialog box.

See also \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxEvtHandler::OnChar}{wxevthandleronchar},\rtfsp
\helpref{wxEvtHandler::OnCharHook}{wxevthandleroncharhook}.

\membersection{wxDialogBox::SetTitle}

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

Sets the title of the dialog box.

\membersection{wxDialogBox::Show}

\func{Bool}{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{wxDocChildFrame}: wxFrame}\label{wxdocchildframe}

\overview{Document/view overview}{docviewoverview}

The wxDocChildFrame class provides a default frame for displaying documents
on separate windows.

The class is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument},
\rtfsp\helpref{wxDocManager}{wxdocmanager} and \helpref{wxDocTemplate}{wxdoctemplate} classes.

See the example application in {\tt samples/docview}.

\membersection{wxDocChildFrame::childDocument}

\member{wxDocument *}{childDocument}

The document associated with the frame.

\membersection{wxDocChildFrame::childView}

\member{wxView *}{childView}

The view associated with the frame.

\membersection{wxDocChildFrame::wxDocChildFrame}

\func{void}{wxDocChildFrame}{\param{wxDocument *}{doc}, \param{wxView *}{view}, \param{wxFrame *}{parent},
 \param{char *}{title}, \param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height},
 \param{long}{ style}, \param{char *}{name}}

Constructor.

\membersection{wxDocChildFrame::\destruct{wxDocChildFrame}}

\func{void}{\destruct{wxDocChildFrame}}{\void}

Destructor.

\membersection{wxDocChildFrame::GetDocument}

\func{wxDocument *}{GetDocument}{\void}

Returns the document associated with this frame.

\membersection{wxDocChildFrame::GetView}

\func{wxView *}{GetView}{\void}

Returns the view associated with this frame.

\membersection{wxDocChildFrame::OnActivate}

\func{void}{OnActivate}{\param{Bool}{ active}}

Sets the currently active view to be the frame's view. You may need
to override (but still call) this function in order to set the keyboard
focus for your subwindow.

\membersection{wxDocChildFrame::OnClose}

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

Closes and deletes the current view and document.

\membersection{wxDocChildFrame::OnMenuCommand}

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

Passes menu commands to the parent frame (assumed to be a wxDocParentFrame).

\membersection{wxDocChildFrame::SetDocument}

\func{void}{SetDocument}{\param{wxDocument *}{doc}}

Sets the document for this frame.

\membersection{wxDocChildFrame::SetView}

\func{void}{SetView}{\param{wxView *}{view}}

Sets the view for this frame.



\section{\class{wxDocManager}: wxEvtHandler}\label{wxdocmanager}

\overview{Overview}{wxdocmanageroverview}

The wxDocManager class is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp
and \helpref{wxDocTemplate}{wxdoctemplate} classes.

\membersection{wxDocManager::currentView}

\member{wxView *}{currentView}

The currently active view.

\membersection{wxDocManager::defaultDocumentNameCounter}

\member{int}{defaultDocumentNameCounter}

Stores the integer to be used for the next default document name.

\membersection{wxDocManager::fileHistory}

\member{wxFileHistory *}{fileHistory}

A pointer to an instance of \helpref{wxFileHistory}{wxfilehistory},
which manages the history of recently-visited files on the File menu.

\membersection{wxDocManager::maxDocsOpen}

\member{int}{maxDocsOpen}

Stores the maximum number of documents that can be opened before
existing documents are closed. By default, this is 10,000.

\membersection{wxDocManager::mnDocs}

\member{wxList}{mnDocs}

A list of all documents.

\membersection{wxDocManager::mnFlags}

\member{long}{mnFlags}

Stores the flags passed to the constructor.

\membersection{wxDocManager::mnTemplates}

\member{wxList}{mnTemplates}

A list of all document templates.

\membersection{wxDocManager::wxDocManager}

\func{void}{wxDocManager}{\param{long}{ flags = wxDEFAULT\_DOCMAN\_FLAGS}, \param{Bool}{ initialize = TRUE}}

Constructor. Create a document manager instance dynamically near the start of your application
before doing any document or view operations.

{\it flags} is currently unused.

If {\it initialize} is TRUE, the \helpref{Initialize}{wxdocmanagerinitialize} function will be called
to create a default history list object. If you derive from wxDocManager, you may wish to call the
base constructor with FALSE, and then call Initialize in your own constructor, to allow
your own Initialize or OnCreateFileHistory functions to be called.

\membersection{wxDocManager::\destruct{wxDocManager}}

\func{void}{\destruct{wxDocManager}}{\void}

Destructor.

\membersection{wxDocManager::ActivateView}

\func{void}{ActivateView}{\param{wxView *}{doc}, \param{Bool}{ activate}, \param{Bool}{ deleting}}

Sets the current view.

\membersection{wxDocManager::AddDocument}

\func{void}{AddDocument}{\param{wxDocument *}{doc}}

Adds the document to the list of documents.

\membersection{wxDocManager::AddFileToHistory}

\func{void}{AddFileToHistory}{\param{char *}{filename}}

Adds a file to the file history list, if we have a pointer to an appropriate file menu.

\membersection{wxDocManager::AssociateTemplate}

\func{void}{AssociateTemplate}{\param{wxDocTemplate *}{temp}}

Adds the template to the document manager's template list.

\membersection{wxDocManager::CreateDocument}

\func{wxDocument *}{CreateDocument}{\param{char *}{path}, \param{long}{ flags}}

Creates a new document in a manner determined by the {\it flags} parameter, which can be:

\begin{itemize}\itemsep=0pt
\item wxDOC\_NEW Creates a fresh document.
\item wxDOC\_SILENT Silently loads the given document file.
\end{itemize}

If wxDOC\_NEW is present, a new document will be created and returned, possibly after
asking the user for a template to use if there is more than one document template.
If wxDOC\_SILENT is present, a new document will be created and the given file loaded
into it. If neither of these flags is present, the user will be presented with
a file selector for the file to load, and the template to use will be determined by the
extension (Windows) or by popping up a template choice list (other platforms).

If the maximum number of documents has been reached, this function
will delete the oldest currently loaded document before creating a new one.

\membersection{wxDocManager::CreateView}

\func{wxView *}{CreateView}{\param{wxDocument *}{doc}, \param{long}{ flags}}

Creates a new view for the given document. If more than one view is allowed for the
document (by virtue of multiple templates mentioning the same document type), a choice
of view is presented to the user.

\membersection{wxDocManager::DisassociateTemplate}

\func{void}{DisassociateTemplate}{\param{wxDocTemplate *}{temp}}

Removes the template from the list of templates.

\membersection{wxDocManager::FileHistoryLoad}

\func{void}{FileHistoryLoad}{\param{char *}{resourceFile}, \param{char *}{sectionName}}

Loads the file history from a resource file, using the given section. This must be called
explicitly by the application.

\membersection{wxDocManager::FileHistorySave}

\func{void}{FileHistorySave}{\param{char *}{resourceFile}, \param{char *}{sectionName}}

Saves the file history into a resource file, using the given section. This must be called
explicitly by the application.

\membersection{wxDocManager::FileHistoryUseMenu}

\func{void}{FileHistoryUseMenu}{\param{wxMenu *}{menu}}

Use this menu for appending recently-visited document filenames, for convenient
access. Calling this function with a valid menu pointer enables the history
list functionality.

\membersection{wxDocManager::FindTemplateForPath}

\func{wxDocTemplate *}{FindTemplateForPath}{\param{char *}{path}}

Given a path, try to find template that matches the extension. This is only
an approximate method of finding a template for creating a document.

\membersection{wxDocManager::GetCurrentDocument}

\func{wxDocument *}{GetCurrentDocument}{\void}

Returns the document associated with the currently active view (if any).

\membersection{wxDocManager::GetCurrentView}

\func{wxView *}{GetCurrentView}{\void}

Returns the currently active view 

\membersection{wxDocManager::GetDocuments}

\func{wxList\&}{GetDocuments}{\void}

Returns a reference to the list of documents.

\membersection{wxDocManager::GetFileHistory}

\func{wxFileHistory *}{GetFileHistory}{\void}

Returns a pointer to file history.

\membersection{wxDocManager::GetMaxDocsOpen}

\func{int}{GetMaxDocsOpen}{\void}

Returns the number of documents that can be open simultaneously.

\membersection{wxDocManager::GetNoHistoryFiles}

\func{int}{GetNoHistoryFiles}{\void}

Returns the number of files currently stored in the file history.

\membersection{wxDocManager::Initialize}\label{wxdocmanagerinitialize}

\func{Bool}{Initialize}{\void}

Initializes data; currently just calls OnCreateFileHistory. Some data cannot
always be initialized in the constructor because the programmer must be given
the opportunity to override functionality. If OnCreateFileHistory was called
from the constructor, an overridden virtual OnCreateFileHistory would not be
called due to C++'s `interesting' constructor semantics. In fact Initialize
\rtfsp{\it is} called from the wxDocManager constructor, but this can be
vetoed by passing FALSE to the second argument, allowing the derived class's
constructor to call Initialize, possibly calling a different OnCreateFileHistory
from the default.

The bottom line: if you're not deriving from Initialize, forget it and
construct wxDocManager with no arguments.

\membersection{wxDocManager::MakeDefaultName}

\func{Bool}{MakeDefaultName}{\param{char *}{buf}}

Copies a suitable default name into {\it buf}. This is implemented by
appending an integer counter to the string {\bf unnamed} and incrementing
the counter.

\membersection{wxDocManager::OnCreateFileHistory}

\func{wxFileHistory *}{OnCreateFileHistory}{\void}

A hook to allow a derived class to create a different type of file history. Called
from \helpref{Initialize}{wxdocmanagerinitialize}.

\membersection{wxDocManager::OnFileClose}

\func{void}{OnFileClose}{\void}

Closes and deletes the currently active document.

\membersection{wxDocManager::OnFileNew}

\func{void}{OnFileNew}{\void}

Creates a document from a list of templates (if more than one template).

\membersection{wxDocManager::OnFileOpen}

\func{void}{OnFileOpen}{\void}

Creates a new document and reads in the selected file.

\membersection{wxDocManager::OnFileSave}

\func{void}{OnFileSave}{\void}

Saves the current document by calling wxDocument::Save for the current document.

\membersection{wxDocManager::OnFileSaveAs}

\func{void}{OnFileSaveAs}{\void}

Calls wxDocument::SaveAs for the current document.

\membersection{wxDocManager::OnMenuCommand}

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

Processes menu commands routed from child or parent frames. This deals
with the following predefined menu item identifiers:

\begin{itemize}\itemsep=0pt
\item wxID\_OPEN Creates a new document and opens a file into it.
\item wxID\_CLOSE Closes the current document.
\item wxID\_NEW Creates a new document.
\item wxID\_SAVE Saves the document.
\item wxID\_SAVE\_AS Saves the document into a specified filename.
\end{itemize}

Unrecognized commands are routed to the currently active wxView's OnMenuCommand.

\membersection{wxDocManager::RemoveDocument}

\func{void}{RemoveDocument}{\param{wxDocument *}{doc}}

Removes the document from the list of documents.

\membersection{wxDocManager::SelectDocumentPath}

\func{wxDocTemplate *}{SelectDocumentPath}{\param{wxDocTemplate **}{templates},
 \param{int}{ noTemplates}, \param{char *}{path}, \param{char *}{bufSize},
 \param{long}{ flags}, \param{Bool}{ save}}

Under Windows, pops up a file selector with a list of filters corresponding to document templates.
The wxDocTemplate corresponding to the selected file's extension is returned.

On other platforms, if there is more than one document template a choice list is popped up,
followed by a file selector.

This function is used in wxDocManager::CreateDocument.

\membersection{wxDocManager::SelectDocumentType}

\func{wxDocTemplate *}{SelectDocumentType}{\param{wxDocTemplate **}{templates},
 \param{int}{ noTemplates}}

Returns a document template by asking the user (if there is more than one template).
This function is used in wxDocManager::CreateDocument.

\membersection{wxDocManager::SelectViewType}

\func{wxDocTemplate *}{SelectViewType}{\param{wxDocTemplate **}{templates},
 \param{int}{ noTemplates}}

Returns a document template by asking the user (if there is more than one template),
displaying a list of valid views. This function is used in wxDocManager::CreateView.
The dialog normally won't appear because the array of templates only contains
those relevant to the document in question, and often there will only be one such.

\membersection{wxDocManager::SetMaxDocsOpen}

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

Sets the maximum number of documents that can be open at a time. By default, this
is 10,000. If you set it to 1, existing documents will be saved and deleted
when the user tries to open or create a new one (similar to the behaviour
of Windows Write, for example). Allowing multiple documents gives behaviour
more akin to MS Word and other Multiple Document Interface applications.



\section{\class{wxDocParentFrame}: wxFrame}\label{wxdocparentframe}

\overview{Document/view overview}{docviewoverview}

The wxDocParentFrame class provides a default top-level frame for
applications using the document/view framework.

It cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument},
\rtfsp\helpref{wxDocManager}{wxdocmanager} and \helpref{wxDocTemplates}{wxdoctemplate} classes.

See the example application in {\tt samples/docview}.

\membersection{wxDocParentFrame::wxDocParentFrame}

\func{void}{wxDocParentFrame}{\param{wxFrame *}{parent},
 \param{char *}{title}, \param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height},
 \param{long}{ style}, \param{char *}{name}}

Constructor.

\membersection{wxDocParentFrame::\destruct{wxDocParentFrame}}

\func{void}{\destruct{wxDocManager}}{\void}

Destructor.

\membersection{wxDocParentFrame::OnClose}

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

Deletes all views and documents. If no user input cancelled the
operation, the function returns TRUE and the application will exit.

Since understanding how document/view clean-up takes place can be difficult,
the implementation of this function is shown below.

\begin{verbatim}
Bool wxDocParentFrame::OnClose(void)
{
  // Delete all views and documents
  wxNode *node = docManager->GetDocuments().First();
  while (node)
  {
    wxDocument *doc = (wxDocument *)node->Data();
    wxNode *next = node->Next();

    if (!doc->Close())
      return FALSE;

    // Implicitly deletes the document when the last
    // view is removed (deleted)
    doc->DeleteAllViews();

    // Check document is deleted
    if (docManager->GetDocuments().Member(doc))
      delete doc;

    // This assumes that documents are not connected in
    // any way, i.e. deleting one document does NOT
    // delete another.
    node = next;
  }
  return TRUE;
}
\end{verbatim}

\membersection{wxDocParentFrame::OnMenuCommand}

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

Processes the wxID\_EXIT and wxID\_FILEn (file history) commands.
Other commands are routed to wxDocManager::OnMenuCommand.


\section{\class{wxDocTemplate}: wxObject}\label{wxdoctemplate}

\overview{Overview}{wxdoctemplateoverview}

The wxDocTemplate class is used to model the relationship between a
document class and a view class.

\membersection{wxDocTemplate::tDefaultExt}

\member{char *}{tDefaultExt}

The default extension for files of this type.

\membersection{wxDocTemplate::tDescription}

\member{char *}{tDescription}

A short description of this template.

\membersection{wxDocTemplate::tDirectory}

\member{char *}{tDirectory}

The default directory for files of this type.

\membersection{wxDocTemplate::tDocClassInfo}

\member{wxClassInfo *}{tDocClassInfo}

Run-time class information that allows document instances to be constructed dynamically.

\membersection{wxDocTemplate::tDocTypeName}

\member{char *}{tDocTypeName}

The named type of the document associated with this template.

\membersection{wxDocTemplate::tDocumentManager}

\member{wxDocTemplate *}{tDocumentManager}

A pointer to the document manager for which this template was created.

\membersection{wxDocTemplate::tFileFilter}

\member{char *}{tFileFilter}

The file filter (such as \verb$*.txt$) to be used in file selector dialogs.

\membersection{wxDocTemplate::tFlags}

\member{long}{tFlags}

The flags passed to the constructor.

\membersection{wxDocTemplate::tViewClassInfo}

\member{wxClassInfo *}{tViewClassInfo}

Run-time class information that allows view instances to be constructed dynamically.

\membersection{wxDocTemplate::tViewTypeName}

\member{char *}{tViewTypeName}

The named type of the view associated with this template.

\membersection{wxDocTemplate::wxDocTemplate}

\func{void}{wxDocTemplate}{\param{wxDocManager *}{manager}, \param{char *}{descr}, \param{char *}{filter},
 \param{char *}{dir}, \param{char *}{ext}, \param{char *}{docTypeName},
 \param{char *}{viewTypeName}, \param{wxClassInfo *}{docClassInfo = NULL},
 \param{wxClassInfo *}{viewClassInfo = NULL}, \param{long}{ flags = wxDEFAULT\_TEMPLATE\_FLAGS}}

Constructor. Create instances dynamically near the start of your application after creating
a wxDocManager instance, and before doing any document or view operations.

{\it manager} is the document manager object which manages this template.

{\it descr} is a short description of what the template is for. This string will be displayed in the
file filter list of Windows file selectors.

{\it filter} is an appropriate file filter such as \verb$*.txt$.

{\it dir} is the default directory to use for file selectors.

{\it ext} is the default file extension (such as txt).

{\it docTypeName} is a name that should be unique for a given type of document, used for
gathering a list of views relevant to a particular document.

{\it viewTypeName} is a name that should be unique for a given view.

{\it docClassInfo} is a pointer to the run-time document class information as returned
by the CLASSINFO macro, e.g. CLASSINFO(MyDocumentClass). If this is not supplied,
you will need to derive a new wxDocTemplate class and override the CreateDocument
member to return a new document instance on demand.

{\it viewClassInfo} is a pointer to the run-time view class information as returned
by the CLASSINFO macro, e.g. CLASSINFO(MyViewClass). If this is not supplied,
you will need to derive a new wxDocTemplate class and override the CreateView
member to return a new view instance on demand.

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

\begin{itemize}\itemsep=0pt
\item wxTEMPLATE\_VISIBLE The template may be displayed to the user in dialogs.
\item wxTEMPLATE\_INVISIBLE The template may not be displayed to the user in dialogs.
\item wxDEFAULT\_TEMPLATE\_FLAGS Defined as wxTEMPLATE\_VISIBLE.
\end{itemize}

\membersection{wxDocTemplate::\destruct{wxDocTemplate}}

\func{void}{\destruct{wxDocTemplate}}{\void}

Destructor.

\membersection{wxDocTemplate::CreateDocument}

\func{wxDocument *}{CreateDocument}{\param{char *}{path}, \param{long}{flags = 0}}

Creates a new instance of the associated document class. If you have not supplied
a wxClassInfo parameter to the template constructor, you will need to override this
function to return an appropriate document instance.

\membersection{wxDocTemplate::CreateView}

\func{wxView *}{CreateView}{\param{wxDocument *}{doc}, \param{long}{flags = 0}}

Creates a new instance of the associated view class. If you have not supplied
a wxClassInfo parameter to the template constructor, you will need to override this
function to return an appropriate view instance.

\membersection{wxDocTemplate::GetDefaultExtension}

\func{char *}{GetDefaultExtension}{\void}

Returns the default file extension for the document data, as passed to the document template constructor.

\membersection{wxDocTemplate::GetDescription}

\func{char *}{GetDescription}{\void}

Returns the text description of this template, as passed to the document template constructor.

\membersection{wxDocTemplate::GetDirectory}

\func{char *}{GetDirectory}{\void}

Returns the default directory, as passed to the document template constructor.

\membersection{wxDocTemplate::GetDocumentManager}

\func{wxDocManager *}{GetDocumentManager}{\void}

Returns a pointer to the document manager instance for which this template was created.

\membersection{wxDocTemplate::GetDocumentName}

\func{char *}{GetDocumentName}{\void}

Returns the document type name, as passed to the document template constructor.

\membersection{wxDocTemplate::GetFileFilter}

\func{char *}{GetFileFilter}{\void}

Returns the file filter, as passed to the document template constructor.

\membersection{wxDocTemplate::GetFlags}

\func{long}{GetFlags}{\void}

Returns the flags, as passed to the document template constructor.

\membersection{wxDocTemplate::GetViewName}

\func{char *}{GetViewName}{\void}

Returns the view type name, as passed to the document template constructor.

\membersection{wxDocTemplate::IsVisible}

\func{Bool}{IsVisible}{\void}

Returns TRUE if the document template can be shown in user dialogs, FALSE otherwise.

\membersection{wxDocTemplate::SetDefaultExtension}

\func{void}{SetDefaultExtension}{\param{char *}{ext}}

Sets the default file extension.

\membersection{wxDocTemplate::SetDescription}

\func{void}{SetDescription}{\param{char *}{descr}}

Sets the template description.

\membersection{wxDocTemplate::SetDirectory}

\func{void}{SetDirectory}{\param{char *}{dir}}

Sets the default directory.

\membersection{wxDocTemplate::SetDocumentManager}

\func{void}{SetDocumentManager}{\param{wxDocManager *}{manager}}

Sets the pointer to the document manager instance for which this template was created.
Should not be called by the application.

\membersection{wxDocTemplate::SetFileFilter}

\func{void}{SetFileFilter}{\param{char *}{filter}}

Sets the file filter.

\membersection{wxDocTemplate::SetFlags}

\func{void}{SetFlags}{\param{long }{flags}}

Sets the internal document template flags (see the constructor description for more details).

\section{\class{wxDocument}: wxEvtHandler}\label{wxdocument}

\overview{Overview}{wxdocumentoverview}

The document class can be used to model an application's file-based
data. It is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}\rtfsp
and \helpref{wxDocManager}{wxdocmanager} classes.

\membersection{wxDocument::documentFile}

\member{char *}{documentFile}

Filename associated with this document (NULL if none).

\membersection{wxDocument::documentModified}

\member{Bool}{documentModified}

TRUE if the document has been modified, FALSE otherwise.

\membersection{wxDocument::documentTemplate}

\member{wxDocTemplate *}{documentTemplate}

A pointer to the template from which this document was created.

\membersection{wxDocument::documentTitle}

\member{char *}{documentTitle}

Document title (may be NULL). The document title is used for an associated
frame (if any), and is usually constructed by the framework from
the filename.

\membersection{wxDocument::documentTypeName}\label{documenttypename}

\member{char *}{documentTypeName}

The document type name given to the wxDocTemplate constructor, copied to this
variable when the document is created. If several document templates are
created that use the same document type, this variable is used in wxDocManager::CreateView
to collate a list of alternative view types that can be used on this kind of
document. Do not change the value of this variable.

\membersection{wxDocument::documentViews}

\member{wxList}{documentViews}

List of wxView instances associated with this document.

\membersection{wxDocument::wxDocument}

\func{void}{wxDocument}{\void}

Constructor. Define your own default constructor to initialize application-specific
data.

\membersection{wxDocument::\destruct{wxDocument}}

\func{void}{\destruct{wxDocument}}{\void}

Destructor. Removes itself from the document manager.

\membersection{wxDocument::AddView}

\func{Bool}{AddView}{\param{wxView *}{view}}

If the view is not already in the list of views, adds the view and calls OnChangedViewList.

\membersection{wxDocument::Close}

\func{Bool}{Close}{\void}

Closes the document, by calling OnSaveModified and then (if this returned TRUE) OnCloseDocument.
This does not normally delete the document object: use DeleteAllViews to do this implicitly.

\membersection{wxDocument::DeleteAllViews}

\func{Bool}{DeleteAllViews}{\void}

Calls wxView::Close and deletes each view. Deleting the final view will implicitly
delete the document itself, because the wxView destructor calls RemoveView. This
in turns calls wxDocument::OnChangedViewList, whose default implemention is to
save and delete the document if no views exist.

\membersection{wxDocument::GetCommandProcessor}

\func{wxCommandProcessor *}{GetCommandProcessor}{\void}

Returns a pointer to the command processor associated with this document.

See \helpref{wxCommandProcessor}{wxcommandprocessor}.

\membersection{wxDocument::GetDocumentTemplate}

\func{wxDocTemplate *}{GetDocumentTemplate}{\void}

Gets a pointer to the template that created the document.

\membersection{wxDocument::GetDocumentManager}

\func{wxDocManager *}{GetDocumentManager}{\void}

Gets a pointer to the associated document manager.

\membersection{wxDocument::GetDocumentName}

\func{char *}{GetDocumentName}{\void}

Gets the document type name for this document. See the comment for \helpref{documentTypeName}{documenttypename}.

\membersection{wxDocument::GetDocumentWindow}

\func{wxWindow *}{GetDocumentWindow}{\void}

Intended to return a suitable window for using as a parent for document-related
dialog boxes. By default, uses the frame associated with the first view.

\membersection{wxDocument::GetFilename}

\func{char *}{GetFilename}{\void}

Gets the filename associated with this document, or NULL if none is
associated.

\membersection{wxDocument::GetFirstView}

\func{wxView *}{GetFirstView}{\void}

A convenience function to get the first view for a document, because
in many cases a document will only have a single view.

\membersection{wxDocument::GetPrintableName}

\func{void}{GetPrintableName}{\param{char *}{name}}

Copies a suitable document name into the supplied {\it name} buffer. The default
function uses the title, or if there is no title, uses the filename; or if no
filename, the string {\bf unnamed}. 

\membersection{wxDocument::GetTitle}

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

Gets the title for this document. The document title is used for an associated
frame (if any), and is usually constructed by the framework from
the filename.

\membersection{wxDocument::IsModified}\label{wxdocumentismodified}

\func{Bool}{IsModified}{\void}

Returns TRUE if the document has been modified since the last save, FALSE otherwise.
You may need to override this if your document view maintains its own
record of being modified (for example if using wxTextWindow to view and edit the document).

See also \helpref{Modify}{wxdocumentmodify}.

\membersection{wxDocument::LoadObject}

\func{istream\&}{LoadObject}{\param{istream\& }{stream}}

Override this function and call it from your own LoadObject before
streaming your own data. LoadObject is called by the framework
automatically when the document contents need to be loaded.

\membersection{wxDocument::Modify}\label{wxdocumentmodify}

\func{void}{IsModify}{\param{Bool}{ modify}}

Call with TRUE to mark the document as modified since the last save, FALSE otherwise.
You may need to override this if your document view maintains its own
record of being modified (for example if using wxTextWindow to view and edit the document).

See also \helpref{IsModified}{wxdocumentismodified}.

\membersection{wxDocument::OnChangedViewList}

\func{void}{OnChangedViewList}{\void}

Called when a view is added to or deleted from this document. The default
implementation saves and deletes the document if no views exist (the last
one has just been removed).

\membersection{wxDocument::OnCloseDocument}

\func{Bool}{OnCloseDocument}{\void}

The default implementation calls DeleteContents (an empty implementation)
sets the modified flag to FALSE. Override this to
supply additional behaviour when the document is closed with Close.

\membersection{wxDocument::OnCreate}

\func{Bool}{OnCreate}{\param{const char *}{path}, \param{long}{ flags}}

Called just after the document object is created to give it a chance
to initialize itself. The default implementation uses the
template associated with the document to create an initial view.
If this function returns FALSE, the document is deleted.

\membersection{wxDocument::OnCreateCommandProcessor}

\func{wxCommandProcessor *}{OnCreateCommandProcessor}{\void}

Override this function if you want a different (or no) command processor
to be created when the document is created. By default, it returns
an instance of wxCommandProcessor.

See \helpref{wxCommandProcessor}{wxcommandprocessor}.

\membersection{wxDocument::OnNewDocument}

\func{Bool}{OnNewDocument}{\void}

The default implementation calls OnSaveModified and DeleteContents, makes a default title for the
document, and notifies the views that the filename (in fact, the title) has changed.

\membersection{wxDocument::OnOpenDocument}

\func{Bool}{OnOpenDocument}{\param{char *}{filename}}

Constructs an input file stream for the given filename (which must not be NULL),
and calls LoadObject. If LoadObject returns TRUE, the document is set to
unmodified; otherwise, an error message box is displayed. The document's
views are notified that the filename has changed, to give windows an opportunity
to update their titles. All of the document's views are then updated.

\membersection{wxDocument::OnSaveDocument}

\func{Bool}{OnSaveDocument}{\param{char *}{filename}}

Constructs an output file stream for the given filename (which must not be NULL),
and calls SaveObject. If SaveObject returns TRUE, the document is set to
unmodified; otherwise, an error message box is displayed.

\membersection{wxDocument::OnSaveModified}

\func{Bool}{OnSaveModified}{\void}

If the document has been modified, prompts the user to ask if the changes should
be changed. If the user replies Yes, the Save function is called. If No, the
document is marked as unmodified and the function succeeds. If Cancel, the
function fails.

\membersection{wxDocument::RemoveView}

\func{Bool}{RemoveView}{\param{wxView *}{view}}

Removes the view from the document's list of views, and calls OnChangedViewList.

\membersection{wxDocument::Save}

\func{Bool}{Save}{\void}

Saves the document by calling OnSaveDocument if there is an associated filename,
or SaveAs if there is no filename.

\membersection{wxDocument::SaveAs}

\func{Bool}{SaveAs}{\void}

Prompts the user for a file to save to, and then calls OnSaveDocument.

\membersection{wxDocument::SaveObject}

\func{ostream\&}{SaveObject}{\param{ostream\& }{stream}}

Override this function and call it from your own SaveObject before
streaming your own data. SaveObject is called by the framework
automatically when the document contents need to be saved.

\membersection{wxDocument::SetCommandProcessor}

\func{void}{SetCommandProcessor}{\param{wxCommandProcessor *}{processor}}

Sets the command processor to be used for this document. The document will then be responsible
for its deletion. Normally you should not call this; override OnCreateCommandProcessor
instead.

See \helpref{wxCommandProcessor}{wxcommandprocessor}.

\membersection{wxDocument::SetDocumentName}

\func{void}{SetDocumentName}{\param{char *}{name}}

Sets the document type name for this document. See the comment for \helpref{documentTypeName}{documenttypename}.

\membersection{wxDocument::SetDocumentTemplate}

\func{void}{SetDocumentTemplate}{\param{wxDocTemplate *}{templ}}

Sets the pointer to the template that created the document. Should only be called by the
framework.

\membersection{wxDocument::SetFilename}

\func{void}{SetFilename}{\param{char *}{filename}}

Sets the filename for this document. Usually called by the framework.

\membersection{wxDocument::SetTitle}

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

Sets the title for this document. The document title is used for an associated
frame (if any), and is usually constructed by the framework from
the filename.

\section{\class{wxEnhDialogBox}: wxDialogBox}\label{wxenhdialogbox}

wxEnDialogBox is derived from \helpref{wxDialogBox}{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}\itemsep=0pt
\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{long }{style = wxENH\_DEFAULT}, \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.

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

\begin{twocollist}\itemsep=0pt
\twocolitem{wxBOTTOM\_COMMANDS}{Command buttons are on bottom of the dialog.}
\twocolitem{wxCANCEL\_BUTTON\_FIRST}{The cancel button is the first button.}
\twocolitem{wxCANCEL\_BUTTON\_LAST}{The cancel button is the last button.}
\twocolitem{wxCANCEL\_BUTTON\_SECOND}{The cancel button is the second button.}
\twocolitem{wxCAPTION}{Gives a caption to the dialog box.}
\twocolitem{wxENH\_DEFAULT}{Equivalent to wxCAPTION $\|$ wxBOTTOM\_COMMANDS $\|$ wxSTATUS\_FOOTER $\|$ wxNO\_CANCEL\_BUTTON.}
\twocolitem{wxNO\_STATUS\_FOOTER}{No status line is displayed.}
\twocolitem{wxNO\_CANCEL}{No cancel button is displayed.}
\twocolitem{wxRIGHT\_COMMANDS}{Command buttons are on the right hand side of the dialog.}
\twocolitem{wxSTATUS\_FOOTER}{A status line is displayed at the bottom of the dialog.}
\end{twocollist}

\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{Bool}{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}\rtfsp
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}\label{wxevent}

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

\func{WXTYPE}{GetEventClass}{\void}

Returns the identifier of the given event class,
such as wxTYPE\_MOUSE\_EVENT.

\membersection{wxEvent::GetEventObject}

\func{wxObject *}{GetEventObject}{\void}

Returns the object associated with the
event, if any.

\membersection{wxEvent::GetEventType}

\func{WXTYPE}{GetEventType}{\void}

Returns the identifier of the given event type,
such as wxEVENT\_TYPE\_BUTTON\_COMMAND.

\membersection{wxEvent::GetObjectType}

\func{WXTYPE}{GetObjectType}{\void}

Returns the type of the object associated with the
event, such as wxTYPE\_BUTTON.

\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{wxEvtHandler}: wxObject}\label{wxevthandler}

\overview{Event handling overview}{eventhandlingoverview}

A class that can handle events from the windowing system.
wxWindow (and therefore all window classes) are derived from
this class.

\membersection{wxEvtHandler::nextHandler}

\member{wxEvtHandler *}{nextHandler}

Protected member variable pointing the next event handler in the chain.

\membersection{wxEvtHandler::previousHandler}

\member{wxEvtHandler *}{previousHandler}

Protected member variable pointing the previous event handler in the chain.

\membersection{wxEvtHandler::wxEvtHandler}

\func{void}{wxEvtHandler}{\void}

Constructor.

\membersection{wxEvtHandler::\destruct{wxEvtHandler}}

\func{void}{\destruct{wxEvtHandler}}{\void}

Destructor. If the handler is part of a chain, the destructor will
unlink itself and restore the previous and next handlers so that they point to
each other.

\membersection{wxEvtHandler::GetClientData}

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

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

\membersection{wxEvtHandler::GetNextHandler}

\func{wxEvtHandler *}{GetNextHandler}{\void}

Gets the pointer to the next handler in the chain.

\membersection{wxEvtHandler::GetPreviousHandler}

\func{wxEvtHandler *}{GetPreviousHandler}{\void}

Gets the pointer to the previous handler in the chain.

\membersection{wxEvtHandler::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{wxEvtHandler::OnChar}\label{wxevthandleronchar}

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

Sent to the window when the user has pressed a key. See \helpref{wxKeyEvent}{wxkeyevent} for
details.

Note that the ASCII values do not have explicit key codes: they are passed as ASCII
values.

See also \helpref{wxEvtHandler::OnEvent}{wxevthandleronevent} for mouse event notification. {\bf OnChar} is
currently applicable to canvas and panel subwindows only. On some platforms, it may
be implemented for text subwindows (not XView).

\membersection{wxEvtHandler::OnCharHook}\label{wxevthandleroncharhook}

\func{Bool}{OnCharHook}{\param{wxKeyEvent\&}{ ch}}

This member is called (under Windows only) to allow the window to intercept keyboard events
before they are processed by child windows. The window receives this event from
the default \helpref{wxApp::OnCharHook}{wxapponcharhook} member function if the window
(frame or dialog box) is active. The function should returns TRUE to indicate the
character has been processed, or FALSE to allow default processing. The default
implementation for wxWindow returns FALSE, but the wxDialogBox implementation
checks for WXK\_ESCAPE and tries to close the dialog.

See also \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxEvtHandler::OnChar}{wxevthandleronchar},\rtfsp
\helpref{wxDialogBox::OnCharHook}{wxdialogboxoncharhook}.

\membersection{wxEvtHandler::OnClose}\label{wxevthandleronclose}

Sent to the frame when the user has tried to close a managed window (i.e., a frame
or dialog box) using the window manager (X) or system menu (Windows).  If TRUE is returned by
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.

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

\membersection{wxEvtHandler::OnDefaultAction}\label{wxevthandlerondefaultaction}

\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.
See \helpref{wxPanel::OnDefaultAction}{wxpanelondefaultaction}.

\membersection{wxEvtHandler::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}{wxwindowdragacceptfiles}.

\membersection{wxEvtHandler::OnEvent}\label{wxevthandleronevent}

\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{wxEvtHandler::OnChar}{wxevthandleronchar} for character
events, and also \helpref{wxMouseEvent}{wxmouseevent} for how to access event information.

\membersection{wxEvtHandler::OnItemEvent}

\func{void}{OnItemEvent}{\param{wxItem *}{ item}, \param{wxMouseEvent \&}{ event}}

Called in user-interface edit mode when a panel item receives a mouse event.
The default implementation manages panel item dragging and sizing.

See \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxEvtHandler::OnItemLeftClick}

\func{void}{OnItemLeftClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user left-clicks on a panel item.
The coordinates (relative to the item) and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxEvtHandler::OnItemMove}

\func{void}{OnItemMove}{\param{wxItem *}{ item}, \param{int }{x}, \param{int }{y}}

Called in user-interface edit mode when the item has been moved by the user.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxEvtHandler::OnItemRightClick}

\func{void}{OnItemRightClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user right-clicks on a panel item.
The coordinates (relative to the item) and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxEvtHandler::OnItemSelect}

\func{void}{OnItemSelect}{\param{wxItem *}{item}, \param{Bool}{ select}}

Called when a window is selected or deselected. Currently applies only to panel items
in user-interface edit mode.

\membersection{wxEvtHandler::OnItemSize}

\func{void}{OnItemSize}{\param{wxItem *}{ item}, \param{int }{width}, \param{int }{height}}

Called in user-interface edit mode when the item has been resized by the user.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxEvtHandler::OnLeftClick}

\func{void}{OnLeftClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user left-clicks on the
panel background. The coordinates and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxEvtHandler::OnRightClick}

\func{void}{OnRightClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user right-clicks on the
panel background. The coordinates and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxEvtHandler::OnKillFocus}

\func{void}{OnKillFocus}{\void}

Called when a window's focus is being killed. There are many exceptions to this rule
so be careful when relying on it.

\membersection{wxEvtHandler::OnMenuCommand}\label{wxevthandleronmenucommand}

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

Sent to a frame window's event handler when an item on the window's menu has been chosen.
Derive your own frame class to handle this message. See \helpref{wxFrame::OnMenuCommand}{wxframeonmenucommand}.

\membersection{wxEvtHandler::OnMenuSelect}\label{wxevthandleronmenuselect}

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

Sent to a frame's event handler when an item on the frame's menu has been selected
(i.e. the cursor is on the item, but the left button has not been
released). Derive your own frame class to handle this message.
See \helpref{wxFrame::OnMenuSelect}{wxframeonmenuselect}.

\membersection{wxEvtHandler::OnMove}

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

Called when a window is moved. Not currently implemented.

\membersection{wxEvtHandler::OnPaint}

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

Sent to the event handler when the window must be refreshed.
Derive your own class to handle this message. So far, only
relevant to the wxCanvas and wxPanel classes.

\membersection{wxEvtHandler::OnScroll}

\func{void}{OnScroll}{\param{wxCommandEvent\& }{event}}

Override this function to intercept scroll events. Only implemented
for the wxCanvas class. See \helpref{wxCanvas::OnScroll}{wxcanvasonscroll}.

\membersection{wxEvtHandler::OnSelect}

\func{void}{OnSelect}{\param{Bool}{ select}}

Called when a window is selected or deselected. Currently applies only to panel items
in user-interface edit mode.

\membersection{wxEvtHandler::OnSetFocus}

\func{void}{OnSetFocus}{\void}

Called when a window's focus is being set. There are many exceptions to this rule
so be careful when relying on it.

\membersection{wxEvtHandler::OnSize}

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

Sent to the event handler 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.

\membersection{wxEvtHandler::SetClientData}

\func{void}{SetClientData}{\param{char *}{data}}

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

\membersection{wxEvtHandler::SetNextHandler}

\func{void}{SetNextHandler}{\param{wxEvtHandler *}{handler}}

Sets the pointer to the next handler.

\membersection{wxEvtHandler::SetPreviousHandler}

\func{void}{SetPreviousHandler}{\param{wxEvtHandler *}{handler}}

Sets the pointer to the previous handler.



\section{\class{wxFileHistory}: wxObject}\label{wxfilehistory}

\overview{Overview}{wxfilehistoryoverview}

The wxFileHistory encapsulates a user interface convenience, the
list of most recently visited files as shown on a menu (usually the File menu).

\membersection{wxFileHistory::fileHistory}

\member{char **}{fileHistory}

A character array of strings corresponding to the most recently opened
files.

\membersection{wxFileHistory::fileHistoryN}

\member{int}{fileHistoryN}

The number of files stored in the history array.

\membersection{wxFileHistory::fileMaxFiles}

\member{int}{fileMaxFiles}

The maximum number of files to be stored and displayed on the menu.

\membersection{wxFileHistory::fileMenu}

\member{wxMenu *}{fileMenu}

The file menu used to display the file history list (if enabled).

\membersection{wxFileHistory::wxFileHistory}

\func{void}{wxFileHistory}{\param{int}{ maxFiles = 9}}

Constructor. Pass the maximum number of files that should be stored and displayed.

\membersection{wxFileHistory::\destruct{wxFileHistory}}

\func{void}{\destruct{wxFileHistory}}{\void}

Destructor.

\membersection{wxFileHistory::AddFileToHistory}

\func{void}{AddFileToHistory}{\param{char *}{filename}}

Adds a file to the file history list, if the object has a pointer to an appropriate file menu.

\membersection{wxFileHistory::FileHistoryLoad}

\func{void}{FileHistoryLoad}{\param{char *}{resourceFile}, \param{char *}{sectionName}}

Loads the file history from a resource file, using the given section. This must be called
explicitly by the application.

\membersection{wxFileHistory::FileHistorySave}

\func{void}{FileHistorySave}{\param{char *}{resourceFile}, \param{char *}{sectionName}}

Saves the file history into a resource file, using the given section. This must be called
explicitly by the application.

\membersection{wxFileHistory::FileHistoryUseMenu}

\func{void}{FileHistoryUseMenu}{\param{wxMenu *}{menu}}

Use this menu for appending recently-visited document filenames, for convenient
access. Calling this function with a valid menu pointer enables the history
list functionality.

\membersection{wxFileHistory::GetMaxFiles}

\func{int}{GetMaxFiles}{\void}

Returns the maximum number of files that can be stored.

\membersection{wxFileHistory::GetNoHistoryFiles}

\func{int}{GetNoHistoryFiles}{\void}

Returns the number of files currently stored in the file history.


\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{wxform}

\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}\itemsep=0pt
\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}\itemsep=0pt
\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::IsEditable}

\func{Bool}{IsEditable}{\void}

Returns TRUE if the form can be edited.

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

\func{void}{OnHelp}{\void}

This member may be derived by the application. When the user presses the
Help button, this is called, allowing the application to take action.

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

\func{void}{SetEditable}{\param{Bool }{id}}

Sets the form to be editable (TRUE) or read-only (FALSE).

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

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

Some of the Windows 3 issues of Multiple Document Interface (MDI) versus
Single Document Interface (SDI) frames are covered in the user manual.

\normalbox{If you wish to have a toolbar on an MDI parent frame, create the toolbar
as normal (as a child of the MDI frame), set the appropriate height for it,
and call {\bf wxFrame::SetToolBar}. wxWindows will now manage the toolbar
automatically. {\bf Note:} SDI frame and MDI child frame toolbars must still
be managed by the application in an {\bf OnSize} member function.}

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

\helponly{See \helpref{MDI versus SDI}{mdi} for a discussion of how the MS Windows Multiple Document Interface
convention is supported.}.

\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}\rtfsp
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 also \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}\rtfsp
member to fit inside the frame.

\membersection{wxFrame::GetMenuBar}\label{wxframegetmenubar}

\func{wxMenuBar *}{GetMenuBar}{\void}

Returns a pointer to the menubar currently associated with the frame (if any).

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

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

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

\membersection{wxFrame::GetToolBar}\label{wxframegettoolbar}

\func{wxWindow *}{GetToolBar}{\void}

Under Windows only, gets the window to be used as a toolbar for this
MDI parent window. 

\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:
    {
      if (OnClose())
        delete this;
      break;
    }
    ...
  }
}
\end{verbatim}

\membersection{wxFrame::OnMenuCommand}\label{wxframeonmenucommand}

\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:
    {
      if (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}\label{wxframeonmenuselect}

\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. The icon
is now `owned' by the frame and will be deleted on frame deletion,
so do not delete the icon yourself.

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.

Instead of using wxFrame::SetIcon under Windows, you can add the following lines to your Windows 3 resource file:

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

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

If these icons are not supplied, and wxFrame::SetIcon is not called either,
then the following defaults apply if you have included wx.rc.

\begin{verbatim}
wxDEFAULT_FRAME               ICON std.ico
wxDEFAULT_MDIPARENTFRAME      ICON mdi.ico
wxDEFAULT_MDICHILDFRAME       ICON child.ico
\end{verbatim}

You can replace std.ico, mdi.ico and child.ico with your own defaults
for all your wxWindows application. Currently they show the same icon.

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::SetToolBar}\label{wxframesettoolbar}

\func{void}{SetToolBar}{\param{wxWindow *}{toolbar}}

Under Windows only, sets the window to be used as a toolbar for this
MDI parent window. It is necessary since wxWindows does not provide
general functionality for application management of an MDI client area.

When the frame is resized, the toolbar is resized to be the width of
the frame client area, and the toolbar height is kept the same.

The parent of the toolbar must be this frame, which must itself have
been created as an MDI parent frame.

Please note that SDI frames and MDI child windows must have their
toolbars managed by the application.

\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{wxGauge}: wxItem}\label{wxgauge}

A gauge is a horizontal or vertical bar which shows the progress of
some operation, or perhaps an amount of something.

Use \helpref{SetValue}{wxgaugesetvalue} to set the value of
the gauge. You can use {\it wxItem::SetButtonColour} and {\it wxItem::SetBackgroundColour} to
set the gauge value and background colours respectively.

Note that wxWindows support for wxGauge is off by default; to enable it,
the file {\tt wx\_setup.h} must be edited, and the gauge code in
\rtfsp{\tt contrib/gauge} (for Windows) and {\tt contrib/xmgauge} (for Motif)
must be compiled.

\membersection{wxGauge::wxGauge}\label{gauge}

\func{void}{wxGauge}{\void}

Constructor, for deriving classes.

\func{void}{wxGauge}{\param{wxPanel *}{parent}, \param{char *}{label},\\
  \param{int}{ range}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = wxHORIZONTAL}, \param{char *}{name = ``gauge"}}

Constructor, creating and showing a gauge.

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

{\it range} is an integer specifying the number of units the
guage is divided into.

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

{\it style} may be wxHORIZONTAL for a horizontal gauge, or wxVERTICAL
for a vertical gauge.

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

\membersection{wxGauge::\destruct{wxGauge}}

\func{void}{\destruct{wxGauge}}{\void}

Destructor, destroying the gauge.

\membersection{wxGauge::Create}

\func{Bool}{Create}{\param{wxPanel *}{parent}, \param{char *}{label},\\
  \param{int}{ range}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
  \param{int}{ width = -1}, \param{int}{ height = -1},\\
  \param{long}{ style = wxHORIZONTAL}, \param{char *}{name = ``gauge"}}

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

\membersection{wxGauge::SetBezelFace}

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

Sets the 3D bezel face width.

\membersection{wxGauge::SetRange}\label{wxgaugesetrange}

\func{void}{SetRange}{\param{int }{range}}

Sets the range of the gauge.

\membersection{wxGauge::SetShadowWidth}

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

Sets the 3D shadow width.

\membersection{wxGauge::SetValue}\label{wxgaugesetvalue}

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

Sets the position of the gauge.

\section{\class{wxGroupBox}: wxItem}\label{wxgroupbox}

A group box is a rectangle drawn around other panel items to denote
a logical grouping of items.

Currently it is implemented for Windows and Motif only.

\membersection{wxGroupBox::wxGroupBox}\label{groupbox}

\func{void}{wxGroupBox}{\void}

Constructor, for deriving classes.

\func{void}{wxGroupBox}{\param{wxPanel *}{parent}, \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 = ``groupBox"}}

Constructor, creating and showing a group box.

If {\it label} is non-NULL, it will be used as the group box 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.

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

\membersection{wxGroupBox::\destruct{wxGroupBox}}

\func{void}{\destruct{wxGroupBox}}{\void}

Destructor, destroying the group box.

\membersection{wxGroupBox::Create}

\func{Bool}{Create}{\param{wxPanel *}{parent}, \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 = ``groupBox"}}

Creates the group box for two-step construction. Derived classes
should call or replace this function. See \helpref{wxGroupBox::wxGroupBox}{groupbox}\rtfsp
for further details.

\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}\rtfsp
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}

Default constructor.

\func{void}{wxIcon}{\param{char **}{ data}}

Construct an icon by specifying the bits in an included .XPM file (X only). 
Only available if USE\_XPM\_IN\_X is enabled in wx\_setup.h.

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

Construct an icon by specifying the bits in an included .XBM file (X only). 

For example:

\begin{verbatim}
#ifdef wx_x
#include "aiai.xbm"
#endif

#ifdef wx_x
  test_icon = new wxIcon(aiai_bits, aiai_width, aiai_height);
#endif
\end{verbatim}

\func{void}{wxIcon}{\param{char *}{iconName}, \param{long}{flags}}

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.  

Construct a cursor by passing a string resource name or filename.
Under Motif, {\it flags} defaults to wxBITMAP\_TYPE\_XBM $\|$ wxBITMAP\_DISCARD\_COLOURMAP. Under Windows,
it defaults to wxBITMAP\_TYPE\_ICO\_RESOURCE $\|$ wxBITMAP\_DISCARD\_COLOURMAP.

Under X, the permitted icon types in the {\it flags} bitlist are:

\begin{itemize}\itemsep=0pt
\item {\bf wxBITMAP\_TYPE\_BMP} Load a Windows bitmap file (if USE\_IMAGE\_LOADING\_IN\_X is enabled in wx\_setup.h).
\item {\bf wxBITMAP\_TYPE\_GIF} Load a GIF bitmap file (if USE\_IMAGE\_LOADING\_IN\_X is enabled in wx\_setup.h).
\item {\bf wxBITMAP\_TYPE\_XBM} Load an X bitmap file.
\item {\bf wxBITMAP\_TYPE\_XPM} Load an XPM (colour pixmap) file. Only available if USE\_XPM\_IN\_X is enabled in wx\_setup.h.
\end{itemize}

Under Windows, the permitted types are:

\begin{itemize}\itemsep=0pt
%\item {\bf wxBITMAP\_TYPE\_BMP} Load a Windows bitmap file
%\item {\bf wxBITMAP\_TYPE\_BMP\_RESOURCE} Load a Windows bitmap from the resource database
%\item {\bf wxBITMAP\_TYPE\_GIF} Load a GIF bitmap file
\item {\bf wxBITMAP\_TYPE\_ICO} Load a cursor from a .ico icon file (only if USE\_RESOURCE\_LOADING\_IN\_MSW
is enabled in wx\_setup.h).
\item {\bf wxBITMAP\_TYPE\_ICO\_RESOURCE} Load a Windows resource (as specified in the .rc file).
\end{itemize}

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

\membersection{wxIcon::GetHeight}

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

Returns the height of the icon.

\membersection{wxIcon::GetWidth}

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

Returns the width of the icon.

\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). The key string is copied and stored by the hash
table implementation.

\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}\rtfsp
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{wxIndividualLayoutConstraint}: wxObject}\label{wxindividuallayoutconstraint}

\overview{Overview and examples}{constraintsoverview}

Objects of this class are stored in the wxIndividualLayoutConstraint class
as one of eight possible constraints that a window can be involved in.

Most constraints are initially set to have the relationship wxUnconstrained,
which means that their values should be calculated by looking at known constraints.
The exceptions are {\it width} and {\it height}, which are set to wxAsIs to
ensure that if the user does not specify a constraint, the existing
width and height will be used, to be compatible with panel items which often
have take a default size. If the constraint is wxAsIs, the dimension will
not be changed.

See also \helpref{wxLayoutConstraints}{wxlayoutconstraints}, \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints}.

\subsection{Edges and relationships}

The {\it wxEdge}\index{wxEdge} enumerated type specifies the type of edge or dimension of a window.

\begin{twocollist}\itemsep=0pt
\twocolitem{wxLeft}{The left edge.}
\twocolitem{wxTop}{The top edge.}
\twocolitem{wxRight}{The right edge.}
\twocolitem{wxBottom}{The bottom edge.}
\twocolitem{wxCentreX}{The x-coordinate of the centre of the window.}
\twocolitem{wxCentreY}{The y-coordinate of the centre of the window.}
\end{twocollist}

The {\it wxRelationship}\index{wxRelationship} enumerated type specifies the relationship that
this edge or dimension has with another specified edge or dimension. Normally, the user
doesn't use these directly because functions such as {\it Below} and {\it RightOf} are a convenience
for using the more general {\it Set} function.

\begin{twocollist}\itemsep=0pt
\twocolitem{wxUnconstrained}{The edge or dimension is unconstrained (the default for edges.}
\twocolitem{wxAsIs}{The edge or dimension is to be taken from the current window position or size (the
default for dimensions.}
\twocolitem{wxAbove}{The edge should be above another edge.}
\twocolitem{wxBelow}{The edge should be below another edge.}
\twocolitem{wxLeftOf}{The edge should be to the left of another edge.}
\twocolitem{wxRightOf}{The edge should be to the right of another edge.}
\twocolitem{wxSameAs}{The edge or dimension should be the same as another edge or dimension.}
\twocolitem{wxPercentOf}{The edge or dimension should be a percentage of another edge or dimension.}
\twocolitem{wxAbsolute}{The edge or dimension should be a given absolute value.}
\end{twocollist}

\membersection{wxIndividualLayoutConstraint::wxIndividualLayoutConstraint}

\func{void}{wxIndividualLayoutConstraint}{\void}

Constructor. Not used by the end-user.

\membersection{wxIndividualLayoutConstraint::Above}

\func{void}{Above}{\param{wxWindow *}{otherWin}, \param{int}{ margin = 0}}

Constrains this edge to be above the given window, with an
optional margin. Implicitly, this is relative to the top edge of the other window.

\membersection{wxIndividualLayoutConstraint::Absolute}

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

Constrains this edge or dimension to be the given absolute value.

\membersection{wxIndividualLayoutConstraint::AsIs}

\func{void}{AsIs}{\void}

Sets this edge or constraint to be whatever the window's value is
at the moment. If either of the width and height constraints
are {\it as is}, the window will not be resized, but moved instead.
This is important when considering panel items which are intended
to have a default size, such as a button, which may take its size
from the size of the button label.

\membersection{wxIndividualLayoutConstraint::Below}

\func{void}{Below}{\param{wxWindow *}{otherWin}, \param{int}{ margin = 0}}

Constrains this edge to be below the given window, with an
optional margin. Implicitly, this is relative to the bottom edge of the other window.

\membersection{wxIndividualLayoutConstraint::Constrained}

\func{void}{Constrained}{\void}

Sets this edge or dimension to be unconstrained, that is, dependent on
other edges and dimensions from which this value can be deduced.

\membersection{wxIndividualLayoutConstraint::LeftOf}

\func{void}{LeftOf}{\param{wxWindow *}{otherWin}, \param{int}{ margin = 0}}

Constrains this edge to be to the left of the given window, with an
optional margin. Implicitly, this is relative to the left edge of the other window.

\membersection{wxIndividualLayoutConstraint::PercentOf}

\func{void}{PercentOf}{\param{wxWindow *}{otherWin}, \param{wxEdge}{ edge}, \param{int}{ margin = 0}}

Constrains this edge or dimension to be to a percentage of the given window, with an
optional margin.

\membersection{wxIndividualLayoutConstraint::RightOf}

\func{void}{RightOf}{\param{wxWindow *}{otherWin}, \param{int}{ margin = 0}}

Constrains this edge to be to the right of the given window, with an
optional margin. Implicitly, this is relative to the right edge of the other window.

\membersection{wxIndividualLayoutConstraint::SameAs}

\func{void}{SameAs}{\param{wxWindow *}{otherWin}, \param{wxEdge}{ edge}, \param{int}{ margin = 0}}

Constrains this edge or dimension to be to the same as the edge of the given window, with an
optional margin.

\membersection{wxIndividualLayoutConstraint::Set}

\func{void}{Set}{\param{wxRelationship}{ rel}, \param{wxWindow *}{otherWin}, \param{wxEdge}{ otherEdge},
 \param{int}{ value = 0}, \param{int}{ margin = 0}}

Sets the properties of the constraint. Normally called by one of the convenience
functions such as Above, RightOf, SameAs.

\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}\rtfsp
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. An enumerated type, one of:

\begin{verbatim}
 WXK_BACK    = 8
 WXK_TAB     = 9
 WXK_RETURN  = 13
 WXK_ESCAPE  = 27
 WXK_SPACE   = 32
 WXK_DELETE  = 127

 WXK_START   = 300
 WXK_LBUTTON
 WXK_RBUTTON
 WXK_CANCEL
 WXK_MBUTTON
 WXK_CLEAR
 WXK_SHIFT
 WXK_CONTROL
 WXK_MENU
 WXK_PAUSE
 WXK_CAPITAL
 WXK_PRIOR
 WXK_NEXT
 WXK_END
 WXK_HOME
 WXK_LEFT
 WXK_UP
 WXK_RIGHT
 WXK_DOWN
 WXK_SELECT
 WXK_PRINT
 WXK_EXECUTE
 WXK_SNAPSHOT
 WXK_INSERT
 WXK_HELP
 WXK_NUMPAD0
 WXK_NUMPAD1
 WXK_NUMPAD2
 WXK_NUMPAD3
 WXK_NUMPAD4
 WXK_NUMPAD5
 WXK_NUMPAD6
 WXK_NUMPAD7
 WXK_NUMPAD8
 WXK_NUMPAD9
 WXK_MULTIPLY
 WXK_ADD
 WXK_SEPARATOR
 WXK_SUBTRACT
 WXK_DECIMAL
 WXK_DIVIDE
 WXK_F1
 WXK_F2
 WXK_F3
 WXK_F4
 WXK_F5
 WXK_F6
 WXK_F7
 WXK_F8
 WXK_F9
 WXK_F10
 WXK_F11
 WXK_F12
 WXK_F13
 WXK_F14
 WXK_F15
 WXK_F16
 WXK_F17
 WXK_F18
 WXK_F19
 WXK_F20
 WXK_F21
 WXK_F22
 WXK_F23
 WXK_F24
 WXK_NUMLOCK
 WXK_SCROLL 
\end{verbatim}

\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{wxLayoutConstraints}: wxObject}\label{wxlayoutconstraints}

\overview{Overview and examples}{constraintsoverview}

Objects of this class can be associated with a window to define its
layout constraints, with respect to siblings or its parent.

The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
some or all of which should be accessed directly to set the appropriate
constraints.

\begin{itemize}\itemsep=0pt
\item {\bf left:} represents the left hand edge of the window
\item {\bf right:} represents the right hand edge of the window
\item {\bf top:} represents the top edge of the window
\item {\bf bottom:} represents the bottom edge of the window
\item {\bf width:} represents the width of the window
\item {\bf height:} represents the height of the window
\item {\bf centreX:} represents the horizontal centre point of the window
\item {\bf centreY:} represents the vertical centre point of the window
\end{itemize}

Most constraints are initially set to have the relationship wxUnconstrained,
which means that their values should be calculated by looking at known constraints.
The exceptions are {\it width} and {\it height}, which are set to wxAsIs to
ensure that if the user does not specify a constraint, the existing
width and height will be used, to be compatible with panel items which often
have take a default size. If the constraint is wxAsIs, the dimension will
not be changed.

See also \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}, \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints}.

\membersection{wxLayoutConstraints::wxLayoutConstraints}

\func{void}{wxLayoutConstraints}{\void}

Constructor.

\membersection{wxLayoutConstraints::bottom}

\member{wxIndividualLayoutConstraint}{bottom}

Constraint for the bottom edge.

\membersection{wxLayoutConstraints::centreX}

\member{wxIndividualLayoutConstraint}{centreX}

Constraint for the horizontal centre point.

\membersection{wxLayoutConstraints::centreY}

\member{wxIndividualLayoutConstraint}{centreY}

Constraint for the vertical centre point.

\membersection{wxLayoutConstraints::height}

\member{wxIndividualLayoutConstraint}{height}

Constraint for the height.

\membersection{wxLayoutConstraints::left}

\member{wxIndividualLayoutConstraint}{left}

Constraint for the left-hand edge.

\membersection{wxLayoutConstraints::right}

\member{wxIndividualLayoutConstraint}{right}

Constraint for the right-hand edge.

\membersection{wxLayoutConstraints::top}

\member{wxIndividualLayoutConstraint}{top}

Constraint for the top edge.

\membersection{wxLayoutConstraints::width}

\member{wxIndividualLayoutConstraint}{width}

Constraint for the width.

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

The key string is copied and stored by the list implementation.

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

List box elements are numbered from zero.

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

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

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

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

\func{void}{SetClientData}{\param{int}{ n}, \param{char *}{data}}

Associates the given client data pointer with the given item.

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

\func{void}{SetString}{\param{int}{ n}, \param{char *}{ s}}

Sets the value of the given string.

\membersection{wxListBox::SetStringSelection}

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

Sets the choice by passing the desired string.

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

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

\func{void}{Break}{\void}

Inserts a break in a menu, causing the next appended item to appear in a new column.

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

\membersection{wxMenu::Checked}

\func{Bool}{Checked}{\param{int}{ id}}

Returns TRUE if the given menu item is currently checked, FALSE otherwise.

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

\func{Bool}{Checked}{\param{int}{ id}}

Returns TRUE if the given menu item is currently checked, FALSE otherwise.

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

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}\itemsep=0pt
\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::LeftDClick}

\func{Bool}{LeftDClick}{\void}

Returns TRUE if the event was a left double click.

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

\func{Bool}{MiddleDClick}{\void}

Returns TRUE if the event was a middle double click.

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

\func{Bool}{RightDClick}{\void}

Returns TRUE if the event was a right double click.

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

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

The {\it style} parameter can be a bit list of the following:

\begin{twocollist}
\twocolitem{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.}
\twocolitem{wxREADONLY}{The text is read-only (not XView).}
\end{twocollist}

\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}{\param{wxObject *}{data}}

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

\section{\class{wxObject}}\label{wxobject}

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

From wxWindows 1.62, wxObject is the hub of a dynamic object creation
scheme, enabling a program to create instances of a class only knowing
its string class name, and to query the class hierarchy.

See also \helpref{wxClassInfo}{wxclassinfo}.

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

{\it NOTE:} This typing scheme will soon become obsolete since there is now
a better system using DECLARE... and IMPLEMENT... macros to register run-time
type information.

\membersection{wxObject::Dump}

\func{void}{Dump}{\param{ostream\&}{ stream}}

A virtual function that should be redefined by derived classes to allow dumping of
memory states. Currently wxWindows does not define Dump for derived classes, but
programmers may wish to use it for their own applications. Be sure to
call the Dump member of the class's base class to allow all information to be dumped.

The implementation of this function just writes the class name of the object.
If DEBUG is undefined or zero, the implementation is empty.

\membersection{wxObject::GetClassInfo}

\func{wxClassInfo *}{GetClassInfo}{void}

This virtual function is redefined for every class that requires run-time
type information.

\membersection{wxObject::IsKindOf}

\func{Bool}{IsKindOf}{\param{wxClassInfo *}{info}}

Determines whether this class is a subclass of (or the same class as)
the given class. E.g.:

\begin{verbatim}
  Bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
\end{verbatim}

\membersection{wxObject::LoadObject}

\func{istream\&}{LoadObject}{\param{istream\&}{ stream}}

The basis for a future persistent storage scheme.

\membersection{wxObject::SaveObject}

\func{ostream\&}{SaveObject}{\param{istream\&}{ stream}}

The basis for a future persistent storage scheme.

\membersection{wxObject::operator new}

\func{void *}{new}{\param{size\_t }{size}, \param{char *}{filename = NULL}, \param{int}{ lineNum = 0}}

The {\it new} operator is defined for debugging versions of the library only, when
the identifier DEBUG is defined and is more than zero. It takes over memory allocation, allowing
wxDebugContext operations.

\membersection{wxObject::operator delete}

\func{void}{delete}{\param{void }{buf}}

The {\it delete} operator is defined for debugging versions of the library only, when
the identifier DEBUG is defined and is more than zero. It takes over memory deallocation, allowing
wxDebugContext operations.

\section{\class{wxPanel}: wxCanvas}\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.

Because wxPanel inherits from wxCanvas (in implementations that permit it,
such as XView, Motif, and Windows) it has a device context, and can be drawn
on. There are some restrictions, however:

\begin{itemize}
\item The following wxCanvas members cannot be used: SetScrollbars, Scroll, GetVirtualSize.
\item The device context associated with wxDialogBox behaves slightly
differently: drawing to it requires enclosing code in BeginDrawing, EndDrawing
calls. This is because under Windows, dialog box device contexts are not 'retained'
and settings would be lost if the device context were retrieved and released
for each drawing operations.
\end{itemize}

\membersection{wxPanel::wxPanel}\label{constrpanel}

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

Constructor, for deriving classes.

\func{void}{wxPanel}{\param{wxWindow *}{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{wxBORDER}{Draws a thin border around the panel.}
\twocolitem{wxUSER\_COLOURS}{Under Windows, overrides standard control
processing to allow setting of the panel background colour.}
\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{wxWindow *}{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::DrawAllStaticItems}

\func{void}{DrawAllStaticItems}{\void}

Draws all the wxWindows static items associated with this panel. This is
experimental code.

\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::GetPanelDC}\label{wxpanelgetpaneldc}

\func{wxPanelDC *}{GetPanelDC}{\void}

Returns the panel device context. You may also get the device context
using wxCanvasDC::GetDC. Since wxCanvasDC and wxPanelDC offer the same
interface, either call will be adequate to get a suitable device context.

\membersection{wxPanel::GetVerticalSpacing}

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

Gets the vertical spacing for placing items on a panel.

\membersection{wxPanel::LoadFromResource}\label{wxpanelloadfromresource}

\func{Bool}{LoadFromResource}{\param{wxWindow *}{parent}, \param{char *}{name}}

Loads the contents of a panel or dialog box from a wxWindows resource.

See also \helpref{wxWindows resource functions}{resourcefuncs}\helponly{ and \helpref{the wxWindows resource system}{resourceformats}}.

\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::OnCommand}\label{wxpaneloncommand}

\func{void}{OnCommand}{\param{wxWindow \&}{win}, \param{wxCommandEvent \&}{event}}

This member is called for panel items that do not have a callback function
of their own. It must be overridden when using wxWindows resources, for example.

\helponly{See also \helpref{wxWindows resource formats}{resourceformats}.}

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

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

Called  when the panel receives a mouse event.
The default implementation manages panel item dragging and sizing if in user-interface edit mode.
It also sends panel mouse clicks to the application-overridable member functions OnLeftClick
and OnRightClick, again only in user-interface edit mode.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnItemEvent}

\func{void}{OnItemEvent}{\param{wxItem *}{ item}, \param{wxMouseEvent \&}{ event}}

Called in user-interface edit mode when the item receives a mouse event.
The default implementation manages panel item dragging and sizing.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnItemLeftClick}

\func{void}{OnItemLeftClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user left-clicks on a panel item.
The coordinates (relative to the item) and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnItemMove}

\func{void}{OnItemMove}{\param{wxItem *}{ item}, \param{int }{x}, \param{int }{y}}

Called in user-interface edit mode when the item has been moved by the user.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnItemRightClick}

\func{void}{OnItemRightClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user right-clicks on a panel item.
The coordinates (relative to the item) and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnItemSize}

\func{void}{OnItemSize}{\param{wxItem *}{ item}, \param{int }{width}, \param{int }{height}}

Called in user-interface edit mode when the item has been resized by the user.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnLeftClick}

\func{void}{OnLeftClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user left-clicks on the
panel background. The coordinates and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnRightClick}

\func{void}{OnRightClick}{\param{int}{ x}, \param{int}{ y}, \param{int}{ keys}}

Called in user-interface edit mode when the user right-clicks on the
panel background. The coordinates and a flag indicating shift and control
key status are passed. {\it keys} is a bit list of wxKEY\_SHIFT and wxKEY\_CTRL.

See also \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\membersection{wxPanel::OnPaint}

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

Sent to the panel when it receives an expose event. If you wish to drawn
on the panel, you may derive your own class to handle this message.

The standard wxPanel::OnPaint implementation contains code to draw
custom static items on the panel, and also to draw selection
handles for panel items if necessary. If you wish to use this functionality,
call wxPanel::OnPaint from your own OnPaint handler, or call
the individual DrawAllStaticItems and PaintSelectionHandles functions.

\membersection{wxPanel::PaintSelectionHandles}

\func{void}{PaintSelectionHandles}{\void}

Paints the selection handles for panel items if user
interface editing mode is on. This function is
called automatically by the default wxPanel::OnPaint handler.

See \helpref{wxWindow::SetUserEditMode}{setusereditmode}.

\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}\rtfsp
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{wxPanelDC}: wxDC}\label{wxpaneldc}

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

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

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

Adds the given directory to the path list, but does not
check if the path was already on the list (use wxPathList::Member)
for this).

\membersection{wxPathList::EnsureFileAccessible}

\func{void}{EnsureFileAccessible}{\param{char *}{filename}}

Given a full filename (with path), ensures that files in the same path
can be accessed using the pathlist. It does this by stripping the
filename and adding the path to the list if not already there.

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

\func{int}{GetDashes}{\param{wxDash **}{dashes}}

Gets an array of dashes (defined as char in X, DWORD under Windows).
{\it dashes} is a pointer to the array (not allocated by the application).
The function returns the number of dashes associated with this pen.

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

\func{void}{SetDashes}{\param{int }{n}, \param{wxDash *}{dashes}}

Associates an array of pointers to dashes (defined as char in X, DWORD under Windows)
with the pen. The array is not deallocated by wxPen, but neither must it be
deallocated by the calling application until the pen is deleted or this
function is called with a NULL array.

Sorry, I don't yet have information as to how the dashes work.

\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},\\
  \param{wxWindow *}{parent}}

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. {\it parent} is the parent of the printer dialog box.

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{wxPreviewCanvas}: wxCanvas}\label{wxpreviewcanvas}

A preview canvas is the default canvas used by the print preview
system to display the preview.

See also \helpref{wxPreviewFrame}{wxpreviewframe}, \helpref{wxPreviewControlBar}{wxpreviewcontrolbar},
\helpref{wxPrintPreview}{wxprintpreview}.

\membersection{wxPreviewCanvas::wxPreviewCanvas}

\func{void}{wxPreviewCanvas}{\param{wxPrintPreview *}{preview}, \param{wxWindow *}{parent},
 \param{int}{ x = -1}, \param{int}{ y = -1},\\
 \param{int}{ width = -1}, \param{int}{ height = -1},\\
 \param{long}{ style = 0}, \param{char *}{name = ``canvas"}}

Constructor.

\membersection{wxPreviewCanvas::\destruct{wxPreviewCanvas}}

\func{void}{\destruct{wxPreviewCanvas}}{\void}

Destructor.

\membersection{wxPreviewCanvas::OnPaint}

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

Calls wxPrintPreview::PaintPage to refresh the canvas.

\section{\class{wxPreviewControlBar}: wxPanel}\label{wxpreviewcontrolbar}

This is the default implementation of the preview control bar, a panel
with buttons and a zoom control. You can derive a new class from this and
override some or all member functions to change the behaviour and appearance;
or you can leave it as it is.

See also \helpref{wxPreviewFrame}{wxpreviewframe}, \helpref{wxPreviewCanvas}{wxpreviewcanvas},
\helpref{wxPrintPreview}{wxprintpreview}.

\membersection{wxPreviewControlBar::buttonFlags}

\member{long}{buttonFlags}

Protected data member, containing the button flags (see the constructor for details).

\membersection{wxPreviewControlBar::buttonFont}

\member{static wxFont *}{buttonFont}

Protected data member, pointing to the font used for the buttons.

\membersection{wxPreviewControlBar::closeButton}

\member{wxButton *}{closeButton}

Protected data member, pointing to the close button.

\membersection{wxPreviewControlBar::nextPageButton}

\member{wxButton *}{nextPageButton}

Protected data member, pointing to the next page button.

\membersection{wxPreviewControlBar::previousPageButton}

\member{wxButton *}{previousPageButton}

Protected data member, pointing to the previous page button.

\membersection{wxPreviewControlBar::printPreview}

\member{wxPrintPreview *}{printPreview}

Protected data member, pointing to the associated print preview object.

\membersection{wxPreviewControlBar::zoomControl}

\member{wxChoice *}{zoomControl}

Protected data member, pointing to the zoom control.

\membersection{wxPreviewControlBar::wxPreviewControlbar}

\func{void}{wxPanel}{\param{wxPrintPreview *}{preview}, \param{long}{ buttons}, \param{wxWindow *}{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 buttons parameter may be a combination of the following, using the bitwise `or' operator.

\begin{twocollist}
\twocolitem{wxPREVIEW\_PRINT}{Create a print button.}
\twocolitem{wxPREVIEW\_NEXT}{Create a next page button.}
\twocolitem{wxPREVIEW\_PREVIOUS}{Create a previous page button.}
\twocolitem{wxPREVIEW\_ZOOM}{Create a zoom control.}
\twocolitem{wxPREVIEW\_DEFAULT}{Equivalent to a combination of wxPREVIEW\_PREVIOUS, wxPREVIEW\_NEXT and
wxPREVIEW\_ZOOM.}
\end{twocollist}

\membersection{wxPreviewControlBar::\destruct{wxPreviewControlBar}}

\func{void}{\destruct{wxPreviewControlBar}}{\void}

Destructor.

\membersection{wxPreviewControlBar::CreateButtons}

\func{void}{CreateButtons}{\void}

Creates buttons, according to value of the button style flags.

\membersection{wxPreviewControlBar::GetPrintPreview}

\func{wxPrintPreview *}{GetPrintPreview}{\void}

Gets the print preview object associated with the control bar.

\membersection{wxPreviewControlBar::GetZoomControl}

\func{int}{GetZoomControl}{\void}

Gets the current zoom setting in percent.

\membersection{wxPreviewControlBar::OnPaint}

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

Draws a black border on the bottom of the control.

\membersection{wxPreviewControlBar::SetZoomControl}

\func{void}{SetZoomControl}{\param{int }{percent}}

Sets the zoom control.

\section{\class{wxPreviewFrame}: wxFrame}\label{wxpreviewframe}

This class provides the default method of managing the print preview interface.
Member functions may be overridden to replace functionality, or the
class may be used without derivation.

See also \helpref{wxPreviewCanvas}{wxpreviewcanvas}, \helpref{wxPreviewControlBar}{wxpreviewcontrolbar},
\helpref{wxPrintPreview}{wxprintpreview}.

\membersection{wxPreviewFrame::controlBar}

\member{wxPreviewControlBar *}{controlBar}

Protected data member, pointing to the preview control bar.

\membersection{wxPreviewFrame::previewCanvas}

\member{wxCanvas *}{previewCanvas}

Protected data member, pointing to the preview canvas.

\membersection{wxPreviewFrame::printPreview}

\member{wxPrintPreview *}{printPreview}

Protected data member, pointing to the print preview object.

\membersection{wxPreviewFrame::wxPreviewFrame}

\func{void}{wxPreviewFrame}{\param{wxPrintPreview *}{preview}, \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. Pass a print preview object plus other normal frame arguments.

\membersection{wxPreviewFrame::\destruct{wxPreviewFrame}}

\func{void}{\destruct{wxPreviewFrame}}{\void}

Destructor. 

\membersection{wxPreviewFrame::CreateControlBar}

\func{void}{CreateControlBar}{\void}

Creates a wxPreviewControlBar. Override this function to allow
a user-defined preview control bar object to be created.

\membersection{wxPreviewFrame::CreateCanvas}

\func{void}{CreateCanvas}{\void}

Creates a wxPreviewCanvas. Override this function to allow
a user-defined preview canvas object to be created.

\membersection{wxPreviewFrame::Initialize}

\func{void}{Initialize}{\void}

Creates the preview canvas and control bar, and calls
wxWindow::MakeModal(TRUE) to disable other top-level windows
in the application.

This function should be called by the application prior to
showing the frame.

\membersection{wxPreviewFrame::OnClose}

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

Enables the other frames in the application, and deletes the print preview
object, implicitly deleting any printout objects associated with the print
preview object.

\section{\class{wxPrintData}: wxObject}\label{wxprintdata}

This class holds a variety of information related to print dialogs.

\membersection{wxPrintData::wxPrintData}

\func{void}{wxPrintData}{\void}

Constructor.

\membersection{wxPrintData::\destruct{wxPrintData}}

\func{void}{\destruct{wxPrintData}}{\void}

Destructor.

\membersection{wxPrintData::EnableHelp}

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

Enables or disables the `Help' button.

\membersection{wxPrintData::EnablePageNumbers}

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

Enables or disables the `Page numbers' controls.

\membersection{wxPrintData::EnablePrintToFile}

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

Enables or disables the `Print to file' checkbox.

\membersection{wxPrintData::EnableSelection}

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

Enables or disables the `Selection' radio button.

\membersection{wxPrintData::GetAllPages}

\func{Bool}{GetAllPages}{\void}

Returns TRUE if the user requested that all pages be printed.

\membersection{wxPrintData::GetCollate}

\func{Bool}{GetCollate}{\void}

Returns TRUE if the user requested that the document(s) be collated.

\membersection{wxPrintData::GetFromPage}

\func{int}{GetFromPage}{\void}

Returns the {\it from} page number, as entered by the user.

\membersection{wxPrintData::GetMaxPage}

\func{int}{GetMaxPage}{\void}

Returns the {\it maximum} page number.

\membersection{wxPrintData::GetMinPage}

\func{int}{GetMinPage}{\void}

Returns the {\it minimum} page number.

\membersection{wxPrintData::GetNoCopies}

\func{int}{GetNoCopies}{\void}

Returns the number of copies requested by the user.

\membersection{wxPrintData::GetToPage}

\func{int}{GetToPage}{\void}

Returns the {\it to} page number, as entered by the user.

\membersection{wxPrintData::SetCollate}

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

Sets the 'Collate' checkbox to TRUE or FALSE.

\membersection{wxPrintData::SetFromPage}

\func{void}{SetFromPage}{\param{int }{page}}

Sets the {\it from} page number.

\membersection{wxPrintData::SetMaxPage}

\func{void}{SetMaxPage}{\param{int }{page}}

Sets the {\it maximum} page number.

\membersection{wxPrintData::SetMinPage}

\func{void}{SetMinPage}{\param{int }{page}}

Sets the {\it minimum} page number.

\membersection{wxPrintData::SetNoCopies}

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

Sets the default number of copies to be printed out.

\membersection{wxPrintData::SetPrintToFile}

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

Sets the 'Print to file' checkbox to TRUE or FALSE.

\membersection{wxPrintData::SetSetupDialog}

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

Determines whether the dialog to be shown will be the Print dialog
(pass FALSE) or Print Setup dialog (pass TRUE).

\membersection{wxPrintData::SetToPage}

\func{void}{SetToPage}{\param{int }{page}}

Sets the {\it to} page number.

\section{\class{wxPrintDialog}: wxDialogBox}\label{wxprintdialog}

This class represents the print and print setup common dialogs.
You may obtain a \helpref{wxPrinterDC}{wxprinterdc} device context from
a successfully dismissed print dialog.

\membersection{wxPrintDialog::wxPrintDialog}

\func{void}{wxPrintDialog}{\param{wxWindow *}{parent}, \param{wxPrintData *}{data = NULL}}

Constructor. Pass a parent window, and optionally a pointer to a block of print
data, which will be copied to the print dialog's print data.

\membersection{wxPrintDialog::\destruct{wxPrintDialog}}

\func{void}{\destruct{wxPrintDialog}}{\void}

Destructor. If wxPrintDialog::GetPrintDC has {\it not} been called,
the device context obtained by the dialog (if any) will be deleted.

\membersection{wxPrintDialog::GetPrintData}

\func{wxPrintData\&}{GetPrintData}{\void}

Returns the \helpref{print data}{wxprintdata} associated with the print dialog.

\membersection{wxPrintDialog::GetPrintDC}

\func{wxDC *}{GetPrintDC}{\void}

Returns the device context created by the print dialog, if any.
When this function has been called, the ownership of the device context
is transferred to the application, so it must then be deleted
explicitly.

\membersection{wxPrintDialog::Show}

\func{Bool}{Show}{\param{Bool}{ flag}}

Shows the dialog, returning TRUE if the user pressed Ok, and FALSE
otherwise. After this function is called, a device context may
be retrievable using wxPrintDialog::GetDC.

\section{\class{wxPrinter}: wxObject}\label{wxprinter}

\overview{Printing framework overview}{printingoverview}

This class represents the Windows or PostScript printer, and is the vehicle through
which printing may be launched by an application. Printing can also
be achieved through using of lower functions and classes, but
this and associated classes provide a more convenient and general
method of printing.

See also \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
\helpref{wxPrintout}{wxprintout}, \helpref{wxPrintPreview}{wxprintpreview}.

\membersection{wxPrinter::wxPrinter}

\func{void}{wxPrinter}{\param{wxPrintData *}{data = NULL}}

Constructor. Pass an optional pointer to a block of print
data, which will be copied to the printer object's print data.

\membersection{wxPrinter::\destruct{wxPrinter}}

\func{void}{\destruct{wxPrinter}}{\void}

Destructor.

\membersection{wxPrinter::Abort}

\func{Bool}{Abort}{\void}

Returns TRUE if the user has aborted the print job.

\membersection{wxPrinter::CreateAbortWindow}

\func{void}{CreateAbortWindow}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}}

Creates the default printing abort window, with a cancel button.

\membersection{wxPrinter::GetPrintData}

\func{wxPrintData\&}{GetPrintData}{\void}

Returns the \helpref{print data}{wxprintdata} associated with the printer object.

\membersection{wxPrinter::Print}

\func{Bool}{Print}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}, \param{Bool }{prompt=TRUE}}

Starts the printing process. Provide a parent window, a user-defined wxPrintout object which controls
the printing of a document, and whether the print dialog should be invoked first.

\membersection{wxPrinter::PrintDialog}

\func{Bool}{PrintDialog}{\param{wxWindow *}{parent}}

Invokes the print dialog.

\membersection{wxPrinter::ReportError}

\func{void}{ReportError}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}, \param{char *}{message}}

Default error-reporting function.

\membersection{wxPrinter::Setup}

\func{void}{Setup}{\param{wxWindow *}{parent}}

Invokes the print setup dialog.

\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{wxPrintout}: wxObject}\label{wxprintout}

\overview{Printing framework overview}{printingoverview}

This class encapsulates the functionality of printing out an
application document. A new class must be derived and members
overridden to respond to calls such as OnPrintPage and HasPage.
Instances of this class are passed to wxPrinter::Print or a
wxPrintPreview object to initiate printing or previewing.

See also \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
\helpref{wxPrinter}{wxprinter}, \helpref{wxPrintPreview}{wxprintpreview}.

\membersection{wxPrintout::wxPrintout}

\func{void}{wxPrintout}{\param{char *}{title = "Printout"}}

Constructor. Pass an optional title argument (currently unused).

\membersection{wxPrintout::\destruct{wxPrintout}}

\func{void}{\destruct{wxPrintout}}{\void}

Destructor.

\membersection{wxPrintout::GetDC}

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

Returns the device context associated with the printout (given to the printout at start of
printing or previewing). This will be a wxPrinterDC if printing under Windows,
a wxPostScriptDC if printing on other platforms, and a wxMemoryDC if previewing.

\membersection{wxPrintout::GetPageInfo}

\func{void}{GetPageInfo}{\param{int *}{minPage}, \param{int *}{maxPage}, \param{int *}{pageFrom}, \param{int *}{pageTo}}

Called by the framework to obtain information from the application about minimum and maximum page values that
the user can select, and the required page range to be printed. By default this
returns 1, 32000 for the page minimum and maximum values, and 1, 1 for the required page range.

If {\it minPage} is zero, the page number controls in the print dialog will be disabled.

\membersection{wxPrintout::GetPageSizeMM}

\func{void}{GetPageSizeMM}{\param{int *}{w}, \param{int *}{h}}

Returns the size of the printer page in millimetres.

\membersection{wxPrintout::GetPageSizePixels}

\func{void}{GetPageSizePixels}{\param{int *}{w}, \param{int *}{h}}

Returns the size of the printer page in pixels. These may not be the
same as the values returned from \helpref{wxDC::GetSize}{wxdcgetsize} if
the printout is being used for previewing, since in this case, a
memory device context is used, using a bitmap size reflecting the current
preview zoom. The application must take this discrepancy into account if
previewing is to be supported.

\membersection{wxPrintout::GetPPIPrinter}

\func{void}{GetPPIPrinter}{\param{int *}{w}, \param{int *}{h}}

Returns the number of pixels per logical inch of the printer device context.
Dividing the printer PPI by the screen PPI can give a suitable scaling
factor for drawing text onto the printer. Remember to multiply
this by a scaling factor to take the preview DC size into account.

\membersection{wxPrintout::GetPPIScreen}

\func{void}{GetPPIScreen}{\param{int *}{w}, \param{int *}{h}}

Returns the number of pixels per logical inch of the screen device context.
Dividing the printer PPI by the screen PPI can give a suitable scaling
factor for drawing text onto the printer. Remember to multiply
this by a scaling factor to take the preview DC size into account.

\membersection{wxPrintout::HasPage}

\func{Bool}{HasPage}{\param{int}{ pageNum}}

Should be overriden to return TRUE if the document has this page, or FALSE
if not. Returning FALSE signifies the end of the document. By default,
HasPage behaves as if the document has only one page.

\membersection{wxPrintout::IsPreview}

\func{Bool}{IsPreview}{\void}

Returns TRUE if the printout is currently being used for previewing.

\membersection{wxPrintout::OnBeginDocument}

\func{Bool}{OnBeginDocument}{\param{int}{ startPage}, \param{int}{ endPage}}

Called by the framework at the start of document printing. Return FALSE from
this function cancels the print job. OnBeginDocument is called once for every
copy printed.

The base wxPrintout::OnBeginDocument {\it must} be called (and the return value
checked) from within the overriden function, since it calls wxDC::StartDoc.

\membersection{wxPrintout::OnEndDocument}

\func{void}{OnEndDocument}{\void}

Called by the framework at the end of document printing. OnEndDocument
is called once for every copy printed.

The base wxPrintout::OnEndDocument {\it must} be called
from within the overriden function, since it calls wxDC::EndDoc.

\membersection{wxPrintout::OnBeginPrinting}

\func{void}{OnBeginPrinting}{\void}

Called by the framework at the start of printing. OnBeginPrinting is called once for every
print job (regardless of how many copies are being printed).

\membersection{wxPrintout::OnEndPrinting}

\func{void}{OnEndPrinting}{\void}

Called by the framework at the end of printing. OnEndPrinting
is called once for every print job (regardless of how many copies are being printed).

\membersection{wxPrintout::OnPreparePrinting}

\func{void}{OnPreparePrinting}{\void}

Called once by the framework before any other demands are made of the
wxPrintout object. This gives the object an opportunity to calculate the
number of pages in the document, for example.

\membersection{wxPrintout::OnPrintPage}

\func{Bool}{OnPrintPage}{\param{int}{ pageNum}}

Called by the framework when a page should be printed. Returning FALSE cancels
the print job. The application can use wxPrintout::GetDC to obtain a device
context to draw on.

\section{\class{wxPrintPreview}: wxObject}\label{wxprintpreview}

\overview{Printing framework overview}{printingoverview}

Objects of this class manage the print preview process. The object is passed
a wxPrintout object, and the wxPrintPreview object itself is passed to
a wxPreviewFrame object. Previewing is started by initializing and showing
the preview frame. Unlike wxPrinter::Print, flow of control returns to the application
immediately after the frame is shown.

See also \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
\helpref{wxPrintout}{wxprintout}, \helpref{wxPrinter}{wxprinter},\rtfsp
\helpref{wxPreviewCanvas}{wxpreviewcanvas}, \helpref{wxPreviewControlBar}{wxpreviewcontrolbar},\rtfsp
\helpref{wxPreviewFrame}{wxpreviewframe}.

\membersection{wxPrintPreview::wxPrintPreview}

\func{void}{wxPrintPreview}{\param{wxPrintout *}{printout}, \param{wxPrintout *}{printoutForPrinting},
\param{wxPrintData *}{data=NULL}}

Constructor. Pass a printout object, an optional printout object to be
used for actual printing, and the address of an optional
block of printer data, which will be copied to the print preview object's
print data.

If {\it printoutForPrinting} is non-NULL, a {\bf Print...} button will be placed on the
preview frame so that the user can print directly from the preview interface.

Do not explicitly delete the printout objects once this destructor has been
called, since they will be deleted in the wxPrintPreview constructor.
The same does not apply to the {\it data} argument.

\membersection{wxPrintPreview::\destruct{wxPrintPreview}}

\func{void}{\destruct{wxPrinter}}{\void}

Destructor. Deletes both print preview objects, so do not destroy these objects
in your application.

\membersection{wxPrintPreview::DrawBlankPage}

\func{Bool}{DrawBlankPage}{\param{wxCanvas *}{canvas}}

Draws a representation of the blank page into the canvas. Used
internally.

\membersection{wxPrintPreview::GetCanvas}

\func{wxCanvas *}{GetCanvas}{\void}

Gets the canvas used for displaying the print preview image.

\membersection{wxPrintPreview::GetCurrentPage}

\func{int}{GetCurrentPage}{\void}

Gets the page currently being previewed.

\membersection{wxPrintPreview::GetFrame}

\func{wxFrame *}{GetFrame}{\void}

Gets the frame used for displaying the print preview canvas
and control bar.

\membersection{wxPrintPreview::GetMaxPage}

\func{int}{GetMaxPage}{\void}

Returns the maximum page number.

\membersection{wxPrintPreview::GetMinPage}

\func{int}{GetMinPage}{\void}

Returns the minimum page number.

\membersection{wxPrintPreview::GetPrintData}

\func{wxPrintData\&}{GetPrintData}{\void}

Returns a reference to the internal print data.

\membersection{wxPrintPreview::GetPrintout}

\func{wxPrintout *}{GetPrintout}{\void}

Gets the preview printout object associated with the wxPrintPreview object.

\membersection{wxPrintPreview::GetPrintoutForPrinting}

\func{wxPrintout *}{GetPrintoutForPrinting}{\void}

Gets the printout object to be used for printing from within the preview interface,
or NULL if none exists.

\membersection{wxPrintPreview::PaintPage}

\func{Bool}{PaintPage}{\param{wxCanvas *}{canvas}}

This refreshes the preview canvas with the preview image.
It must be called from the preview canvas's OnPaint member.

The implementation simply blits the preview bitmap onto
the canvas, creating a new preview bitmap if none exists.

\membersection{wxPrintPreview::Print}

\func{Bool}{Print}{\param{Bool }{prompt}}

Invokes the print process using the second wxPrintout object
supplied in the wxPrintPreview constructor.
Will normally be called by the {\bf Print...} panel item on the
preview frame's control bar.

\membersection{wxPrintPreview::RenderPage}

\func{Bool}{RenderPage}{\param{int }{pageNum}}

Renders a page into a wxMemoryDC. Used internally by wxPrintPreview.

\membersection{wxPrintPreview::SetCanvas}

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

Sets the canvas to be used for displaying the print preview image.

\membersection{wxPrintPreview::SetCurrentPage}

\func{void}{SetCurrentPage}{\param{int}{ pageNum}}

Sets the current page to be previewed.

\membersection{wxPrintPreview::SetFrame}

\func{void}{SetFrame}{\param{wxFrame *}{frame}}

Sets the frame to be used for displaying the print preview canvas
and control bar.

\membersection{wxPrintPreview::SetPrintout}

\func{void}{SetPrintout}{\param{wxPrintout *}{printout}}

Associates a printout object with the wxPrintPreview object.

\membersection{wxPrintPreview::SetZoom}

\func{void}{SetZoom}{\param{int}{ percent}}

Sets the percentage preview zoom, and refreshes the preview canvas
accordingly.



\section{\class{wxQueryCol}: wxObject}\label{wxquerycol}

\overview{Overview}{wxquerycoloverview}

Every ODBC data column is represented by an instance of this class.

\membersection{wxQueryCol::wxQueryCol}

\func{void}{wxQueryCol}{\void}

Constructor. Sets the attributes of the column to default values.

\membersection{wxQueryCol::\destruct{wxQueryCol}}

\func{void}{\destruct{wxQueryCol}}{\void}

Destructor. Deletes the wxQueryField list.

\membersection{wxQueryCol::BindVar}

\func{void *}{BindVar}{\param{void *}{v}, \param{long}{ sz}}

Binds a user-defined variable to a column. Whenever a column is bound to a
variable, it will automatically copy the data of the current field into this
buffer (to a maximum of {\it sz} bytes).

\membersection{wxQueryCol::FillVar}

\func{void}{FillVar}{\param{int}{ recnum}}

Fills the bound variable with the data of the field recnum. When no variable
is bound to the column nothing will happen.

\membersection{wxQueryCol::GetData}

\func{void *}{GetData}{\param{int}{ field}}

Returns a pointer to the data of the field.

\membersection{wxQueryCol::GetName}

\func{char *}{GetName}{\void}

Returns the name of a column.
  
\membersection{wxQueryCol::GetType}

\func{short}{GetType}{\void}

Returns the data type of a column.

\membersection{wxQueryCol::GetSize}

\func{long}{GetSize}{\param{int}{ field}}

Return the size of the data of the field field.

\membersection{wxQueryCol::IsRowDirty}

\func{Bool}{IsRowDirty}{\param{int}{ field}}

Returns TRUE if the given field has been changed, but not saved.

\membersection{wxQueryCol::IsNullable}

\func{Bool}{IsNullable}{\void}
  
Returns TRUE if a column may contain no data.

\membersection{wxQueryCol::AppendField}

\func{void}{AppendField}{\param{void *}{buf}, \param{long}{ len}}

Appends a wxQueryField instance to the field list of the column. {\it len} bytes from\rtfsp
{\it buf} will be copied into the field's buffer.

\membersection{wxQueryCol::SetData}

\func{Bool}{SetData}{\param{int}{ field}, \param{void *}{buf}, \param{long}{ len}}

Sets the data of a field. This function finds the wxQueryField corresponding to\rtfsp
{\it field} and calls wxQueryField::SetData with {\it buf} and {\it len} arguments.

\membersection{wxQueryCol::SetName}

\func{void}{SetName}{\param{char *}{name}}

Sets the name of a column. Only useful when creating new tables or
appending columns.
 
\membersection{wxQueryCol::SetNullable}

\func{void}{SetNullable}{\param{Bool}{ nullable}}

Determines whether a column may contain no data. Only useful when creating new tables or
appending columns.

\membersection{wxQueryCol::SetFieldDirty}

\func{void}{SetFieldDirty}{\param{int}{ field}, \param{Bool }{dirty = TRUE}}

Sets the dirty tag of a given field.

\membersection{wxQueryCol::SetType}

\func{void}{SetType}{\param{short}{ type}}
  
Sets the data type of a column. Only useful when creating new tables or
appending columns.

\section{\class{wxQueryField}: wxObject}\label{wxqueryfield}

\overview{Overview}{wxqueryfieldoverview}

Represents the data item for one or several columns.

\membersection{wxQueryField::wxQueryField}

\func{wxQueryField}{\void}

Constructor. Sets type and size of the field to default values.
  
\membersection{wxQueryField::\destruct{wxQueryField}}

\func{void}{\destruct{wxQueryField}}{\void}

Destructor. Frees the associated memory depending on the field type.

\membersection{wxQueryField::AllocData}

\func{Bool}{AllocData}{\void}

Allocates memory depending on the size and type of the field.

\membersection{wxQueryField::ClearData}

\func{void}{ClearData}{\void}

Deletes the contents of the field buffer without deallocating the memory.

\membersection{wxQueryField::GetData}

\func{void *}{GetData}{\void}

Returns a pointer to the field buffer.

\membersection{wxQueryField::GetSize}

\func{long}{GetSize}{\void}

Returns the size of the field buffer.

\membersection{wxQueryField::GetType}

\func{short}{GetType}{\void}

Returns the type of the field (currently SQL\_CHAR, SQL\_VARCHAR or SQL\_INTEGER).
 
\membersection{wxQueryField::IsDirty}

\func{Bool}{IsDirty}{\void}

Returns TRUE if the data of a field has been changed, but not saved.

\membersection{wxQueryField::SetData}

\func{Bool}{SetData}{\param{void *}{data}, \param{long}{ sz}}

Allocates memory of the size {\it sz} and copies the contents of {\it d} into the
field buffer.
  
\membersection{wxQueryField::SetDirty}

\func{void}{SetDirty}{\param{Bool}{ dirty = TRUE}}

Sets the dirty tag of a field.

\membersection{wxQueryField::SetSize}

\func{void}{SetSize}{\param{long}{ size}}

Resizes the field buffer. Stored data will be lost.
  
\membersection{wxQueryField::SetType}

\func{void}{SetType}{\param{short }{type}}

Sets the type of the field. Currently the types SQL\_CHAR, SQL\_VARCHAR and
SQL\_INTEGER are supported.


\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{wxRecordSet}: wxObject}\label{wxrecordset}

\overview{Overview}{wxrecordsetoverview}

Each wxRecordSet represents an ODBC database query. You can make multiple queries
at a time by using multiple wxRecordSets with a wxDatabase or you can make
your queries in sequential order using the same wxRecordSet.

\membersection{wxRecordSet::wxRecordSet}

\func{void}{wxRecordSet}{\param{wxDatabase *}{db}, \param{int}{ type = wxOPEN\_TYPE\_DYNASET},
 \param{int}{ opt = wxOPTION\_DEFAULT}}

Constructor. {\it db} is a pointer to the wxDatabase instance you wish to use the
wxRecordSet with. Currently there are two possible values of {\it type}:

\begin{itemize}\itemsep=0pt
\item wxOPEN\_TYPE\_DYNASET: Loads only one record at a time into memory. The other
data of the result set will be loaded dynamically when
moving the cursor. This is the default type.
\item wxOPEN\_TYPE\_SNAPSHOT: Loads all records of a result set at once. This will
need much more memory, but will result in
faster access to the ODBC data.
\end{itemize}

The {\it option} parameter is not used yet.

The constructor appends the wxRecordSet object to the parent database's list of
wxRecordSet objects, for later destruction when the wxDatabase is destroyed.

\membersection{wxRecordSet::\destruct{wxRecordSet}}

\func{void}{\destruct{wxRecordSet}}{\void}

Destructor. All data except that stored in user-defined variables will be lost.
It also unlinks the wxRecordSet object from the parent database's list of
wxRecordSet objects.
 
\membersection{wxRecordSet::AddNew}

\func{void}{AddNew}{\void}

Not implemented.

\membersection{wxRecordSet::BeginQuery}

\func{Bool}{BeginQuery}{\param{int}{ openType}, \param{char *}{sql = NULL}, \param{int}{ options = wxOPTION\_DEFAULT}}

Not implemented.

\begin{comment}
// beg for comment
// Shall we use SQLPrepare() here ? Usually the Query() function can be
// called without a former call of BeginQuery().
\end{comment}

\membersection{wxRecordSet::BindVar}

\func{void *}{BindVar}{\param{int}{ col}, \param{void *}{buf}, \param{long}{ size}}

Binds a user-defined variable to the column col. Whenever the current field's
data changes, it will be copied into buf (maximum {\it size} bytes).

\func{void *}{BindVar}{\param{const char *}{col}, \param{void *}{buf}, \param{long}{ size}}

The same as above, but uses the column name as the identifier.


\membersection{wxRecordSet::CanAppend}

\func{Bool}{CanAppend}{\void}

Not implemented.

\membersection{wxRecordSet::Cancel}

\func{void}{Cancel}{\void}

Not implemented.

\membersection{wxRecordSet::CanRestart}

\func{Bool}{CanRestart}{\void}

Not implemented.

\membersection{wxRecordSet::CanScroll}

\func{Bool}{CanScroll}{\void}

Not implemented.

\membersection{wxRecordSet::CanTransact}

\func{Bool}{CanTransact}{\void}

Not implemented.

\membersection{wxRecordSet::CanUpdate}

\func{Bool}{CanUpdate}{\void}

Not implemented.

\membersection{wxRecordSet::ConstructDefaultSQL}

\func{Bool}{ConstructDefaultSQL}{\void}

Not implemented.

\membersection{wxRecordSet::Delete}

\func{Bool}{Delete}{\void}

Deletes the current record. Not implemented.

\membersection{wxRecordSet::Edit}

\func{void}{Edit}{\void}

Not implemented.

\membersection{wxRecordSet::EndQuery}

\func{Bool}{EndQuery}{\void}

Not implemented.

\membersection{wxRecordSet::ExecuteSQL}\label{wxrecordsetexecutesql}

\func{Bool}{ExecuteSQL}{\param{char *}{sql}}

Directly executes a SQL statement. The data will be presented as a normal
result set. Note that the recordset must have been created as a snapshot, not
dynaset. Dynasets will be implemented in the near future.

Examples of common SQL statements are given in \helpref{A selection of SQL commands}{sqlcommands}.

\membersection{wxRecordSet::FillVars}

\func{void}{FillVars}{\param{int}{ recnum}}

Fills in the user-defined variables of the columns. You can set these
variables with wxQueryCol::BindVar. This function will be automatically
called after every successful database operation.

\membersection{wxRecordSet::GetColName}

\func{char *}{GetColName}{\param{int}{ col}}

Returns the name of the column at position {\it col}. Returns NULL if {\it col} does not
exist.

\membersection{wxRecordSet::GetColType}

\func{short}{GetColType}{\param{int}{ col}}

Returns the data type of the column at position {\it col}. Returns SQL\_TYPE\_NULL
if {\it col} does not exist.

\func{short}{GetColType}{\param{const char *}{ name}}

The same as above, but uses the column name as the identifier.

See \helpref{ODBC SQL data types}{sqltypes} for a list
of possible data types.

\membersection{wxRecordSet::GetColumns}

\func{Bool}{GetColumns}{\param{char *}{table = NULL}}

Returns the columns of the table with the specified name. If no name is
given the class member {\it tablename} will be used. If both names are NULL
nothing will happen. The data will be presented as a normal result set, organized
as follows:

\begin{twocollist}
\twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
\twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
\twocolitem{2 (VARCHAR)}{TABLE\_NAME}
\twocolitem{3 (VARCHAR)}{COLUMN\_NAME}
\twocolitem{4 (SMALLINT)}{DATA\_TYPE}
\twocolitem{5 (VARCHAR)}{TYPE\_NAME}
\twocolitem{6 (INTEGER)}{PRECISION}
\twocolitem{7 (INTEGER)}{LENGTH}
\twocolitem{8 (SMALLINT)}{SCALE}
\twocolitem{9 (SMALLINT)}{RADIX}
\twocolitem{10 (SMALLINT)}{NULLABLE}
\twocolitem{11 (VARCHAR)}{REMARKS}
\end{twocollist}

\membersection{wxRecordSet::GetCurrentRecord}

\func{long}{GetCurrentRecord}{\void}

Not implemented.

\membersection{wxRecordSet::GetDatabase}{\void}

\func{wxDatabase *}{GetDatabase}{\void}

Returns the wxDatabase object bound to a wxRecordSet.

\membersection{wxRecordSet::GetDataSources}\label{wxrecordsetgetdatasources}

\func{Bool}{GetDataSources}{\void}

Gets the currently-defined data sources via the ODBC manager. The data will be presented
as a normal result set. See the documentation for the ODBC function SQLDataSources for how the data
is organized.

Example:
  
\begin{verbatim}
  wxDatabase Database;

  wxRecordSet *Record = new wxRecordSet(&Database);

  if (!Record->GetDataSources()) {
    char buf[300];
    sprintf(buf, "%s %s\n", Database.GetErrorClass(), Database.GetErrorMessage());
    frame->output->SetValue(buf);
  }
  else {
    do {
      frame->DataSource->Append((char*)Record->GetFieldDataPtr(0, SQL_CHAR));
    } while (Record->MoveNext());
  }
\end{verbatim}

\membersection{wxRecordSet::GetDefaultConnect}

\func{char *}{GetDefaultConnect}{\void}

Not implemented.

\membersection{wxRecordSet::GetDefaultSQL}

\func{char *}{GetDefaultSQL}{\void}

Not implemented.

\membersection{wxRecordSet::GetErrorCode}

\func{wxRETCODE}{GetErrorCode}{\void}

Returns the error code of the last ODBC action. This will be one of:

\begin{twocollist}\itemsep=0pt
\twocolitem{SQL\_ERROR}{General error.}
\twocolitem{SQL\_INVALID\_HANDLE}{An invalid handle was passed to an ODBC function.}
\twocolitem{SQL\_NEED\_DATA}{ODBC expected some data.}
\twocolitem{SQL\_NO\_DATA\_FOUND}{No data was found by this ODBC call.}
\twocolitem{SQL\_SUCCESS}{The call was successful.}
\twocolitem{SQL\_SUCCESS\_WITH\_INFO}{The call was successful, but further information can be
obtained from the ODBC manager.}
\end{twocollist}

\membersection{wxRecordSet::GetFieldData}\label{wxrecordsetgetfielddata}

\func{Bool}{GetFieldData}{\param{int}{ col}, \param{int}{ dataType}, \param{void *}{dataPtr}}

Copies the current data of the column at position {\it col} into the buffer
\rtfsp{\it dataPtr}. To be sure to get the right type of data, the user has to pass the
correct data type. The function returns FALSE if {\it col} does not
exist or the wrong data type was given.

\func{Bool}{GetFieldData}{\param{const char *}{name}, \param{int}{ dataType}, \param{void *}{dataPtr}}

The same as above, but uses the column name as the identifier.

See \helpref{ODBC SQL data types}{sqltypes} for a list
of possible data types.

\membersection{wxRecordSet::GetFieldDataPtr}\label{wxrecordsetgetfielddataptr}

\func{void *}{GetFieldDataPtr}{\param{int}{ col}, \param{int}{ dataType}}

Returns the current data pointer of the column at position {\it col}.
To be sure to get the right type of data, the user has to pass the
data type. Returns NULL if {\it col} does not exist or if {\it dataType} is
incorrect.

\func{void *}{GetFieldDataPtr}{\param{const char *}{name}, \param{int}{ dataType}}

The same as above, but uses the column name as the identifier.

See \helpref{ODBC SQL data types}{sqltypes} for a list
of possible data types.

\membersection{wxRecordSet::GetFilter}

\func{char *}{GetFilter}{\void}

Returns the current filter.

\membersection{wxRecordSet::GetNumberCols}

\func{long}{GetNumberCols}{\void}

Returns the number of columns in the result set.
  
\membersection{wxRecordSet::GetNumberFields}

\func{int}{GetNumberFields}{\void}

Not implemented.

\membersection{wxRecordSet::GetNumberParams}

\func{int}{GetNumberParams}{\void}

Not implemented.

\membersection{wxRecordSet::GetNumberRecords}

\func{long}{GetNumberRecords}{\void}

Returns the number of records in the result set.
  
\membersection{wxRecordSet::GetOptions}

\func{int}{GetOptions}{\void}

Returns the options of the wxRecordSet. Options are not supported yet.

\membersection{wxRecordSet::GetResultSet}

\func{Bool}{GetResultSet}{\void}

Copies the data presented by ODBC into wxRecordSet. Depending on the
wxRecordSet type all or only one record(s) will be copied.
Usually this function will be called automatically after each successful
database operation.
  
\membersection{wxRecordSet::GetSortString}

\func{char *}{GetSortString}{\void}

Not implemented.
  
\membersection{wxRecordSet::GetSQL}

\func{char *}{GetSQL}{\void}

Not implemented.

\membersection{wxRecordSet::GetTableName}

\func{char *}{GetTableName}{\void}

Returns the name of the current table.
  
\membersection{wxRecordSet::GetTables}

\func{Bool}{GetTables}{\void}

Gets the tables of a database. The data will be presented as a normal result
set, organized as follows:

\begin{twocollist}
\twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
\twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
\twocolitem{2 (VARCHAR)}{TABLE\_NAME}
\twocolitem{3 (VARCHAR)}{TABLE\_TYPE (TABLE, VIEW, SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY,
ALIAS, SYNONYM, or database-specific type)}
\twocolitem{4 (VARCHAR)}{REMARKS}
\end{twocollist}

\membersection{wxRecordSet::GetType}

\func{int}{GetType}{\void}

Returns the type of the wxRecordSet: wxOPEN\_TYPE\_DYNASET or
wxOPEN\_TYPE\_SNAPSHOT. See the wxRecordSet description for details.

\membersection{wxRecordSet::GoTo}

\func{Bool}{GoTo}{\param{long}{ n}}

Moves the cursor to the record with the number n, where  the first record
has the number 0.
  
\membersection{wxRecordSet::IsBOF}

\func{Bool}{IsBOF}{\void}

Returns TRUE if the user tried to move the cursor before the first record
in the set.

\membersection{wxRecordSet::IsFieldDirty}

\func{Bool}{IsFieldDirty}{\param{int}{ field}}

Returns TRUE if the given field has been changed but not saved yet.

\func{Bool}{IsFieldDirty}{\param{const char *}{name}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::IsFieldNull}

\func{Bool}{IsFieldNull}{\param{int}{ field}}

Returns TRUE if the given field has no data.

\func{Bool}{IsFieldNull}{\param{const char *}{ name}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::IsColNullable}

\func{Bool}{IsColNullable}{\param{int}{ col}}

Returns TRUE if the given column may contain no data.

\func{Bool}{IsColNullable}{\param{const char *}{name}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::IsEOF}

\func{Bool}{IsEOF}{\void}

Returns TRUE if the user tried to move the cursor behind the last record
in the set.

\membersection{wxRecordSet::IsDeleted}

\func{Bool}{IsDeleted}{\void}

Not implemented.
  
\membersection{wxRecordSet::IsOpen}

\func{Bool}{IsOpen}{\void}

Returns TRUE if the parent database is open.

\membersection{wxRecordSet::Move}

\func{Bool}{Move}{\param{long}{ rows}}

Moves the cursor a given number of rows. Negative values are allowed.
  
\membersection{wxRecordSet::MoveFirst}

\func{Bool}{MoveFirst}{\void}

Moves the cursor to the first record.
  
\membersection{wxRecordSet::MoveLast}

\func{Bool}{MoveLast}{\void}

Moves the cursor to the last record.
  
\membersection{wxRecordSet::MoveNext}\label{wxrecordsetmovenext}

\func{Bool}{MoveNext}{\void}

Moves the cursor to the next record.
  
\membersection{wxRecordSet::MovePrev}\label{wxrecordsetmoveprev}

\func{Bool}{MovePrev}{\void}

Moves the cursor to the previous record.
  
\membersection{wxRecordSet::Query}

\func{Bool}{Query}{\param{char *}{columns}, \param{char *}{table}, \param{char *}{filter = NULL}}

Start a query. An SQL string of the following type will automatically be
generated and executed: ``SELECT columns FROM table WHERE filter".

\membersection{wxRecordSet::RecordCountFinal}

\func{Bool}{RecordCountFinal}{\void}

Not implemented.
  
\membersection{wxRecordSet::Requery}

\func{Bool}{Requery}{\void}

Re-executes the last query. Not implemented.

\membersection{wxRecordSet::SetFieldDirty}

\func{void}{SetFieldDirty}{\param{int}{ field}, \param{Bool}{ dirty = TRUE}}

Sets the dirty tag of the field field. Not implemented.

\func{void}{SetFieldDirty}{\param{const char *}{name}, \param{Bool}{ dirty = TRUE}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::SetDefaultSQL}

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

Not implemented.

\membersection{wxRecordSet::SetFieldNull}

\func{void}{SetFieldNull}{\param{void *}{p}, \param{Bool }{isNull = TRUE}}

Not implemented.

\membersection{wxRecordSet::SetOptions}

\func{void}{SetOptions}{\param{int}{ opt}}

Sets the options of the wxRecordSet. Not implemented.
  
\membersection{wxRecordSet::SetTableName}

\func{void}{SetTableName}{\param{char *}{tablename}}

Specify the name of the table you want to use.
  
\membersection{wxRecordSet::SetType}

\func{void}{SetType}{\param{int}{ type}}

Sets the type of the wxRecordSet. See the wxRecordSet class description for details.

\membersection{wxRecordSet::Update}

\func{Bool}{Update}{\void}

Writes back the current record. Not implemented.



\section{\class{wxScreenDC}: wxCanvasDC}\label{wxscreendc}

An instance of this class may be created to access the whole screen.
Free the instance as soon as it has been used, since there are a limited
number of device contexts in some environments.

Note that this hasn't been tested yet.

See \helpref{wxDC}{wxdc} for further information on device contexts.

\membersection{wxScreenDC::wxScreenDC}

\func{void}{wxScreenDC}{\void}

Constructor.

\section{\class{wxServer}: wxIPCObject}\label{wxserver}

\overview{IPC overview}{ipcoverview}

A wxServer object represents the server part of a client-server DDE
(Dynamic Data Exchange) conversation (available under both Windows
and UNIX).

\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 = wxHORIZONTAL}, \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 style} parameter may be wxHORIZONTAL to denote a horizontal
slider, or wxVERTICAL for a vertical slider.

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}\rtfsp
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{wxString}: wxObject}\label{wxstring}

String class, to be documented.

\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}\rtfsp
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}: wxItem}\label{wxtext}

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}\itemsep=0pt
\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.

The {\it style} parameter can be a bit list of the following:

\begin{twocollist}
\twocolitem{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.}
\twocolitem{wxPASSWORD}{The text will be echoed as asterisks.}
\twocolitem{wxREADONLY}{The text will not be user-editable.}
\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 items.

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

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

Destructor, destroying the text item.

\membersection{wxText::Copy}

\func{void}{Copy}{\void}

Copies the selected text to the clipboard under Motif and MS Windows.

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

\func{void}{Cut}{\void}

Copies the selected text to the clipboard and removes the selection, under Motif and MS Windows.

\membersection{wxText::GetValue}

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

Gets a pointer to the current value. Copy this for long-term use.

\membersection{wxText::Paste}

\func{void}{Paste}{\void}

Pastes text from the clipboard to the text item, under Motif and MS Windows.

\membersection{wxText::SetEditable}

\func{void}{SetEditable}{\param{Bool}{ editable}}

Makes the text item editable (TRUE) or read-only (FALSE).

\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 (or a panel, on some platforms),
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.

For compilers other than Borland C++, this class
also derives from streambuf. You can then use instances of wxTextWindow
for the usual ostream operations, for example:

\begin{verbatim}
  wxTextWindow *textwin = new wxTextWindow(...);

  ostream stream(textwin);
  stream << "Hello! C++ streams are neat." << endl;
\end{verbatim}

\membersection{wxTextWindow::wxTextWindow}\label{constrtextwindow}

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

Constructor, for deriving classes.

\func{void}{wxTextWindow}{\param{wxWindow *}{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.

Under Windows and Motif, the parent can be either a frame or panel.
Under XView, the parent must be a frame.

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{wxWindow *}{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}{SetSelection}{\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::OnChar}

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

In Motif and Windows, it is possible to intercept character
input by overriding this member. Call this function
to let the default behaviour take place; not calling
it results in the character being ignored. You can
replace the {\it keyCode} member of {\it event} to
translate keystrokes.

Note that Windows and Motif have different ways
of implementing the default behaviour. In Windows,
calling wxTextWindow::OnChar immediately
processes the character. In Motif,
calling this function simply sets a flag
to let default processing happen. This might affect
the way in which you write your OnChar function
on different platforms.

Under Windows, the wxNATIVE\_IMPL flag must
be passed to the wxTextWindow constructor
if overriding OnChar is to have any effect.

See \helpref{wxEvtHandler::OnChar}{wxevthandleronchar} and\rtfsp
\helpref{wxKeyEvent}{wxkeyevent} for more details
of the keystroke event.

\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{wxToolBar}: wxCanvas}\label{wxtoolbar}

\overview{Overview}{wxtoolbaroverview}

A wxToolBar is a canvas containing mouse-sensitive bitmaps.
Include the file {\tt wx\_tbar.h} to use this class.

\membersection{wxToolBar::wxToolBar}

\func{void}{wxToolBar}{\param{wxFrame *}{frame}, \param{int}{ x = 0}, \param{int}{ y = 0},\\
  \param{int}{ width = -1}, \param{int}{ height = -1}, \param{long}{ style = 0},\\
  \param{int}{ orientation = wxVERTICAL}, \param{int}{ nRowsOrColumns = 2}}

Constructs a toolbar canvas, with the same arguments as a canvas plus
an orientation (wxVERTICAL or wxHORIZONTAL) and the number of rows or
columns, whose meaning depends on the orientation.  If laid out
vertically, the final argument refers to the number of rows to draw
before the next column is started; if horizontal, it refers to the
number of columns to draw before the next row is started.

\membersection{wxToolBar::\destruct{wxToolBar}}

\func{void}{\destruct{wxToolBar}}{\void}

Toolbar destructor.

\membersection{wxToolBar::AddTool}

\func{wxToolBarTool *}{AddTool}{\param{int}{ toolIndex},\\
  \param{wxBitmap *}{ bitmap1}, \param{wxBitmap *}{ bitmap2 = NULL},\\
  \param{Bool}{ isToggle = FALSE},\\
  \param{float}{ xPos = -1}, \param{float}{ yPos = -1}\\
  \param{wxObject *}{clientData}}

Adds a tool to the toolbar. The {\it toolIndex} is an integer by which
the tool may be identified in subsequent operations.  {\it isToggle}\rtfsp
specifies whether the tool is a toggle or not: a toggle tool may be in
two states, whereas a non-toggle tool is just a button.

The first bitmap is the primary tool bitmap for toggle and button
tools. The second bitmap specifies the on-state bitmap for a toggle
tool. If this is NULL, either an inverted version of the primary bitmap is
used for the on-state of a toggle tool (monochrome displays) or a black
border is drawn around the tool (colour displays).

The arguments {\it xPos} and {\it yPos} allow the programmer to specify
the position of the tool if automatic layout is not suitable. For
example, a toolbar along the top of a window may have groups of tools,
with spacing between groups. In this case, specifying {\it xPos} is all
that is required, and {\it yPos} will take its value from the current
vertical spacing value.

{\it clientData} is an optional pointer to client data which can be
retrieved later using {\bf GetToolClientData}.

\membersection{wxToolBar::DrawTool}

\func{void}{DrawTool}{\param{wxMemoryDC\& }{memDC}, \param{wxToolBarTool *}{tool}}

Draws the specified tool onto the canvas using the given memory device context.
Used internally, and should not need to be used by the programmer.

\membersection{wxToolBar::EnableTool}

\func{void}{EnableTool}{\param{int }{toolIndex}, \param{Bool}{ enable}}

Enables or disables the tool. Not currently implemented, but should give some
indication of whether the tool is active.

\membersection{wxToolBar::FindToolForPosition}

\func{wxToolBarTool *}{FindToolForPosition}{\param{float}{ x}, \param{float}{ y}}

Find a tool for the given mouse position, or return NULL. Used
internally, and should not need to be used by the programmer.

\membersection{wxToolBar::GetMaxSize}

\func{void}{GetMaxSize}{\param{float *}{w}, \param{float *}{h}}

Gets the maximum size taken up by the tools after layout, including margins.
This can be used to size a frame around the toolbar canvas.

\membersection{wxToolBar::GetToolClientData}

\func{wxObject *}{GetToolClientData}{\param{int }{toolIndex}}

Get any client data associated with the tool.

\membersection{wxToolBar::GetToolEnabled}

\func{Bool}{GetToolEnabled}{\param{int }{toolIndex}}

Returns TRUE if the tool is enabled, FALSE otherwise.

\membersection{wxToolBar::GetToolState}

\func{Bool}{GetToolState}{\param{int }{toolIndex}}

Gets the on/off state of a toggle tool.

\membersection{wxToolBar::Layout}

\func{void}{Layout}{\void}

Called by the application after the tools have been added to
automatically lay the tools out on the canvas. If you have given
absolute positions when adding the tools, do not call this.

\membersection{wxToolBar::OnLeftClick}

\func{Bool}{OnLeftClick}{\param{int}{ toolIndex}, \param{Bool}{ toggleDown}}

Called when the user clicks on a tool with the left mouse button. The
programmer should override this function to detect left tool clicks. {\it
toolIndex} is the identifier passed to {\bf AddTool}, and {\it
toggleDown} is TRUE if the tool is a toggle and the toggle is down,
otherwise is FALSE.

If the tool is a toggle and this function returns FALSE, the toggle
toggle state (internal and visual) will not be changed. This provides a way of
specifying that toggle operations are not permitted in some circumstances.

\membersection{wxToolBar::OnMouseEnter}

\func{void}{OnMouseEnter}{\param{int}{ toolIndex}}

This is called when the mouse moves into a tool ({\it toolIndex} is
greater than -1) or out of the toolbox ({\it toolIndex} is -1). The
programmer can override this to provide extra information about the tool,
such as a short description on the status line. Icons are not always as
intuitive as they're cracked up to be!

\membersection{wxToolBar::OnRightClick}

\func{void}{OnRightClick}{\param{int}{ toolIndex}, \param{float}{ x}, \param{float}{ y}}

Called when the user clicks on a tool with the right mouse button. The
programmer should override this function to detect right tool clicks.
{\it toolIndex} is the identifier passed to {\bf AddTool}, and {\it x}
and {\it y} give the mouse cursor position.

A typical use of this member might be to pop up a menu.

\membersection{wxToolBar::SetMargins}

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

Set the values to be used as margins and spacing for the tools. This must be
called before the tools are added if absolute positioning is to be used, and the
default (zero-size) margins are to be overridden.

\membersection{wxToolBar::ToggleTool}

\func{void}{ToggleTool}{\param{int }{toolIndex}, \param{Bool}{ toggle}}

Toggles a tool on or off.

\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}\rtfsp
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}\itemsep=0pt
\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{wxView}: wxEvtHandler}\label{wxview}

\overview{Overview}{wxviewoverview}

The view class can be used to model the viewing and editing component of
an application's file-based data. It is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxDocument}{wxdocument}, \helpref{wxDocTemplate}{wxdoctemplate}
and \helpref{wxDocManager}{wxdocmanager} classes.

\membersection{wxView::viewDocument}

\member{wxDocument *}{viewDocument}

The document associated with this view. There may be more than one view per
document, but there can never be more than one document for one view.

\membersection{wxView::viewFrame}

\member{wxFrame *}{viewFrame}

Frame associated with the view, if any.

\membersection{wxView::viewTypeName}

\member{char *}{viewTypeName}

The view type name given to the wxDocTemplate constructor, copied to this
variable when the view is created. Not currently used by the framework.

\membersection{wxView::wxView}

\func{void}{wxView}{\void}

Constructor. Define your own default constructor to initialize application-specific
data.

\membersection{wxView::\destruct{wxView}}

\func{void}{\destruct{wxView}}{\void}

Destructor. Removes itself from the document's list of views.

\membersection{wxView::Activate}

\func{void}{Activate}{\param{Bool}{ activate}}

Call this from your view frame's OnActivate member to tell the framework which view is
currently active. If your windowing system doesn't call OnActivate, you may need to
call this function from OnMenuCommand or any place where you know the view must
be active, and the framework will need to get the current view.

The prepackaged view frame wxDocChildFrame calls wxView::Activate from its OnActivate member
and from its OnMenuCommand member.

This function calls wxView::OnActivateView.

\membersection{wxView::Close}

\func{Bool}{Close}{\param{Bool}{ deleteWindow = TRUE}}

Closes the view by calling OnClose. If {\it deleteWindow} is TRUE, this function should
delete the window associated with the view.

\membersection{wxView::GetDocument}

\func{wxDocument *}{GetDocument}{\void}

Gets a pointer to the document associated with the view.

\membersection{wxView::GetDocumentManager}

\func{wxDocumentManager *}{GetDocumentManager}{\void}

Returns a pointer to the document manager instance associated with this view.

\membersection{wxView::GetFrame}

\func{wxFrame *}{GetFrame}{\void}

Gets the frame associated with the view (if any).

\membersection{wxView::GetViewName}

\func{char *}{GetViewName}{\void}

Gets the name associated with the view (passed to the wxDocTemplate constructor).
Not currently used by the framework.

\membersection{wxView::OnActivateView}

\func{void}{OnActivateView}{\param{Bool }{activate}, \param{wxView *}{activeView}, \param{wxView *}{deactiveView}}

Called when a view is activated by means of wxView::Activate. The default implementation does
nothing.

\membersection{wxView::OnChangeFilename}

\func{void}{OnChangeFilename}{\void}

Called when the filename has changed. The default implementation constructs a
suitable title and sets the title of the view frame (if any).

\membersection{wxView::OnClose}

\func{Bool}{OnClose}{\param{Bool}{ deleteWindow}}

Implements closing behaviour. The default implementation calls wxDocument::Close
to close the associated document. Does not delete the view. The application
may wish to do some cleaning up operations in this function, {\it if} a
call to wxDocument::Close succeeded. For example, if your application's
all share the same canvas, you need to disassociate the canvas from the view
and perhaps clear the canvas. If {\it deleteWindow} is TRUE, delete the
frame associated with the view.

\membersection{wxView::OnCreate}

\func{Bool}{OnCreate}{\param{wxDocument *}{doc}, \param{long}{ flags}}

Called just after view construction to give the view a chance to initialize
itself based on the passed document and flags (unused). By default, simply
returns TRUE. If the function returns FALSE, the view will be deleted.

The predefined document child frame, wxDocChildFrame, calls this function
automatically.

\membersection{wxView::OnCreatePrintout}

\func{wxPrintout *}{OnCreatePrintout}{\void}

If the printing framework is enabled in the library, this function returns a
\rtfsp\helpref{wxPrintout}{wxprintout} object for the purposes of printing. It should create a new object
everytime it is called; the framework will delete objects it creates.

By default, this function returns an instance of wxDocPrintout, which prints
and previews one page by calling wxView::OnDraw.

Override to return an instance of a class other than wxDocPrintout.

\membersection{wxView::OnUpdate}

\func{void}{OnUpdate}{\param{wxView *}{sender}, \param{wxObject *}{hint}}

Called when the view should be updated. {\it sender} is a pointer to the view
that sent the update request, or NULL if no single view requested the update (for instance,
when the document is opened). {\it hint} is as yet unused but may in future contain
application-specific information for making updating more efficient.

\membersection{wxView::SetDocument}

\func{void}{SetDocument}{\param{wxDocument *}{doc}}

Associates the given document with the view. Normally called by the
framework.

\membersection{wxView::SetFrame}

\func{void}{SetFrame}{\param{wxFrame *}{frame}}

Sets the frame associated with this view. The application should call this
if possible, to tell the view about the frame.

\membersection{wxView::SetViewName}

\func{void}{SetViewName}{\param{char *}{name}}

Sets the view type name. Should only be called by the framework.


\section{\class{wxWindow}: wxObject}\label{wxwindow}

\overview{Event handling overview}{eventhandlingoverview}

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

\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::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::GetConstraints}\label{wxwindowgetconstraints}

\func{wxLayoutConstraints *}{GetConstraints}{\void}

Gets a pointer to the window's layout constraints (if any).

\membersection{wxWindow::GetEventHandler}\label{wxwindowgeteventhandler}

\func{wxEvtHandler *}{GetEventHandler}{\void}

Gets the event handler for this window. By default, the window is its
own event handler. Use this function if you wish to manually call an event handler
function (such as OnPaint).

See \helpref{wxEvtHandler}{wxevthandler}.

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

\func{char *}{GetName}{\void}

Returns a pointer to internal data containing the window's name. This name is not guaranteed
to be unique; it is up to the programmer to supply an appropriate name.

\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::GetUserEditMode}\label{getusereditmode}

\func{Bool}{GetUserEditMode}{\void}

Returns TRUE if the window is in user interface edit mode.

See \helpref{wxWindow::SetUserEditMode}{setusereditmode} for
further details.

\membersection{wxWindow::GetWindowStyleFlag}

\func{long}{GetWindowStyleFlag}{\void}

Gets the window style that was passed to the consructor or {\bf Create}
member.

\membersection{wxWindow::Layout}\label{wxwindowlayout}

\func{void}{Layout}{\void}

Invokes the constraint-based layout algorithm for this window. It is called
automatically by the default {\bf wxWindow::OnSize} member.

\membersection{wxWindow::Move}

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

Moves the window to the given position.

Implementations of SetSize can also implicitly implement the
wxWindow::Move function, which is defined in the base wxWindow class
as the call:

\begin{verbatim}
  SetSize(x, y, -1, -1, wxSIZE_USE_EXISTING);
\end{verbatim}

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

\func{void}{Refresh}{\void}

Causes a message or event to be generated to repaint the
window.

\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::SetAutoLayout}\label{winsetautolayout}

\func{void}{SetAutoLayout}{\param{Bool}{ autoLayout}}

Set this to TRUE if you wish the Layout function to be called
from within wxWindow::OnSize functions (when the window is resized).

See also \helpref{SetConstraints}{wxwindowsetconstraints}.

\membersection{wxWindow::SetConstraints}\label{wxwindowsetconstraints}

\func{void}{SetConstraints}{\param{wxLayoutConstraints *}{constraints}}

Sets the window to have the given layout constraints. The window
will then own the object, and will take care of its deletion.
If an existing layout constraints object is already owned by the
window, it will be deleted.

Pass NULL to this function to disassociate and delete the window's
constraints.

You must call \helpref{wxWindow::SetAutoLayout}{winsetautolayout} to tell a window to use
the constraints automatically in OnSize; otherwise, you must
override OnSize and call Layout explicitly.

\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},
 \param{int}{ sizeFlags = wxSIZE\_AUTO}}

\func{void}{SetSize}{\param{int}{ width}, \param{int}{ height}}

This sets the size and/or position of the entire window in pixels.
The second form is a convenience for calling the first form with default
x and y parameters, and must be used with non-default width and height values.

The first form sets the position and optionally size, of the window.
Parameters may be -1 to indicate either that a default should be supplied
by wxWindows, or that the current value of the dimension should be used.
The behaviour is controlled by {\it sizeFlags}, which is a bit list of the
following:

\begin{itemize}
\itemsep=0pt
\item wxSIZE\_AUTO\_WIDTH (1): a -1 width value is taken to indicate
a wxWindows-supplied default width.
\item wxSIZE\_AUTO\_HEIGHT (2): a -1 height value is taken to indicate
a wxWindows-supplied default width.
\item wxSIZE\_AUTO (3): -1 size values are taken to indicate
a wxWindows-supplied default size.
\item wxSIZE\_USE\_EXISTING (0): existing dimensions should be used
if -1 values are supplied.
\end{itemize}

In versions of wxWindows prior to 1.61 (c), it was not always
clear what interpretation was being used. Now implementations
of SetSize can also implicitly implement the wxWindow::Move function,
which is defined as the call:

\begin{verbatim}
  SetSize(x, y, -1, -1, wxSIZE_USE_EXISTING);
\end{verbatim}

\membersection{wxWindow::SetClientSize}

\func{void}{SetClientSize}{\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::SetEventHandler}\label{wxwindowseteventhandler}

\func{void}{SetEventHandler}{\param{wxEvtHandler *}{handler}}

Sets the event handler for this window. By default, the window is its
own event handler. See \helpref{wxEvtHandler}{wxevthandler}.

\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::SetUserEditMode}\label{setusereditmode}

\func{void}{SetUserEditMode}{\param{Bool}{ editable}}

Sets a flag indicating that the user can 'edit' the interface.
This is for the use of visual user interface building tools, and
currently only works for wxPanel and wxDialogBox.

When this mode is on, the windows stop having their normal
functionality and instead receives OnEvent calls that the
application can intercept. In particular, the base wxPanel
class implements panel item moving and sizing, and
passes left and right click events from the items and panel
to the application via functions such as OnLeftClick.
The application might pop up a menu or select/deselect items
in response to these calls.

See also \helpref{wxWindow::GetUserEditMode}{getusereditmode}.

\membersection{wxWindow::Show}

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

If {\it show} is TRUE, displays the window and brings it to the front.  Otherwise,
hides the window.

\chapter{Functions}\label{functions}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}

The functions defined in wxWindows are described here.

\section{File functions}\label{filefunctions}

See also \helpref{wxPathList}{wxpathlist}.

\membersection{::wxDirExists}

\func{Bool}{wxDirExists}{\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{::wxFileExists}

\func{Bool}{wxFileExists}{\param{char *}{filename}}

Returns TRUE if the file exists.

\membersection{::wxFileNameFromPath}

\func{char *}{wxFileNameFromPath}{\param{char *}{path}}

Returns a temporary pointer to the filename for a full path.
Copy this pointer for long-term use.

\membersection{::wxIsAbsolutePath}

\func{Bool}{wxIsAbsolutePath}{\param{char *}{filename}}

Returns TRUE if the argument is an absolute filename, i.e. with a slash
or drive name at the beginning.

\membersection{::wxPathOnly}

\func{char *}{wxPathOnly}{\param{char *}{path}}

Returns a temporary pointer to the directory part of the filename. Copy this
pointer for long-term use.

\membersection{::wxUnix2DosFilename}

\func{void}{wxUnix2DosFilename}{\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{::wxStringMatch}

\func{Bool}{wxStringMatch}{\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.

\membersection{::wxStringEq}

\func{Bool}{wxStringEq}{\param{char *}{s1}, \param{char *}{s2}}

A macro defined as:

\begin{verbatim}
#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
\end{verbatim}

\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}

\func{Bool}{wxTransferFileToStream}{\param{char *}{filename}, \param{ostream\& }{stream}}

Copies the given file to {\it stream}. Useful when converting an old application to
use streams (within the document/view framework, for example).

Use of this function requires the file wx\_doc.h to be included.

\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}

\func{Bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{char *}{filename}}

Copies the given stream to the file {\it filename}. Useful when converting an old application to
use streams (within the document/view framework, for example).

Use of this function requires the file wx\_doc.h to be included.

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

Under Windows (only), the wildcard may be a specification for multiple
types of file with a description for each, such as:

\begin{verbatim}
 "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif"
\end{verbatim}

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}

Remember that the returned pointer is temporary and should be copied
if other wxWindows calls will be made before the value is to be used.

\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{int }{minX}, \param{int }{minY},
 \param{int }{maxX}, \param{int }{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{Clipboard functions}\label{clipsboard}

These clipboard functions are implemented for Windows only.

\membersection{::wxCloseClipboard}

\func{Bool}{wxCloseClipboard}{\void}

Closes the clipboard to allow other applications to use it.

\membersection{::wxEmptyClipboard}

\func{Bool}{wxEmptyClipboard}{\void}

Empties the clipboard.

\membersection{::wxEnumClipboardFormats}

\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}

Enumerates the formats found in a list of available formats that belong
to the clipboard. Each call to this  function specifies a known
available format; the function returns the format that appears next in
the list. 

{\it dataFormat} specifies a known format. If this parameter is zero,
the function returns the first format in the list. 

The return value specifies the next known clipboard data format if the
function is successful. It is zero if the {\it dataFormat} parameter specifies
the last  format in the list of available formats, or if the clipboard
is not open. 

Before it enumerates the formats function, an application must open the clipboard by using the 
wxOpenClipboard function. 

\membersection{::wxGetClipboardData}

\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}

Gets data from the clipboard.

{\it dataFormat} may be one of:

\begin{itemize}\itemsep=0pt
\item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
\item wxCF\_BITMAP: returns a new wxBitmap.
\end{itemize}

The clipboard must have previously been opened for this call to succeed.

\membersection{::wxGetClipboardFormatName}

\func{Bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{char *}{formatName}, \param{int}{maxCount}}

Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.

\membersection{::wxIsClipboardFormatAvailable}

\func{Bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}

Returns TRUE if the given data format is available on the clipboard.

\membersection{::wxOpenClipboard}

\func{Bool}{wxOpenClipboard}{\void}

Opens the clipboard for passing data to it or getting data from it.

\membersection{::wxRegisterClipboardFormat}

\func{int}{wxRegisterClipboardFormat}{\param{char *}{formatName}}

Registers the clipboard data format name and returns an identifier.

\membersection{::wxSetClipboardData}

\func{Bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}

Passes data to the clipboard.

{\it dataFormat} may be one of:

\begin{itemize}\itemsep=0pt
\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
\item wxCF\_BITMAP: {\it data} is a wxBitmap.
\item wxCF\_METAFILE: {\it data} is a wxMetaFile. {\it width} and {\it height} are used to give recommended dimensions.
\end{itemize}

The clipboard must have previously been opened for this call to succeed.

\section{Miscellaneous functions}\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{::wxCreateDynamicObject}\label{wxcreatedynamicobject}

\func{wxObject *}{wxCreateDynamicObject}{\param{char *}{className}}

Creates and returns an object of the given class, if the class has been
registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.

\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 yet implemented for 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 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{char *}{label}, \param{wxWindow *}{parent=NULL}}

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 boxes; if non-NULL, the search will be limited to the given window hierarchy.
The search is recursive in both cases.

\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}

\func{wxWindow *}{wxFindWindowByName}{\param{char *}{name}, \param{wxWindow *}{parent=NULL}}

Find a window by its name (as given in a window constructor or {\bf Create} function call).
If {\it parent} is NULL, the search will start from all top-level
frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
The search is recursive in both cases.

If no such named window is found, {\bf wxFindWindowByLabel} is called.

\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}

\func{wxWindow *}{wxGetActiveWindow}{\void}

Gets the currently active window (Windows only).

\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{::wxIPCCleanUp}\label{wxipccleanup}

\func{void}{wxIPCCleanUp}{\void}

Call this when your application is terminating, if you have
called \helpref{wxIPCInitialize}{wxipcinitialize}.

\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{::wxNow}\label{wxnow}

\func{char *}{wxNow}{\void}

Returns a string representing the current date and time.

\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{::wxTrace}\label{wxtrace}

\func{void}{wxTrace}{\param{char *}{fmt}, \param{...}{}}

In debug mode, takes printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).

If not in debug mode, this compiles to `null code'.

\membersection{::wxTraceLevel}\label{wxtracelevel}

\func{void}{wxTraceLevel}{\param{int}{ level}, \param{char *}{fmt}, \param{...}{}}

In debug mode, takes printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
The first argument should be the level at which this information is appropriate.
It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
this value.

If not in debug mode, this compiles to `null code'.

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

\section{Macros}\label{macros}

These macros are defined in wxWindows.

\membersection{CLASSINFO}\label{classinfo}

\func{wxClassInfo *}{CLASSINFO}{className}

Returns a pointer to the wxClassInfo object associated with this class.

\membersection{DEBUG\_NEW}\label{debugnew}

\func{}{DEBUG\_NEW}{arg}

This is defined in debug mode to be call the redefined new operator
with filename and line number arguments. The definition is:

\begin{verbatim}
#define DEBUG_NEW new(__FILE__,__LINE__)
\end{verbatim}

In non-debug mode, this is defined as the normal new operator.

\membersection{DECLARE\_ABSTRACT\_CLASS}

\func{}{DECLARE\_ABSTRACT\_CLASS}{className}

Used inside a class declaration to declare that the class should be
made known to the class hierarchy, but objects of this class cannot be created
dynamically. The same as DECLARE\_CLASS.

Example:

\begin{verbatim}
class wxCommand: public wxObject
{
  DECLARE_ABSTRACT_CLASS(wxCommand)

 private:
  ...
 public:
  ...
};
\end{verbatim}

\membersection{DECLARE\_CLASS}

\func{}{DECLARE\_CLASS}{className}

Used inside a class declaration to declare that the class should be
made known to the class hierarchy, but objects of this class cannot be created
dynamically. The same as DECLARE\_ABSTRACT\_CLASS.

\membersection{DECLARE\_DYNAMIC\_CLASS}

\func{}{DECLARE\_DYNAMIC\_CLASS}{className}

Used inside a class declaration to declare that the objects of this class should be dynamically
createable from run-time type information.

Example:

\begin{verbatim}
class wxFrame: public wxWindow
{
  DECLARE_DYNAMIC_CLASS(wxFrame)

 private:
  char *frameTitle;
 public:
  ...
};
\end{verbatim}

\membersection{IMPLEMENT\_ABSTRACT\_CLASS}

\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}

Used in a C++ implementation file to complete the declaration of
a class that has run-time type information. The same as IMPLEMENT\_CLASS.

Example:

\begin{verbatim}
IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)

wxCommand::wxCommand(void)
{
...
}
\end{verbatim}

\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}

\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}

Used in a C++ implementation file to complete the declaration of
a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.

\membersection{IMPLEMENT\_CLASS}

\func{}{IMPLEMENT\_CLASS}{className, baseClassName}

Used in a C++ implementation file to complete the declaration of
a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.

\membersection{IMPLEMENT\_CLASS2}

\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}

Used in a C++ implementation file to complete the declaration of a
class that has run-time type information and two base classes. The
same as IMPLEMENT\_ABSTRACT\_CLASS2.

\membersection{IMPLEMENT\_DYNAMIC\_CLASS}

\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}

Used in a C++ implementation file to complete the declaration of
a class that has run-time type information, and whose instances
can be created dynamically.

Example:

\begin{verbatim}
IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)

wxFrame::wxFrame(void)
{
...
}
\end{verbatim}

\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}

\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}

Used in a C++ implementation file to complete the declaration of
a class that has run-time type information, and whose instances
can be created dynamically. Use this for classes derived from two
base classes.

\membersection{TRACE}\label{trace}

\func{}{TRACE}{formatString, ...}

In debug mode, calls wxTrace with printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).

If not in debug mode, this compiles to `null code'.

\membersection{TRACELEVEL}\label{tracelevel}

\func{}{TRACELEVEL}{level, formatString, ...}

In debug mode, calls wxTraceLevel with printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
The first argument should be the level at which this information is appropriate.
It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
this value.

If not in debug mode, this compiles to `null code'.

\section{wxWindows resource functions}\label{resourcefuncs}

This section details functions for manipulating wxWindows (.WXR) resource
files and loading user interface elements from resources.

\normalbox{Please note that this use of the word `resource' is different from that used when talking
about initialisation file resource reading and writing, using such functions
as wxWriteResource and wxGetWriteResource. It's just an unfortunate clash of terminology.}

\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}

See also \helpref{wxPanel::LoadFromResource}{wxpanelloadfromresource} for panel and dialog
loading from resource data.

\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}

\func{Bool}{wxResourceAddIdentifier}{\param{char *}{name}, \param{int }{value}}

Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
\verb$#$defining a name to an integer). Unlikely to be used by an application except
perhaps for implementing resource functionality for interpreted languages.

\membersection{::wxResourceClear}

\func{void}{wxResourceClear}{\void}

Clears the wxWindows resource table.

\membersection{::wxResourceCreateBitmap}

\func{wxBitmap *}{wxResourceCreateBitmap}{\param{char *}{resource}}

Creates a new bitmap from a file, static data, or Windows resource, given a valid
wxWindows bitmap resource identifier. For example, if the .WXR file contains
the following:

\begin{verbatim}
static char *aiai_resource = "bitmap(name = 'aiai_resource',\
  bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
  bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X']).";
\end{verbatim}

then this function can be called as follows:

\begin{verbatim}
  wxBitmap *bitmap  = wxResourceCreateBitmap("aiai_resource");
\end{verbatim}

\membersection{::wxResourceCreateIcon}

\func{wxIcon *}{wxResourceCreateIcon}{\param{char *}{resource}}

Creates a new icon from a file, static data, or Windows resource, given a valid
wxWindows icon resource identifier. For example, if the .WXR file contains
the following:

\begin{verbatim}
static char *aiai_resource = "icon(name = 'aiai_resource',\
  icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
  icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X']).";
\end{verbatim}

then this function can be called as follows:

\begin{verbatim}
  wxIcon *icon = wxResourceCreateIcon("aiai_resource");
\end{verbatim}

\membersection{::wxResourceCreateMenuBar}

\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{char *}{resource}}

Creates a new menu bar given a valid wxWindows menubar resource
identifier. For example, if the .WXR file contains the following:

\begin{verbatim}
static char *menuBar11 = "menu(name = 'menuBar11',\
  menu = \
  [\
    ['&File', 1, '', \
      ['&Open File', 2, 'Open a file'],\
      ['&Save File', 3, 'Save a file'],\
      [],\
      ['E&xit', 4, 'Exit program']\
    ],\
    ['&Help', 5, '', \
      ['&About', 6, 'About this program']\
    ]\
  ]).";
\end{verbatim}

then this function can be called as follows:

\begin{verbatim}
  wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
\end{verbatim}


\membersection{::wxResourceGetIdentifier}

\func{int}{wxResourceGetIdentifier}{\param{char *}{name}}

Used for retrieving the integer value associated with an identifier.
A zero value indicates that the identifier was not found.

See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.

\membersection{::wxResourceParseData}

\func{Bool}{wxResourceParseData}{\param{char *}{resource}}

Parses a string containing one or more wxWindows resource objects. If
the resource objects are global static data that are included into the
C++ program, then this function must be called for each variable
containing the resource data, to make it known to wxWindows.

\membersection{::wxResourceParseFile}

\func{Bool}{wxResourceParseFile}{\param{char *}{filename}}

Parses a file containing one or more wxWindows resource objects
in C++-compatible syntax. Use this function to dynamically load
wxWindows resource data.

\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}

\func{Bool}{wxResourceRegisterBitmapData}{\param{char *}{name}, \param{char *}{xbm\_data}, \param{int }{width},
\param{int }{height}}

\func{Bool}{wxResourceRegisterBitmapData}{\param{char *}{name}, \param{char **}{xpm\_data}}

Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system. 
This is required if other resources will use the bitmap data, since otherwise there
is no connection between names used in resources, and the global bitmap data.

\membersection{::wxResourceRegisterIconData}

Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.

\chapter{Classes by category}\label{classesbycat}

A classification of wxWindows classes by category.

\section{Managed windows}

There are several types of window that are directly controlled by the
window manager (such as MS Windows, or the Motif Window Manager).
Frames may contain \helpref{subwindows}{catsubwindows}, and
dialog boxes have their own built-in subwindow similar to a panel.

\begin{itemize}\itemsep=0pt
\item \helpref{wxFrame}{wxframe}
\item \helpref{wxDialogBox}{wxdialogbox}
\item \helpref{wxEnhDialogBox}{wxenhdialogbox}
\end{itemize}

See also \helpref{wxWindow}{wxwindow}.

\section{Subwindows}\label{catsubwindows}

Subwindows should be created as children of frames. The panel
subwindow may contain panel items (controls or widgets).

\begin{itemize}\itemsep=0pt
\item \helpref{wxCanvas}{wxcanvas}
\item \helpref{wxPanel}{wxpanel}
\item \helpref{wxTextWindow}{wxtextwindow}
\item \helpref{wxToolBar}{wxtoolbar}
\item \helpref{wxButtonBar}{wxbuttonbar}
\end{itemize}

See also \helpref{wxWindow}{wxwindow}.

\section{Panel items}

These are widgets (in Motif terminology) or controls (in MS Windows terminology) that can be
placed on panels and dialog boxes, with the exception of wxMenu and wxMenuBar.

\begin{itemize}\itemsep=0pt
\item \helpref{wxButton}{wxbutton}
\item \helpref{wxCheckBox}{wxcheckbox}
\item \helpref{wxChoice}{wxchoice}
\item \helpref{wxGauge}{wxgauge}
\item \helpref{wxGroupBox}{wxgroupbox}
\item \helpref{wxItem}{wxitem}
\item \helpref{wxListBox}{wxlistbox}
\item \helpref{wxMultiText}{wxmultitext}
\item \helpref{wxMenu}{wxmenu}
\item \helpref{wxMenuBar}{wxmenubar}
\item \helpref{wxMessage}{wxmessage}
\item \helpref{wxRadioBox}{wxradiobox}
\item \helpref{wxSlider}{wxslider}
\item \helpref{wxText}{wxtext}
\end{itemize}

See also \helpref{wxWindow}{wxwindow}.

\section{Window layout}

\overview{Overview}{constraintsoverview}

These are the classes and functions relevant to using automated window layout.

\begin{itemize}\itemsep=0pt
\item \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}
\item \helpref{wxLayoutConstraints}{wxlayoutconstraints}
\item \helpref{wxWindow::Layout}{wxwindowlayout}
\item \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints}
\item \helpref{wxWindow::GetConstraints}{wxwindowgetconstraints}
\end{itemize}

\section{Device contexts}

\overview{Overview}{dcoverview}

Device contexts are surfaces that may be drawn on, and provide an
abstraction that allows parameterisation of your drawing code
by passing different device contexts.

\begin{itemize}\itemsep=0pt
\item \helpref{wxCanvasDC}{wxcanvasdc}
\item \helpref{wxDC}{wxdc}
\item \helpref{wxMemoryDC}{wxmemorydc}
\item \helpref{wxMetaFileDC}{wxmetafiledc}
\item \helpref{wxPanelDC}{wxpaneldc}
\item \helpref{wxPostScriptDC}{wxpostscriptdc}
\item \helpref{wxPrinterDC}{wxprinterdc}
\end{itemize}

\section{Graphics device interface}

\overview{Bitmaps overview}{wxbitmapoverview}

These classes are related to the Graphics Device Interface, in MS Windows terminology.

\begin{itemize}\itemsep=0pt
\item \helpref{wxColour}{wxcolour}
\item \helpref{wxBitmap}{wxbitmap}
\item \helpref{wxBrush}{wxbrush}
\item \helpref{wxBrushList}{wxbrushlist}
\item \helpref{wxCursor}{wxcursor}
\item \helpref{wxFont}{wxfont}
\item \helpref{wxFontList}{wxfontlist}
\item \helpref{wxIcon}{wxicon}
\item \helpref{wxPen}{wxpen}
\item \helpref{wxPenList}{wxpenlist}
\item \helpref{wxColourMap}{wxcolourmap}
\end{itemize}

\section{Events}

\overview{Overview}{eventhandlingoverview}

Some member functions that an application overrides are passed
event objects containing information about the event.

\begin{itemize}\itemsep=0pt
\item \helpref{wxCommandEvent}{wxcommandevent}
\item \helpref{wxEvent}{wxevent}
\item \helpref{wxKeyEvent}{wxkeyevent}
\item \helpref{wxMouseEvent}{wxmouseevent}
\end{itemize}

\section{Data structures}

These are the data structure classes offered by wxWindows.

\begin{itemize}\itemsep=0pt
\item \helpref{wxHashTable}{wxhashtable}
\item \helpref{wxList}{wxlist}
\item \helpref{wxNode}{wxnode}
\item \helpref{wxObject}{wxobject}
\item \helpref{wxString}{wxstring}
\item \helpref{wxStringList}{wxstringlist}
\end{itemize}

\section{Run-time class information system}

\overview{Overview}{runtimeclassoverview}

wxWindows supports run-time manipulation of class information, and dynamic
creation of objects given class names.

\begin{itemize}\itemsep=0pt
\item \helpref{wxClassInfo}{wxclassinfo}
\item \helpref{wxObject}{wxobject}
\item \helpref{Macros}{macros}
\end{itemize}

\section{Debugging features}

\overview{Overview}{debuggingoverview}

wxWindows supports some aspects of debugging an application through
classes, functions and macros.

\begin{itemize}\itemsep=0pt
\item \helpref{wxDebugContext}{wxdebugcontext}
\item \helpref{wxDebugStreamBuf}{wxdebugstreambuf}
\item \helpref{wxObject}{wxobject}
\item \helpref{wxTrace}{wxtrace}
\item \helpref{wxTraceLevel}{wxtracelevel}
\item \helpref{DEBUG\_NEW}{debugnew}
\item \helpref{TRACE}{trace}
\item \helpref{TRACELEVEL}{tracelevel}
\end{itemize}

\section{Interprocess communication}

\overview{Overview}{ipcoverview}

wxWindows provides a simple interprocess communications facilities
based on DDE.

\begin{itemize}\itemsep=0pt
\item \helpref{wxClient}{wxclient}
\item \helpref{wxConnection}{wxconnection}
\item \helpref{wxHelpInstance}{wxhelpinstance}
\item \helpref{wxServer}{wxserver}
\end{itemize}

\section{Document/view framework}

\overview{Overview}{docviewoverview}

wxWindows supports a document/view framework which provides
housekeeping for a document-centric application.

\begin{itemize}\itemsep=0pt
\item \helpref{wxDocument}{wxdocument}
\item \helpref{wxView}{wxview}
\item \helpref{wxDocTemplate}{wxdoctemplate}
\item \helpref{wxDocManager}{wxdocmanager}
\item \helpref{wxDocChildFrame}{wxdocchildframe}
\item \helpref{wxDocParentFrame}{wxdocparentframe}
\item \helpref{wxTransferFileToStream}{wxtransferfiletostream}
\item \helpref{wxTransferStreamToFile}{wxtransferstreamtofile}
\end{itemize}

\section{Printing framework}

\overview{Overview}{printingoverview}

A printing and previewing framework is implemented to
make it relatively straighforward to provide document printing
facilities.

\begin{itemize}\itemsep=0pt
\item \helpref{wxPreviewFrame}{wxpreviewframe}
\item \helpref{wxPreviewCanvas}{wxpreviewcanvas}
\item \helpref{wxPreviewControlBar}{wxpreviewcontrolbar}
\item \helpref{wxPrintData}{wxprintdata}
\item \helpref{wxPrintDialog}{wxprintdialog}
\item \helpref{wxPrinter}{wxprinter}
\item \helpref{wxPrinterDC}{wxprinterdc}
\item \helpref{wxPrintout}{wxprintout}
\item \helpref{wxPrintPreview}{wxprintpreview}
\end{itemize}

\section{Database classes}

\overview{Database classes overview}{odbcoverview}

wxWindows provides a set of classes for accessing Microsoft's ODBC (Open Database Connectivity)
product.

\begin{itemize}\itemsep=0pt
\item \helpref{wxDatabase}{wxdatabase}
\item \helpref{wxQueryCol}{wxquerycol}
\item \helpref{wxQueryField}{wxqueryfield}
\item \helpref{wxRecordSet}{wxrecordset}
\end{itemize}


\section{Miscellaneous}

\begin{itemize}\itemsep=0pt
\item \helpref{wxApp}{wxapp}
\item \helpref{wxForm}{wxform}
\item \helpref{wxIntPoint}{wxintpoint}
\item \helpref{wxPathList}{wxpathlist}
\item \helpref{wxPoint}{wxpoint}
\item \helpref{wxTimer}{wxtimer}
\item \helpref{wxTypeTree}{wxtypetree}
\end{itemize}


\chapter{Topic overviews}\label{overviews}

This chapter contains a selection of topic overviews.

\section{Run time class information overview}\label{runtimeclassoverview}

Classes: \helpref{wxObject}{wxobject}, \helpref{wxClassInfo}{wxclassinfo}.

One of the failings of C++ is that no run-time information is provided
about a class and its position in the inheritance hierarchy.
Another is that instances of a class cannot be created just by knowing the name of a class,
which makes facilities such as persistent storage hard to implement.

Most C++ GUI frameworks overcome these limitations by means of a set of
macros and functions and wxWindows (from version 1.62) is no exception.
Each class that you wish to be known the type system should have
a macro such as DECLARE\_DYNAMIC\_CLASS just inside the class declaration.
The macro IMPLEMENT\_DYNAMIC\_CLASS should be in the implementation file.

Variations on these \helpref{macros}{macros} are used for multiple inheritance, and abstract
classes that cannot be instantiated dynamically or otherwise.

DECLARE\_DYNAMIC\_CLASS inserts a static wxClassInfo declaration into the
class, initialized by IMPLEMENT\_DYNAMIC\_CLASS. When initialized, the
wxClassInfo object inserts itself into a linked list (accessed through
wxClassInfo::first and wxClassInfo::next pointers). The linked list
is fully created by the time all global initialisation is done.

IMPLEMENT\_DYNAMIC\_CLASS is a macro that not only initialises the static
wxClassInfo member, but defines a global function capable of creating a
dynamic object of the class in question. A pointer to this function is
stored in wxClassInfo, and is used when an object should be created
dynamically.

wxObject::IsKindOf uses the linked list of wxClassInfo. It takes
a wxClassInfo argument, so use CLASSINFO(className) to return an
appropriate wxClassInfo pointer to use in this function.

The function \helpref{wxCreateDynamicObject}{wxcreatedynamicobject} can be used
to construct a new object of a given type, by supplying a string name.
If you have a pointer to the wxClassInfo object instead, then you
can simply call wxClassInfo::CreateObject.

\subsection{wxClassInfo}\label{wxclassinfooverview}

\overview{Run time class information overview}{runtimeclassoverview}

Class: \helpref{wxClassInfo}{wxclassinfo}

This class stores meta-information about classes. An application
may use macros such as DECLARE\_DYNAMIC\_CLASS and IMPLEMENT\_DYNAMIC\_CLASS
to record run-time information about a class, including:

\begin{itemize}\itemsep=0pt
\item its position in the inheritance hierarchy;
\item the base class name(s) (up to two base classes are permitted);
\item a string representation of the class name;
\item a function that can be called to construct an instance of this class.
\end{itemize}

The DECLARE\_... macros declare a static wxClassInfo variable in a class, which is initialized
by macros of the form IMPLEMENT\_... in the implementation C++ file. Classes whose instances may be
constructed dynamically are given a global constructor function which returns a new object.

You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g. CLASSINFO(wxFrame).
You can get the wxClassInfo for an object using wxObject::GetClassInfo.

See also \helpref{wxObject}{wxobject} and \helpref{wxCreateDynamicObject}{wxcreatedynamicobject}.

\subsection{Example}

In a header file wx\_frame.h:

\begin{verbatim}
class wxFrame: public wxWindow
{
  DECLARE_DYNAMIC_CLASS(wxFrame)

 private:
  char *frameTitle;
 public:
  ...
};
\end{verbatim}

In a C++ file wx\_frame.cc:

\begin{verbatim}
IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)

wxFrame::wxFrame(void)
{
...
}
\end{verbatim}


\section{Document/view overview}\label{docviewoverview}

Classes: \helpref{wxDocument}{wxdocument}, \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate},\rtfsp
\helpref{wxDocManager}{wxdocmanager}, \helpref{wxDocParentFrame}{wxdocparentframe}, \helpref{wxDocChildFrame}{wxdocchildframe},
\rtfsp\helpref{wxCommand}{wxcommand}, \helpref{wxCommandProcessor}{wxcommandprocessor}

The document/view framework is found in most application frameworks, because it
can dramatically simplify the code required to build many kinds of application.

The idea is that you can model your application primarily in terms of {\it documents} to store data
and provide interface-independent operations upon it, and {\it views} to visualise and manipulate
the data. Documents know how to do input and output given stream objects, and views are responsible
for taking input from physical windows and performing the manipulation on the document data.
If a document's data changes, all views should be updated to reflect the change.

The framework can provide many user-interface elements based on this model. Once you have defined
your own classes and the relationships between them, the framework takes care
of popping up file selectors, opening and closing files, asking the user to save
modifications, routing menu commands to appropriate (possibly default) code, even
some default print/preview functionality and support for command undo/redo.
The framework is highly modular, allowing overriding and replacement of functionality
and objects to achieve more than the default behaviour.

These are the overall steps involved in creating an application based on the document/view framework:

\begin{enumerate}\itemsep=0pt
\item Define your own document and view classes, overriding a minimal set of
member functions e.g. for input/output, drawing and initialization.
\item Define any subwindows
(such as a canvas) that are needed for the view(s). You may need to route some events
to views or documents, for example OnPaint needs to be routed to wxView::OnDraw.
\item Decide what style of interface you will use: Microsoft's MDI (multiple
document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
for each document), or single-window (one document open at a time, as in Windows Write).
\item Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
you initialize a view. Create menus using standard menu ids (such as wxID\_OPEN, wxID\_PRINT),
routing non-application-specific identifiers to the base frame's OnMenuCommand.
\item Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
as many wxDocTemplate instances as necessary to define relationships between documents and
views. For a simple application, there will be just one wxDocTemplate.
\end{enumerate}

If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand
and use wxCommandProcessor::Submit instead of directly executing code. The framework will
take care of calling Undo and Do functions as appropriate, so long as the wxID\_UNDO and
wxID\_REDO menu items are defined in the view menu.

Here are a few examples of the tailoring you can do to go beyond the default framework
behaviour:

\begin{itemize}\itemsep=0pt
\item Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
or a command history editor.
\item Override wxView::OnCreatePrintout to create an instance of a derived \helpref{wxPrintout}{wxprintout}\rtfsp
class, to provide multi-page document facilities.
\item Override wxDocManager::SelectDocumentPath to provide a different file selector.
\item Limit the maximum number of open documents and the maximum number of undo commands.
\end{itemize}

Note that to activate framework functionality, you need to use some or all of
the wxWindows \helpref{predefined command identifiers}{predefinedids} in your menus.

\subsection{wxDocument overview}\label{wxdocumentoverview}

\overview{Document/view framework overview}{docviewoverview}

Class: \helpref{wxDocument}{wxdocument}

The wxDocument class can be used to model an application's file-based
data. It is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocTemplate}{wxdoctemplate}\rtfsp
and \helpref{wxDocManager}{wxdocmanager} classes.

Using this framework can save a lot of routine user-interface programming,
since a range of menu commands -- such as open, save, save as -- are supported automatically.
The programmer just needs to define a minimal set of classes and member functions
for the framework to call when necessary. Data, and the means to view and edit
the data, are explicitly separated out in this model, and the concept of multiple {\it views} onto
the same data is supported.

Note that the document/view model will suit many but not all styles of application.
For example, it would be overkill for a simple file conversion utility, where there
may be no call for {\it views} on {\it documents} or the ability to open, edit and save
files. But probably the majority of applications are document-based.

See the example application in {\tt samples/docview}.

To use the abstract wxDocument class, you need to derive a new class and override
at least the member functions SaveObject and LoadObject. SaveObject and
LoadObject will be called by the framework when the document needs to be saved
or loaded.

Use the macros DECLARE\_DYNAMIC\_CLASS and IMPLEMENT\_DYNAMIC\_CLASS in order
to allow the framework to create document objects on demand. When you create
a \helpref{wxDocTemplate}{wxdoctemplate} object on application initialization, you
should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.

If you do not wish to use the wxWindows method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
to return an instance of the appropriate class.

\subsection{wxView overview}\label{wxviewoverview}

\overview{Document/view framework overview}{docviewoverview}

Class: \helpref{wxView}{wxview}

The wxView class can be used to model the viewing and editing component of
an application's file-based data. It is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxDocument}{wxdocument}, \helpref{wxDocTemplate}{wxdoctemplate}
and \helpref{wxDocManager}{wxdocmanager} classes.

See the example application in {\tt samples/docview}.

To use the abstract wxView class, you need to derive a new class and override
at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You'll probably
want to override OnMenuCommand to respond to menu commands from the frame containing the
view.

Use the macros DECLARE\_DYNAMIC\_CLASS and IMPLEMENT\_DYNAMIC\_CLASS in order
to allow the framework to create view objects on demand. When you create
a \helpref{wxDocTemplate}{wxdoctemplate} object on application initialization, you
should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.

If you do not wish to use the wxWindows method of creating view
objects dynamically, you must override wxDocTemplate::CreateView
to return an instance of the appropriate class.

\subsection{wxDocTemplate overview}\label{wxdoctemplateoverview}

\overview{Document/view framework overview}{docviewoverview}

Class: \helpref{wxDocTemplate}{wxdoctemplate}

The wxDocTemplate class is used to model the relationship between a
document class and a view class. The application creates a document
template object for each document/view pair. The list of document
templates managed by the wxDocManager instance is used to create
documents and views. Each document template knows what file filters
and default extension are appropriate for a document/view combination,
and how to create a document or view.

For example, you might write a small doodling application that can load
and save lists of line segments. If you had two views of the data -- graphical,
and a list of the segments -- then you would create one document class DoodleDocument,
and two view classes (DoodleGraphicView and DoodleListView). You would also
need two document templates, one for the graphical view and another for the
list view. You would pass the same document class and default file extension to both
document templates, but each would be passed a different view class. When
the user clicks on the Open menu item, the file selector is displayed
with a list of possible file filters -- one for each wxDocTemplate. Selecting
the filter selects the wxDocTemplate, and when
a file is selected, that template will be used for creating a document
and view. Under non-Windows platforms, the user will be prompted for
a list of templates before the file selector is shown, since most file selectors
do not allow a choice of file filters.

For the case where an application has one document type and one view type,
a single document template is constructed, and dialogs will be appropriately
simplified.

wxDocTemplate is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}
and \helpref{wxDocManager}{wxdocmanager} classes.

See the example application in {\tt samples/docview}.

To use the wxDocTemplate class, you do not need to derive a new class.
Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass) and
CLASSINFO(YourViewClass) to allow dynamic instance creation.
If you do not wish to use the wxWindows method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
and wxDocTemplate::CreateView to return instances of the appropriate class.

{\it NOTE}: the document template has nothing to do with the C++ template construct. C++
templates are not used anywhere in wxWindows.

\subsection{wxDocManager overview}\label{wxdocmanageroverview}

\overview{Document/view framework overview}{docviewoverview}

Class: \helpref{wxDocManager}{wxdocmanager}

The wxDocManager class is part of the document/view framework supported by wxWindows,
and cooperates with the \helpref{wxView}{wxview}, \helpref{wxDocument}{wxdocument}\rtfsp
and \helpref{wxDocTemplate}{wxdoctemplate} classes.

A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document and
and template instances, and much functionality is routed through this object, such
as providing selection and file dialogs. The application can use this class `as is' or
derive a class and override some members to extend or change the functionality.
Create an instance of this class near the beginning of your application initialization,
before any documents, views or templates are manipulated.

There may be multiple wxDocManager instances in an application.

See the example application in {\tt samples/docview}.

\subsection{wxCommand overview}\label{wxcommandoverview}

\overview{Document/view framework overview}{docviewoverview}

Classes: \helpref{wxCommand}{wxcommand}, \helpref{wxCommandProcessor}{wxcommandprocessor}

wxCommand is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing
a toolbar button or any other means provided by the application to
change the data or view.

Instead of the application functionality being scattered around
switch statements and functions in a way that may be hard to
read and maintain, the functionality for a command is explicitly represented
as an object which can be manipulated by a framework or application.
When a user interface event occurs, the application {\it submits} a command
to a \helpref{wxCommandProcessor}{wxcommandprocessoroverview} object to execute and
store.

The wxWindows document/view framework handles Undo and Redo by use of
wxCommand and wxCommandProcessor objects. You might find further uses
for wxCommand, such as implementing a macro facility that stores, loads
and replays commands.

An application can derive a new class for every command, or, more likely, use
one class parameterized with an integer or string command identifier.

\subsection{wxCommandProcessor overview}\label{wxcommandprocessoroverview}

\overview{Document/view framework overview}{docviewoverview}

Classes: \helpref{wxCommandProcessor}{wxcommandprocessor}, \helpref{wxCommand}{wxcommand}

wxCommandProcessor is a class that maintains a history of wxCommand
instances, with undo/redo functionality built-in. Derive a new class from this
if you want different behaviour.

\subsection{wxFileHistory overview}\label{wxfilehistoryoverview}

\overview{Document/view framework overview}{docviewoverview}

Classes: \helpref{wxFileHistory}{wxfilehistory}, \helpref{wxDocManager}{wxdocmanager}

wxFileHistory encapsulates functionality to record the last few files visited, and
to allow the user to quickly load these files using the list appended to the File menu.

Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish
to derive from it to allow different behaviour, such as popping up a scrolling
list of files.

By calling wxFileHistory::FileHistoryUseMenu you can associate a file menu with
the file history, that will be used for appending the filenames. They are
appended using menu identifiers in the range wxID\_FILE1 to wxID\_FILE9.

In order to respond to a file load command from one of these identifiers,
you need to handle them in your wxFrame::OnMenuCommand. Below is the
code used by the default document/view parent frame.

\begin{verbatim}
void wxDocParentFrame::OnMenuCommand(int id)
{
  switch (id)
  {
    case wxID_EXIT:
    {
      if (GetEventHandler()->OnClose())
        delete this;
      break;
    }
    case wxID_FILE1:
    case wxID_FILE2:
    case wxID_FILE3:
    case wxID_FILE4:
    case wxID_FILE5:
    case wxID_FILE6:
    case wxID_FILE7:
    case wxID_FILE8:
    case wxID_FILE9:
    {
      char *f = docManager->GetHistoryFile(id-wxID_FILE1);
      if (f)
        (void)docManager->CreateDocument(f, wxDOC_SILENT);
      break;
    }
    default:
    {
      docManager->OnMenuCommand(id);
    }
  }
}
\end{verbatim}

\subsection{wxWindows predefined command identifiers}\label{predefinedids}

To allow communication between the application's menus and the
document/view framework, several command identifiers are predefined for you
to use in menus. The framework recognizes them and processes them if you
forward commands from wxFrame::OnMenuCommand (or perhaps from toolbars and
other user interface constructs).

\begin{itemize}\itemsep=0pt
\item wxID\_OPEN (5000)
\item wxID\_CLOSE (5001)
\item wxID\_NEW (5002)
\item wxID\_SAVE (5003)
\item wxID\_SAVEAS (5004)
\item wxID\_REVERT (5005)
\item wxID\_EXIT (5006)
\item wxID\_UNDO (5007)
\item wxID\_REDO (5008)
\item wxID\_HELP (5009)
\item wxID\_PRINT (5010)
\item wxID\_PRINT\_SETUP (5011)
\item wxID\_PREVIEW (5012)
\end{itemize}

\section{Printing overview}\label{printingoverview}

Classes: \helpref{wxPrintout}{wxprintout}, \helpref{wxPrinter}{wxprinter},\rtfsp
\helpref{wxPrintPreview}{wxprintpreview}, \helpref{wxPrinterDC}{wxprinterdc},\rtfsp
\helpref{wxPrintDialog}{wxprintdialog}.

The printing framework relies on the application to provide classes
whose member functions can respond to particular requests, such
as `print this page' or `does this page exist in the document?'.
This method allows wxWindows to take over the housekeeping duties of
turning preview pages, calling the print dialog box, creating
the printer device context, and so on: the application can concentrate
on the rendering of the information onto a device context.
The printing framework is mainly a Windows feature; PostScript
support under non-Windows platforms is emerging but has not been rigorously tested.

The \helpref{document/view framework}{docviewoverview} creates a default wxPrintout
object for every view, calling wxView::OnDraw to achieve a
prepackaged print/preview facility.

A document's printing ability is represented in an application by a
derived wxPrintout class. This class prints a page on request, and can
be passed to the Print function of a wxPrinter object to actually print
the document, or can be passed to a wxPrintPreview object to initiate
previewing. The following code (from the printing sample) shows how easy
it is to initiate printing, previewing and the print setup dialog, once the wxPrintout
functionality has been defined. Notice the use of MyPrintout for
both printing and previewing. All the preview user interface functionality
is taken care of by wxWindows. For details on how MyPrintout is defined,
please look at the printout sample code.

\begin{verbatim}
    case WXPRINT_PRINT:
    {
      wxPrinter printer;
      MyPrintout printout("My printout");
      printer.Print(this, &printout, TRUE);
      break;
    }
    case WXPRINT_PREVIEW:
    {
      // Pass two printout objects: for preview, and possible printing.
      wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
      wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", 100, 100, 600, 650);
      frame->Centre(wxBOTH);
      frame->Initialize();
      frame->Show(TRUE);
      break;
    }
    case WXPRINT_PRINT_SETUP:
    {
      wxPrintDialog printerDialog(this);
      printerDialog.GetPrintData().SetSetupDialog(TRUE);
      printerDialog.Show(TRUE);
      break;
    }
\end{verbatim}

\section{Interprocess communication overview}\label{ipcoverview}

Classes: \helpref{wxServer}{wxserver}, \helpref{wxConnection}{wxconnection},
\rtfsp\helpref{wxClient}{wxclient}.

The following describes how wxWindows implements DDE.  The following
three classes are central.

\begin{enumerate}\itemsep=0pt
\item wxClient. This represents the client application, and is used
only within a client program.
\item wxServer. This represents the server application, and is used
only within a server program.
\item wxConnection. This represents the connection from the current
client or server to the other application (server or client), and can be used
in both server and client programs. Most DDE
transactions operate on this object.
\end{enumerate}

Messages between applications are usually identified by three variables:
connection object, topic name and item name.  A data string is a fourth
element of some messages. To create a connection (a conversation in
Windows parlance), the client application sends the message
MakeConnection to the client object, with a string service name to
identify the server and a topic name to identify the topic for the
duration of the connection. Under UNIX, the service name must contain an
integer port identifier.

The server then responds and either vetos the connection or allows it.
If allowed, a connection object is created which persists until the
connection is closed.  The connection object is then used for subsequent
messages between client and server.

To create a working server, the programmer must:

\begin{enumerate}\itemsep=0pt
\item Derive a class from wxServer.
\item Override the handler OnAcceptConnection for accepting or rejecting a connection,
on the basis of the topic argument. This member must create and return a connection
object if the connection is accepted.
\item Create an instance of your server object, and call Create to
activate it, giving it a service name.
\item Derive a class from wxConnection.
\item Provide handlers for various messages that are sent to the server
side of a wxConnection.
\end{enumerate}

To create a working client, the programmer must:

\begin{enumerate}\itemsep=0pt
\item Derive a class from wxClient.
\item Override the handler OnMakeConnection to create and return
an appropriate connection object.
\item Create an instance of your client object.
\item Derive a class from wxConnection.
\item Provide handlers for various messages that are sent to the client
side of a wxConnection.
\item When appropriate, create a new connection by sending a MakeConnection
message to the client object, with arguments host name (processed in UNIX only),
service name, and topic name for this connection. The client object will call OnMakeConnection
to create a connection object of the desired type.
\item Use the wxConnection member functions to send messages to the server.
\end{enumerate}

\subsection{Data transfer}

These are the ways that data can be transferred from one application to
another.

\begin{itemize}\itemsep=0pt
\item {\bf Execute:} the client calls the server with a data string representing
a command to be executed. This succeeds or fails, depending on the
server's willingness to answer. If the client wants to find the result
of the Execute command other than success or failure, it has to explicitly
call Request.
\item {\bf Request:} the client asks the server for a particular data string
associated with a given item string. If the server is unwilling to
reply, the return value is NULL. Otherwise, the return value is a string
(actually a pointer to the connection buffer, so it should not be
deallocated by the application).
\item {\bf Poke:} The client sends a data string associated with an item
string directly to the server. This succeeds or fails.
\item {\bf Advise:} The client asks to be advised of any change in data
associated with a particular item. If the server agrees, the server will
send an OnAdvise message to the client along with the item and data.
\end{itemize}

The default data type is wxCF\_TEXT (ASCII text), and the default data
size is the length of the null-terminated string. Windows-specific data
types could also be used on the PC.

\subsection{Examples}

See the sample programs {\it server}\/ and {\it client}\/ in the IPC
samples directory.  Run the server, then the client. This demonstrates
using the Execute, Request, and Poke commands from the client, together
with an Advise loop: selecting an item in the server list box causes
that item to be highlighted in the client list box.

See also the source for wxHelp, which is a DDE server, and the files
wx\_help.h and wx\_help.cc which implement the client interface to
wxHelp.

\subsection{Remote Procedure Call}

DDE is quite a low level protocol, and all encoding and decoding of
messages must be done by the client and server applications. The
wxWindows extension {\it PrologIO}\/ implements a remote procedure call
protocol (RPC) so that a server can implement a library of functions for
a client to call.  PrologIO makes it easy for applications to pack and
unpack the arguments and return value(s) of procedure calls, and
provides a mechanism for the server to register its available calls and
automatically handle the routing of calls to appropriate server
callbacks, one to a procedure definition. All this makes calling or
implementing server facilities childishly simple. Since PrologIO sits on
top of the DDE wrapper, it is also platform independent. See the
separate PrologIO manual and \helpref{PrologIO}{prologio}.

\subsection{More DDE details}

A wxClient object represents the client part of a client-server DDE
(Dynamic Data Exchange) conversation (available in 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}\rtfsp
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}\rtfsp
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}

\section{Device context overview}\label{dcoverview}

Classes: \helpref{wxDC}{wxdc}, \helpref{wxPostScriptDC}{wxpostscriptdc},\rtfsp
\rtfsp\helpref{wxMetaFileDC}{wxmetafiledc}, \helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxPrinterDC}{wxprinterdc},\rtfsp
\helpref{wxScreenDC}{wxscreendc}.

A wxDC is a {\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.

wxDC is abstract and cannot be used to create
device context objects. Instead, use a derived class. \helpref{wxCanvasDC}{wxcanvasdc}\rtfsp
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.

\section{wxApp overview}\label{wxappoverview}

Classes: \helpref{wxApp}{wxapp}

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 wxApp.\rtfsp
\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 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}

\section{Bitmaps overview}\label{wxbitmapoverview}

Classes: \helpref{wxBitmap}{wxbitmap}, \helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}.

The wxBitmap class encapsulates the concept of a platform-dependent bitmap,
either monochrome or colour. Platform-specific methods for creating a
wxBitmap object 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.

There is now (from version 1.61) extra provision for a number of bitmap
formats via the standard wxBitmap class. These extra facilities can
be enabled using settings in wx\_setup.h; by default they are switched off.

XPM colour pixmaps may be loaded and saved under Windows and X, with
some restrictions imposed by the lack of colourmap facility when
using XPM files. The user may elect to use XPM files as a cross-platform
stabdard, or translate between XPM and BMP files using a suitable
utility (one is under preparation for wxWindows users).

Also, under Windows, DIBs (device independent bitmaps with extension BMP)
may be dynamically loaded and saved. Under X, GIF and BMP files may be
loaded but not saved.

\section{Dialog box overview}\label{wxdialogboxoverview}

Classes: \helpref{wxDialogBox}{wxdialogBox}, \helpref{wxEnhDialogBox}{wxenhdialogbox}

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. This can
be corrected using a patch (see install/install.txt and install/xview.txt).

Under implementations that permit it, wxDialogBox inherits from wxCanvas
via wxPanel, and has a wxPanelDC that the application can draw on.

The panel device context associated with wxDialogBox behaves slightly
differently than for a panel or canvas: drawing to it {\it requires} enclosing
code in BeginDrawing, EndDrawing calls. This is because under Windows, dialog
box device contexts are not 'retained' and settings would be lost if the
device context were retrieved and released for each drawing operations.

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.

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.



\section{Constraints overview}\label{constraintsoverview}

Classes: \helpref{wxLayoutConstraints}{wxlayoutconstraints}, \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}.

Objects of class wxLayoutConstraint can be associated with a window to define the
way its subwindows are laid out, with respect to their siblings or parent.

The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
some or all of which should be accessed directly to set the appropriate
constraints.

\begin{itemize}\itemsep=0pt
\item {\bf left:} represents the left hand edge of the window
\item {\bf right:} represents the right hand edge of the window
\item {\bf top:} represents the top edge of the window
\item {\bf bottom:} represents the bottom edge of the window
\item {\bf width:} represents the width of the window
\item {\bf height:} represents the height of the window
\item {\bf centreX:} represents the horizontal centre point of the window
\item {\bf centreY:} represents the vertical centre point of the window
\end{itemize}

Most constraints are initially set to have the relationship wxUnconstrained,
which means that their values should be calculated by looking at known constraints.
The exceptions are {\it width} and {\it height}, which are set to wxAsIs to
ensure that if the user does not specify a constraint, the existing
width and height will be used, to be compatible with panel items which often
have take a default size. If the constraint is wxAsIs, the dimension will
not be changed.

To call the \helpref{wxWindow::Layout}{wxwindowlayout} function which evaluates
constraints, you can either call wxWindow::SetAutoLayout to tell
default OnSize handlers to call Layout, or override OnSize and call Layout yourself.

\subsection{Constraint layout: more detail}

By default, windows do not have a wxLayoutConstraints object. In this case, much layout
must be done explicitly, by performing calculations in OnSize members, except
for the case of frames that have one subwindow, where wxFrame::OnSize takes care
of resizing the child.

To avoid the need for these rather awkward calculations, the user can create
a wxLayoutConstraints object and associate it with a window with wxWindow::SetConstraints.
This object contains a constraint for each of the window edges, two for the centre point,
and two for the window size. By setting some or all of these constraints appropriately,
the user can achieve quite complex layout by defining relationships between windows.

In wxWindows, each window can be constrained relative to either its {\it
siblings} on the same window, or the {\it parent}. The layout algorithm
therefore operates in a top-down manner, finding the correct layout for
the children of a window, then the layout for the grandchildren, and so
on. Note that this differs markedly from native Motif layout, where
constraints can ripple upwards and can eventually change the frame
window or dialog box size. We assume in wxWindows that the {\it user} is
always `boss' and specifies the size of the outer window, to which
subwindows must conform. Obviously, this might be a limitation in some
circumstances, but it suffices for most situations, and the
simplification avoids some of the nightmarish problems associated with
programming Motif.

When the user sets constraints, many of the constraints for windows
edges and dimensions remain unconstrained. For a given window,
the wxWindow::Layout algorithm first resets all constraints
in all children to have unknown edge or dimension values, and then iterates through the constraints,
evaulating them. For unconstrained edges and dimensions, it
tries to find the value using known relationships that always hold. For example,
an unconstrained {\it width} may be calculated from the {\it left} and {\it right edges}, if
both are currently known. For edges and dimensions with user-supplied constraints, these
constraints are evaulated if the inputs of the constraint are known.

The algorithm stops when all child edges and dimension are known (success), or there
there are unknown edges or dimensions but there has been no change in this cycle (failure).

It then sets all the window positions and sizes according to the values it has found.

Because the algorithm is iterative, the order in which constraints are considered is
irrelevant.

\subsection{Window layout examples}\label{layoutexamples}

\subsubsection{Example 1: subwindow layout}

This example specifies a panel and a canvas side by side,
with a text subwindow below it. 

\begin{verbatim}
  frame->panel = new wxPanel(frame, 0, 0, 1000, 500, 0);
  frame->canvas = new MyCanvas(frame, 0, 0, 400, 400, wxRETAINED);
  frame->text_window = new MyTextWindow(frame, 0, 250, 400, 250, wxNATIVE_IMPL);

  // Set constraints for panel subwindow
  wxLayoutConstraints *c1 = new wxLayoutConstraints;

  c1->left.SameAs       (frame, wxLeft);
  c1->top.SameAs        (frame, wxTop);
  c1->right.PercentOf   (frame, wxWidth, 50);
  c1->height.PercentOf  (frame, wxHeight, 50);

  frame->panel->SetConstraints(c1);

  // Set constraints for canvas subwindow
  wxLayoutConstraints *c2 = new wxLayoutConstraints;

  c2->left.SameAs       (frame->panel, wxRight);
  c2->top.SameAs        (frame, wxTop);
  c2->right.SameAs      (frame, wxRight);
  c2->height.PercentOf  (frame, wxHeight, 50);

  frame->canvas->SetConstraints(c2);

  // Set constraints for text subwindow
  wxLayoutConstraints *c3 = new wxLayoutConstraints;
  c3->left.SameAs       (frame, wxLeft);
  c3->top.Below         (frame->panel);
  c3->right.SameAs      (frame, wxRight);
  c3->bottom.SameAs     (frame, wxBottom);

  frame->text_window->SetConstraints(c3);
\end{verbatim}

\subsubsection{Example 2: panel item layout}

This example sizes a button width to 80 percent of the panel width, and centres
it horizontally. A listbox and multitext item are placed below it. The listbox
takes up 40 percent of the panel width, and the multitext item takes up
the remainder of the width. Margins of 5 pixels are used.

\begin{verbatim}
  // Create some panel items
  wxButton *btn1 = new wxButton(frame->panel, (wxFunction)NULL, "A button") ;

  wxLayoutConstraints *b1 = new wxLayoutConstraints;
  b1->centreX.SameAs    (frame->panel, wxCentreX);
  b1->top.SameAs        (frame->panel, wxTop, 5);
  b1->width.PercentOf   (frame->panel, wxWidth, 80);
  b1->height.PercentOf  (frame->panel, wxHeight, 10);
  btn1->SetConstraints(b1);

  wxListBox *list = new wxListBox(frame->panel, (wxFunction)NULL, "A list",
                                  wxSINGLE, -1, -1, 200, 100);

  wxLayoutConstraints *b2 = new wxLayoutConstraints;
  b2->top.Below         (btn1, 5);
  b2->left.SameAs       (frame->panel, wxLeft, 5);
  b2->width.PercentOf   (frame->panel, wxWidth, 40);
  b2->bottom.SameAs     (frame->panel, wxBottom, 5);
  list->SetConstraints(b2);

  wxMultiText *mtext = new wxMultiText(frame->panel, (wxFunction)NULL, "Multiline text", "Some text",
                        -1, -1, 150, 100);
  
  wxLayoutConstraints *b3 = new wxLayoutConstraints;
  b3->top.Below         (btn1, 5);
  b3->left.RightOf      (list, 5);
  b3->right.SameAs      (frame->panel, wxRight, 5);
  b3->bottom.SameAs     (frame->panel, wxBottom, 5);
  mtext->SetConstraints(b3);
\end{verbatim}

\section{Event handling overview}\label{eventhandlingoverview}

Classes: \helpref{wxEvtHandler}{wxevthandler}, \helpref{wxWindow}{wxwindow}

To handle events that are generated by the windowing system (usually in response
to a user's action), the programmer must derive a class from the window that
is sent the event, and define appropriate behaviour. For example, to respond to
OnPaint messages from a wxCanvas, you would derive a new class MyCanvas
and define the function MyCanvas::OnPaint. Within this function, you
paint the canvas as necessary for your application.

To respond to a user closing a window, define OnClose; to intercept character
input from a canvas, define OnChar, and so on. These events are listed in the
class description for \helpref{wxEvtHandler}{wxevthandler}, which is the
base class for all window classes.

In fact, you don't have to derive a new class from a window class
if you don't want to. You can derive a new class from wxEvtHandler instead,
overriding the appropriate member function, and then call
\rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} to make this
event handler the object that responds to events. This way, you can avoid
a lot of class derivation, and use the same event handler object to
handle events from instances of different classes. If you ever have to call a window's event handler
manually, use the GetEventHandler function to retrieve the window's event handler and use that
to call the member function. By default, GetEventHandler returns a pointer to the window itself
unless an application has redirected event handling using SetEventHandler.

You could use this technique to respond to panel item commands. Normally,
you supply a function of type wxFunction to the panel item constructor, and
it will be called with references to the panel item and command event.
Instead, you could use a single wxEvtHandler object for handling one or
more panel items, setting the event handler object for the panel item just
after item construction. This handler could even be the panel or dialog box.

Another use of SetEventHandler is to temporarily or permanently change the
behaviour of the GUI. For example, you might want to invoke a dialog editor
in your application that changes aspects of dialog boxes. You can
grab all the input for an existing dialog box, and edit it `in situ',
before restoring its behaviour to normal. So even if the application
has derived new classes to customize behaviour, your utility can indulge
in a spot of body-snatching. It could be a useful technique for on-line
tutorials, too, where you take a user through a serious of steps and
don't want them to diverge from the lesson. Here, you can examine the events
coming from buttons and windows, and if acceptable, pass them through to
the original event handler. Use Set/GetNextHandler and Set/GetPreviousHandler
to form a chain of event handlers, taking care to pass events along the chain.

\section{Toolbar overview}\label{wxtoolbaroverview}

Class: \helpref{wxToolBar}{wxtoolbar}

The wxToolBar class gives wxWindows programs an extra, and increasingly
popular, user interface component: a set of bitmap buttons or toggles.
A toolbar gives faster access to an application's facilities than
menus, which have to be popped up and selected rather laboriously.
Besides which, a toolbar looks prettier than a purely menu-based
interface.

wxToolBar uses a canvas subwindow for drawing bitmaps, and so bitmap
images cannot be mixed with panel items, but in most cases this won't
be important. A toolbar might appear as a single row of images under
the menubar, or it might be in a separate frame layout in several rows
and columns. The class handles the layout of the images, unless explicit
positioning is requested.

A tool is a bitmap which can either be a button (there is no `state',
it just generates an event when clicked) or it can be a toggle. If a
toggle, a second bitmap can be provided to depict the `on' state; if
the second bitmap is omitted, either the inverse of the first bitmap
will be used (for monochrome displays) or a thick border is drawn
around the bitmap (for colour displays where inverting will not have
the desired result).

Mouse click events for a given button are sent to a member called
\rtfsp{\bf OnLeftClick}, and so an application must derive from wxToolBar in order
to use it. The application can also handle {\bf OnMouseEnter} events for
the tools, to give the user extra feedback about the tools as the mouse
moves over them.

\normalbox{This toolbar class does not give as slick an appearance as,
or the responsiveness of, conventional Windows toolbars. The buttons are not
given a 3D appearance and do not depress like normal buttons. However, you
can use the optimized wxButtonBar library for greatly improved Windows behaviour,
and behaviour under X identical to wxToolBar.
See \helpref{The wxButtonBar library}{wxbuttonbaroverview}.}

\subsection{Using the toolbar library}

Include the file {\tt wx\_tbar.h} to use this class.

An example of toolbar use is given in the sample program contained in {\tt
test.cc} and {\tt test.h}.  This creates a main window, and two
toolbars: a floating toolbar with 24 tools, and a toolbar along the
top of the main drawing canvas, divided into groups.  The icons for
this second toolbar would normally be quite small.

The test program defines a general-purpose derived frame called
\rtfsp{\bf wxFrameWithToolBar} which can manage a frame with one main subwindow
and one horizontal toolbar.

Note that one of the bitmaps on the floating toolbar is a small version of the
main graphic: this demonstrates how a memory device context can be used to
draw into a bitmap. An application which allowed the user to build up a symbol
library dynamically might create this kind of bitmap.

Left clicks and movements over the toolbars are intercepted and information
is displayed on the status line.

The following fragment illustrates the essence of creating a toolbar.

\begin{verbatim}
  toolBarBitmaps[0] = new wxBitmap("icon1");
  toolBarBitmaps[1] = new wxBitmap("icon2");
  toolBarBitmaps[2] = new wxBitmap("icon3");
  ...

  toolBarFrame = new wxFrame(NULL, "Tools", 0, 0, 300, 200,
    wxSDI | wxDEFAULT_FRAME | wxSTAY_ON_TOP);

  toolBar = new TestToolBar(toolBarFrame, 10, 10, -1, -1, 0, wxVERTICAL, 5);
  toolBar->SetMargins(2, 2);
  toolBar->GetDC()->SetBackground(wxGREY_BRUSH);

  for (int i = 10; i < 25; i++)
    toolBar->AddTool(i, toolBarBitmaps[i], NULL, TRUE);

  toolBar->Layout();
  float maxWidth, maxHeight;
  toolBar->GetMaxSize(&maxWidth, &maxHeight);
  toolBarFrame->SetClientSize((int)maxWidth, (int)maxHeight);
  toolBarFrame->Show(TRUE);
\end{verbatim}

\subsection{The wxButtonBar library}\label{wxbuttonbaroverview}

\overview{wxToolBar overview}{wxtoolbaroverview}

Class: \helpref{wxButtonBar}{wxbuttonbar}

wxToolBar does the job, but it isn't as slick as it could be. The wxButtonBar
library class presents an almost identical Application Programming
Interface, but under Windows, the buttons are 3D and depress properly.

Under Windows, it expects 16-colour bitmaps that are 16 pixels wide and 15 pixels
high. If you want to use a different size, call {\bf wxButtonBar::SetDefaultSize}\rtfsp
as the demo shows, before adding tools to the button bar. Don't supply more than
one bitmap for each tool, because wxButtonBar generates all three images (normal,
depressed and checked) from the single bitmap you give it.

Include the file {\tt wx\_bbar.h} to use this class.

X-optimized (or generic) button bar code may follow at a future date.

\section{Database classes overview}\label{odbcoverview}

Classes: \helpref{wxDatabase}{wxdatabase}, \helpref{wxRecordSet}{wxrecordset}, \helpref{wxQueryCol}{wxquerycol},
\rtfsp\helpref{wxQueryField}{wxqueryfield}

\normalboxd{IMPORTANT NOTE: The ODBC classes are a preliminary release and incomplete. Please
take this into account when using them. Feedback and bug fixes are appreciated,
as always. The classes are being developed by Olaf Klein (oklein@smallo.ruhr.de) and
Patrick Halke (patrick@zaphod.ruhr.de).}

wxWindows provides a set of classes for accessing a subset of Microsoft's ODBC (Open Database Connectivity)
product. Currently, this wrapper is available under MS Windows only, although
ODBC may appear on other platforms, and a generic or product-specific SQL emulator for the ODBC
classes may be provided in wxWindows at a later date.

ODBC presents a unified API (Application Programmer's Interface) to a
wide variety of databases, by interfacing indirectly to each database or
file via an ODBC driver. The language for most of the database
operations is SQL, so you need to learn a small amount of SQL as well as
the wxWindows ODBC wrapper API. Even though the databases may not be
SQL-based, the ODBC drivers translate SQL into appropriate operations
for the database or file: even text files have rudimentry ODBC support,
along with dBASE, Access, Excel and other file formats.

The run-time files for ODBC are bundled with many existing database
packages, including MS Office. The required header files, sql.h and
sqlext.h, are bundled with several compilers including MS VC++ and
Watcom C++. The only other way to obtain these header files is from the
ODBC SDK, which is only available with the MS Developer Network CD-ROMs
-- at great expense. If you have odbc.dll, you can make the required
import library odbc.lib using the tool `implib'. You need to have odbc.lib
in your compiler library path.

The minimum you need to distribute with your application is odbc.dll, which must
go in the Windows system directory. For the application to function correctly,
ODBC drivers must be installed on the user's machine. If you do not use the database
classes, odbc.dll will be loaded but not called (so ODBC does not need to be
setup fully if no ODBC calls will be made).

A sample is distributed with wxWindows in {\tt samples/odbc}. You will need to install
the sample dbf file as a data source using the ODBC setup utility, available from
the control panel if ODBC has been fully installed.

\subsection{Procedures for writing an ODBC application}

You first need to create a wxDatabase object. If you want to get information
from the ODBC manager instead of from a particular database (for example
using \helpref{wxRecordSet::GetDataSources}{wxrecordsetgetdatasources}), then you
do not need to call \helpref{wxDatabase::Open}{wxdatabaseopen}.
If you do wish to connect to a datasource, then call wxDatabase::Open.
You can reuse your wxDatabase object, calling wxDatabase::Close and wxDatabase::Open
multiple times.

Then, create a wxRecordSet object for retrieving or sending information.
For ODBC manager information retrieval, you can create it as a dynaset (retrieve the
information as needed) or a snapshot (get all the data at once).
If you are going to call \helpref{wxRecordSet::ExecuteSQL}{wxrecordsetexecutesql}, you need to create it as a snapshot.
Dynaset mode is not yet implemented for user data.

Having called a function such as wxRecordSet::ExecuteSQL or
wxRecordSet::GetDataSources, you may have a number of records
associated with the recordset, if appropriate to the operation. You can
now retrieve information such as the number of records retrieved and the
actual data itself. Use \helpref{wxRecordSet::GetFieldData}{wxrecordsetgetfielddata} or
\helpref{wxRecordSet::GetFieldDataPtr}{wxrecordsetgetfielddataptr} to get the data or a pointer to it, passing
a column index or name. The data returned will be for the current
record. To move around the records, use \helpref{wxRecordSet::MoveNext}{wxrecordsetmovenext},
\rtfsp\helpref{wxRecordSet::MovePrev}{wxrecordsetmoveprev} and associated functions.

You can use the same recordset for multiple operations, or delete
the recordset and create a new one.

Note that when you delete a wxDatabase, any associated recordsets
also get deleted, so beware of holding onto invalid pointers.

\subsection{wxDatabase overview}\label{wxdatabaseoverview}

\overview{Database classes overview}{odbcoverview}

Class: \helpref{wxDatabase}{wxdatabase}

Every database object represents an ODBC connection. To do anything useful
with a database object you need to bind a wxRecordSet object to it. All you
can do with wxDatabase is opening/closing connections and getting some info
about it (users, passwords, and so on).

\subsection{wxQueryCol overview}\label{wxquerycoloverview}

\overview{Database classes overview}{odbcoverview}

Class: \helpref{wxQueryCol}{wxquerycol}

Every data column is represented by an instance of this class.
It contains the name and type of a column and a list of wxQueryFields where
the real data is stored. The links to user-defined variables are stored
here, as well.

\subsection{wxQueryField overview}\label{wxqueryfieldoverview}

\overview{Database classes overview}{odbcoverview}

Class: \helpref{wxQueryField}{wxqueryfield}

As every data column is represented by an instance of the class wxQueryCol,
every data item of a specific column is represented by an instance of
wxQueryField. Each column contains a list of wxQueryFields. If wxRecordSet is
of the type wxOPEN\_TYPE\_DYNASET, there will be only one field for each column,
which will be updated every time you call functions like wxRecordSet::Move
or wxRecordSet::GoTo. If wxRecordSet is of the type wxOPEN\_TYPE\_SNAPSHOT,
all data returned by an ODBC function will be loaded at once and the number
of wxQueryField instances for each column will depend on the number of records.

\subsection{wxRecordSet overview}\label{wxrecordsetoverview}

\overview{Database classes overview}{odbcoverview}

Class: \helpref{wxRecordSet}{wxrecordset}

Each wxRecordSet represents a database query. You can make multiple queries
at a time by using multiple wxRecordSets with a wxDatabase or you can make
your queries in sequential order using the same wxRecordSet.

\subsection{ODBC SQL data types}\label{sqltypes}

\overview{Database classes overview}{odbcoverview}

These are the data types supported in ODBC SQL. Note that there are other, extended level conformance
types, not currently supported in wxWindows.

\begin{twocollist}\itemsep=0pt
\twocolitem{CHAR(n)}{A character string of fixed length {\it n}.}
\twocolitem{VARCHAR(n)}{A varying length character string of maximum length {\it n}.}
\twocolitem{LONG VARCHAR(n)}{A varying length character string: equivalent to VARCHAR for the purposes
of ODBC.}
\twocolitem{DECIMAL(p, s)}{An exact numeric of precision {\it p} and scale {\it s}.}
\twocolitem{NUMERIC(p, s)}{Same as DECIMAL.}
\twocolitem{SMALLINT}{A 2 byte integer.}
\twocolitem{INTEGER}{A 4 byte integer.}
\twocolitem{REAL}{A 4 byte floating point number.}
\twocolitem{FLOAT}{An 8 byte floating point number.}
\twocolitem{DOUBLE PRECISION}{Same as FLOAT.}
\end{twocollist}

These data types correspond to the following ODBC identifiers:

\begin{twocollist}\itemsep=0pt
\twocolitem{SQL\_CHAR}{A character string of fixed length.}
\twocolitem{SQL\_VARCHAR}{A varying length character string.}
\twocolitem{SQL\_DECIMAL}{An exact numeric.}
\twocolitem{SQL\_NUMERIC}{Same as SQL\_DECIMAL.}
\twocolitem{SQL\_SMALLINT}{A 2 byte integer.}
\twocolitem{SQL\_INTEGER}{A 4 byte integer.}
\twocolitem{SQL\_REAL}{A 4 byte floating point number.}
\twocolitem{SQL\_FLOAT}{An 8 byte floating point number.}
\twocolitem{SQL\_DOUBLE}{Same as SQL\_FLOAT.}
\end{twocollist}

\subsection{A selection of SQL commands}\label{sqlcommands}

\overview{Database classes overview}{odbcoverview}

The following is a very brief description of some common SQL commands, with
examples.

\subsubsection{Create}

Creates a table.

Example:

\begin{verbatim}
CREATE TABLE Book
 (BookNumber     INTEGER     PRIMARY KEY
 , CategoryCode  CHAR(2)     DEFAULT 'RO' NOT NULL
 , Title         VARCHAR(100) UNIQUE
 , NumberOfPages SMALLINT
 , RetailPriceAmount NUMERIC(5,2)
 )
\end{verbatim}

\subsubsection{Insert}

Inserts records into a table.

Example:

\begin{verbatim}
INSERT INTO Book
  (BookNumber, CategoryCode, Title)
  VALUES(5, 'HR', 'The Lark Ascending')
\end{verbatim}

\subsubsection{Select}

The Select operation retrieves rows and columns from a table. The criteria
for selection and the columns returned may be specified.

Examples:

\verb$SELECT * FROM Book$

Selects all rows and columns from table Book.

\verb$SELECT Title, RetailPriceAmount FROM Book WHERE RetailPriceAmount > 20.0$

Selects columns Title and RetailPriceAmount from table Book, returning only
the rows that match the WHERE clause.

\verb$SELECT * FROM Book WHERE CatCode = 'LL' OR CatCode = 'RR'$

Selects all columns from table Book, returning only
the rows that match the WHERE clause.

\verb$SELECT * FROM Book WHERE CatCode IS NULL$

Selects all columns from table Book, returning only rows where the CatCode column
is NULL.

\verb$SELECT * FROM Book ORDER BY Title$

Selects all columns from table Book, ordering by Title, in ascending order. To specify
descending order, add DESC after the ORDER BY Title clause.

\verb$SELECT Title FROM Book WHERE RetailPriceAmount >= 20.0 AND RetailPriceAmount <= 35.0$

Selects records where RetailPriceAmount conforms to the WHERE expression.

\subsubsection{Update}

Updates records in a table.

Example:

\verb$UPDATE Incident SET X = 123 WHERE ASSET = 'BD34'$

This example sets a field in column `X' to the number 123, for the record
where the column ASSET has the value `BD34'.


\section{Debugging overview}\label{debuggingoverview}

Classes: \helpref{wxDebugContext}{wxdebugcontext}, \helpref{wxDebugStreamBuf}{wxdebugstreambuf},
\rtfsp\helpref{wxObject}{wxobject}

\normalboxd{{\bf IMPORTANT NOTE:} The debugging facilities in wxWindows are new (June 1995)
so please be careful when using them. Since they operate at a low level
by redefining memory allocation operators, there may be unforeseen problems on specific platforms.
Proceed with caution!}

Various classes, functions and macros are provided in wxWindows to help you debug
your application. Most of these are only available if you compile both wxWindows,
your application and {\it all} libraries that use wxWindows with the DEBUG flag
set to 1 or more.

wxDebugContext is a class that never gets instantiated, but ties together
various functions and variables. It allows you to set the debugging stream, dump
all objects to that stream, write statistics about object allocation, and
check memory for errors.

You can use the \helpref{TRACE}{trace} macro to output debugging information in DEBUG mode;
it will be defined to nothing for non-debugging code.

It is good practice to define a Dump member function for each class you derive
from a wxWindows class, so that wxDebugContext::Dump can call it and
give valuable information about the state of the application.

For wxDebugContext to do its work, the {\it new} and {\it delete}\rtfsp
operators for wxObject have been redefined to store extra information
about dynamically allocated objects (but not statically declared
objects). This slows down a debugging version of an application, but can
in theory find difficult-to-detect memory leaks (objects are not
deallocated), overwrites (writing past the end of your object) and
underwrites (writing to memory in front of the object).

If you have difficulty tracking down a memory leak, recompile
in debugging mode and call wxDebugContext::Dump and wxDebugContext::Statistics
at appropriate places. They will tell you what objects have not yet been
deleted, and what kinds of object they are.

If you use the macro DEBUG\_NEW instead of the normal 'new', the debugging
output (and error messages reporting memory problems) will also tell you what
file and on what line you allocated the object.

To avoid the need for replacing existing new operators with DEBUG\_NEW, you
can write this at the top of each application file:

\begin{verbatim}
#define new DEBUG\_NEW
\end{verbatim}

In non-debugging mode, this will revert to the usual interpretation
of new. Note that for this not to mess up new-based allocation of non-wxObject derived classes and
built-in types, there are global definitions of new and delete which match
the syntax required for storing filename and line numbers. These merely
call malloc and free, and so do not do anything interesting. The definitions
may possibly cause multiple symbol problems for some compilers and so might
need to be omitted by setting the USE\_GLOBAL\_MEMORY\_OPERATORS to 0 in wx\_setup.h

\subsection{wxDebugContext overview}\label{wxdebugcontextoverview}

\overview{Debugging overview}{debuggingoverview}

Class: \helpref{wxDebugContext}{wxdebugcontext}

wxDebugContext is a class for performing various debugging and memory tracing
operations. Only present in a debugging build of wxWindows,
i.e. if the DEBUG symbol is defined and non-zero.

This class has only static data and function members, and there should be
no instances. Probably the most useful members are SetFile (for directing output
to a file, instead of the default standard error or debugger output);
Dump (for dumping the dynamically allocated objects) and PrintStatistics
(for dumping information about allocation of objects). You can also call
Check to check memory blocks for integrity.

Here's an example of use. The SetCheckpoint ensures that only the
allocations done after the checkpoint will be dumped. Unfortunately
the define of new to DEBUG\_NEW does not work for Borland C++ (and
perhaps other compilers) because it fails to find the correct overloaded
operator for non-object usage of new. Instead, you need to use DEBUG\_NEW
explicitly if there are any examples of non-object new usage in the file.

\begin{verbatim}
#define new DEBUG_NEW

  wxDebugContext::SetCheckpoint();

  wxDebugContext::SetFile("c:\\temp\\debug.log");

  wxString *thing = new wxString;

  // Proves that defining 'new' to be 'DEBUG_NEW' doesn't mess up
  // non-object allocation. Doesn't work for Borland C++.
  char *ordinaryNonObject = new char[1000];

  wxDebugContext::Dump();
  wxDebugContext::PrintStatistics();
\end{verbatim}


\section{Writing a wxWindows application: a rough guide}\label{roughguide}

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}\rtfsp
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}\rtfsp
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{Notes on using the reference}\label{referencenotes}

In the 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.


