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