1 \chapter{Functions
}\label{functions
}
2 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
3 \setfooter{\thepage}{}{}{}{}{\thepage}
5 The functions defined in wxWindows are described here.
7 \section{File functions
}\label{filefunctions
}
9 \wxheading{Include files
}
15 \helpref{wxPathList
}{wxpathlist
}
17 \membersection{::wxDirExists
}
19 \func{bool
}{wxDirExists
}{\param{const wxString\&
}{dirname
}}
21 Returns TRUE if the directory exists.
23 \membersection{::wxDos2UnixFilename
}
25 \func{void
}{Dos2UnixFilename
}{\param{const wxString\&
}{s
}}
27 Converts a DOS to a Unix filename by replacing backslashes with forward
30 \membersection{::wxFileExists
}
32 \func{bool
}{wxFileExists
}{\param{const wxString\&
}{filename
}}
34 Returns TRUE if the file exists.
36 \membersection{::wxFileNameFromPath
}
38 \func{wxString
}{wxFileNameFromPath
}{\param{const wxString\&
}{path
}}
40 Returns a temporary pointer to the filename for a full path.
41 Copy this pointer for long-term use.
43 \membersection{::wxFindFirstFile
}\label{wxfindfirstfile
}
45 \func{wxString
}{wxFindFirstFile
}{\param{const wxString\&
}{spec
},
\param{int
}{ flags =
0}}
47 This function does directory searching; returns the first file
48 that matches the path
{\it spec
}, or NULL. Use
\helpref{wxFindNextFile
}{wxfindnextfile
} to
49 get the next matching file.
51 {\it spec
} may contain wildcards.
53 {\it flags
} is reserved for future use.
55 The returned filename is a pointer to static memory so should
61 wxString f = wxFindFirstFile("/home/project/*.*");
69 \membersection{::wxFindNextFile
}\label{wxfindnextfile
}
71 \func{wxString
}{wxFindFirstFile
}{\void}
73 Returns the next file that matches the path passed to
\helpref{wxFindFirstFile
}{wxfindfirstfile
}.
75 \membersection{::wxGetOSDirectory
}\label{wxgetosdirectory
}
77 \func{wxString
}{wxGetOSDirectory
}{\void}
79 Returns the Windows directory under Windows; on other platforms returns the empty string.
81 \membersection{::wxIsAbsolutePath
}
83 \func{bool
}{wxIsAbsolutePath
}{\param{const wxString\&
}{filename
}}
85 Returns TRUE if the argument is an absolute filename, i.e. with a slash
86 or drive name at the beginning.
88 \membersection{::wxPathOnly
}
90 \func{wxString
}{wxPathOnly
}{\param{const wxString\&
}{path
}}
92 Returns a temporary pointer to the directory part of the filename. Copy this
93 pointer for long-term use.
95 \membersection{::wxUnix2DosFilename
}
97 \func{void
}{wxUnix2DosFilename
}{\param{const wxString\&
}{s
}}
99 Converts a Unix to a DOS filename by replacing forward
100 slashes with backslashes.
102 \membersection{::wxConcatFiles
}
104 \func{bool
}{wxConcatFiles
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
},
105 \param{const wxString\&
}{file3
}}
107 Concatenates
{\it file1
} and
{\it file2
} to
{\it file3
}, returning
110 \membersection{::wxCopyFile
}
112 \func{bool
}{wxCopyFile
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
}}
114 Copies
{\it file1
} to
{\it file2
}, returning TRUE if successful.
116 \membersection{::wxGetCwd
}\label{wxgetcwd
}
118 \func{wxString
}{wxGetCwd
}{\void}
120 Returns a string containing the current (or working) directory.
122 \membersection{::wxGetHostName
}\label{wxgethostname
}
124 \func{bool
}{wxGetHostName
}{\param{const wxString\&
}{buf
},
\param{int
}{sz
}}
126 Copies the current host machine's name into the supplied buffer.
128 Under Windows or NT, this function first looks in the environment
129 variable SYSTEM
\_NAME; if this is not found, the entry
{\bf HostName
}\rtfsp
130 in the
{\bf wxWindows
} section of the WIN.INI file is tried.
132 Returns TRUE if successful, FALSE otherwise.
134 \membersection{::wxGetEmailAddress
}\label{wxgetemailaddress
}
136 \func{bool
}{wxGetEmailAddress
}{\param{const wxString\&
}{buf
},
\param{int
}{sz
}}
138 Copies the user's email address into the supplied buffer, by
139 concatenating the values returned by
\helpref{wxGetHostName
}{wxgethostname
}\rtfsp
140 and
\helpref{wxGetUserId
}{wxgetuserid
}.
142 Returns TRUE if successful, FALSE otherwise.
144 \membersection{::wxGetUserId
}\label{wxgetuserid
}
146 \func{bool
}{wxGetUserId
}{\param{const wxString\&
}{buf
},
\param{int
}{sz
}}
148 Copies the current user id into the supplied buffer.
150 Under Windows or NT, this function first looks in the environment
151 variables USER and LOGNAME; if neither of these is found, the entry
{\bf UserId
}\rtfsp
152 in the
{\bf wxWindows
} section of the WIN.INI file is tried.
154 Returns TRUE if successful, FALSE otherwise.
156 \membersection{::wxGetUserName
}\label{wxgetusername
}
158 \func{bool
}{wxGetUserName
}{\param{const wxString\&
}{buf
},
\param{int
}{sz
}}
160 Copies the current user name into the supplied buffer.
162 Under Windows or NT, this function looks for the entry
{\bf UserName
}\rtfsp
163 in the
{\bf wxWindows
} section of the WIN.INI file. If PenWindows
164 is running, the entry
{\bf Current
} in the section
{\bf User
} of
165 the PENWIN.INI file is used.
167 Returns TRUE if successful, FALSE otherwise.
169 \membersection{::wxGetWorkingDirectory
}
171 \func{wxString
}{wxGetWorkingDirectory
}{\param{const wxString\&
}{buf=NULL
},
\param{int
}{sz=
1000}}
173 This function is obsolete: use
\helpref{wxGetCwd
}{wxgetcwd
} instead.
175 Copies the current working directory into the buffer if supplied, or
176 copies the working directory into new storage (which you must delete yourself)
177 if the buffer is NULL.
179 {\it sz
} is the size of the buffer if supplied.
181 \membersection{::wxGetTempFileName
}
183 \func{wxString
}{wxGetTempFileName
}{\param{const wxString\&
}{prefix
},
\param{const wxString\&
}{buf=NULL
}}
185 Makes a temporary filename based on
{\it prefix
}, opens and closes the file,
186 and places the name in
{\it buf
}. If
{\it buf
} is NULL, new store
187 is allocated for the temporary filename using
{\it new
}.
189 Under Windows, the filename will include the drive and name of the
190 directory allocated for temporary files (usually the contents of the
191 TEMP variable). Under Unix, the
{\tt /tmp
} directory is used.
193 It is the application's responsibility to create and delete the file.
195 \membersection{::wxIsWild
}\label{wxiswild
}
197 \func{bool
}{wxIsWild
}{\param{const wxString\&
}{pattern
}}
199 Returns TRUE if the pattern contains wildcards. See
\helpref{wxMatchWild
}{wxmatchwild
}.
201 \membersection{::wxMatchWild
}\label{wxmatchwild
}
203 \func{bool
}{wxMatchWild
}{\param{const wxString\&
}{pattern
},
\param{const wxString\&
}{text
},
\param{bool
}{ dot
\_special}}
205 Returns TRUE if the
{\it pattern
}\/ matches the
{\it text
}\/; if
{\it
206 dot
\_special}\/ is TRUE, filenames beginning with a dot are not matched
207 with wildcard characters. See
\helpref{wxIsWild
}{wxiswild
}.
209 \membersection{::wxMkdir
}
211 \func{bool
}{wxMkdir
}{\param{const wxString\&
}{dir
}}
213 Makes the directory
{\it dir
}, returning TRUE if successful.
215 \membersection{::wxRemoveFile
}
217 \func{bool
}{wxRemoveFile
}{\param{const wxString\&
}{file
}}
219 Removes
{\it file
}, returning TRUE if successful.
221 \membersection{::wxRenameFile
}
223 \func{bool
}{wxRenameFile
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
}}
225 Renames
{\it file1
} to
{\it file2
}, returning TRUE if successful.
227 \membersection{::wxRmdir
}
229 \func{bool
}{wxRmdir
}{\param{const wxString\&
}{dir
},
\param{int
}{ flags=
0}}
231 Removes the directory
{\it dir
}, returning TRUE if successful. Does not work under VMS.
233 The
{\it flags
} parameter is reserved for future use.
235 \membersection{::wxSetWorkingDirectory
}
237 \func{bool
}{wxSetWorkingDirectory
}{\param{const wxString\&
}{dir
}}
239 Sets the current working directory, returning TRUE if the operation succeeded.
240 Under MS Windows, the current drive is also changed if
{\it dir
} contains a drive specification.
242 \section{String functions
}
244 \membersection{::copystring
}
246 \func{char*
}{copystring
}{\param{const char*
}{s
}}
248 Makes a copy of the string
{\it s
} using the C++ new operator, so it can be
249 deleted with the
{\it delete
} operator.
251 \membersection{::wxStringMatch
}
253 \func{bool
}{wxStringMatch
}{\param{const wxString\&
}{s1
},
\param{const wxString\&
}{s2
},\\
254 \param{bool
}{ subString = TRUE
},
\param{bool
}{ exact = FALSE
}}
256 Returns TRUE if the substring
{\it s1
} is found within
{\it s2
},
257 ignoring case if
{\it exact
} is FALSE. If
{\it subString
} is FALSE,
258 no substring matching is done.
260 \membersection{::wxStringEq
}\label{wxstringeq
}
262 \func{bool
}{wxStringEq
}{\param{const wxString\&
}{s1
},
\param{const wxString\&
}{s2
}}
267 #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) ==
0))
270 \membersection{::wxTransferFileToStream
}\label{wxtransferfiletostream
}
272 \func{bool
}{wxTransferFileToStream
}{\param{const wxString\&
}{filename
},
\param{ostream\&
}{stream
}}
274 Copies the given file to
{\it stream
}. Useful when converting an old application to
275 use streams (within the
document/view framework, for example).
277 Use of this function requires the file wx
\_doc.h to be included.
279 \membersection{::wxTransferStreamToFile
}\label{wxtransferstreamtofile
}
281 \func{bool
}{wxTransferStreamToFile
}{\param{istream\&
}{stream
} \param{const wxString\&
}{filename
}}
283 Copies the given stream to the file
{\it filename
}. Useful when converting an old application to
284 use streams (within the
document/view framework, for example).
286 Use of this function requires the file wx
\_doc.h to be included.
288 \section{Dialog functions
}\label{dialogfunctions
}
290 Below are a number of convenience functions for getting input from the
291 user or displaying messages. Note that in these functions the last three
292 parameters are optional. However, it is recommended to pass a parent frame
293 parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
294 the front when the dialog box is popped up.
296 \membersection{::wxFileSelector
}\label{wxfileselector
}
298 \func{wxString
}{wxFileSelector
}{\param{const wxString\&
}{message
},
\param{const wxString\&
}{default
\_path = NULL
},\\
299 \param{const wxString\&
}{default
\_filename = NULL
},
\param{const wxString\&
}{default
\_extension = NULL
},\\
300 \param{const wxString\&
}{wildcard = ``*.*''
},
\param{int
}{flags =
0},
\param{wxWindow *
}{parent = NULL
},\\
301 \param{int
}{ x = -
1},
\param{int
}{ y = -
1}}
303 Pops up a file selector box. In Windows, this is the common file selector
304 dialog. In X, this is a file selector box with somewhat less functionality.
305 The path and filename are distinct elements of a full file pathname.
306 If path is NULL, the current directory will be used. If filename is NULL,
307 no default filename will be supplied. The wildcard determines what files
308 are displayed in the file selector, and file extension supplies a type
309 extension for the required filename. Flags may be a combination of wxOPEN,
310 wxSAVE, wxOVERWRITE
\_PROMPT, wxHIDE
\_READONLY, or
0. They are only significant
311 at present in Windows.
313 Both the X and Windows versions implement a wildcard filter. Typing a
314 filename containing wildcards
(*, ?) in the filename text item, and
315 clicking on Ok, will result in only those files matching the pattern being
316 displayed. In the X version, supplying no default name will result in the
317 wildcard filter being inserted in the filename text item; the filter is
318 ignored if a default name is supplied.
320 Under Windows (only), the wildcard may be a specification for multiple
321 types of file with a description for each, such as:
324 "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif"
327 The application must check for a NULL return value (the user pressed
328 Cancel). For example:
331 const wxString\& s = wxFileSelector("Choose a file to open");
338 Remember that the returned pointer is temporary and should be copied
339 if other wxWindows calls will be made before the value is to be used.
341 \wxheading{Include files}
345 \membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
347 \func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
348 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
349 \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = TRUE}}
351 Pop up a dialog box with title set to {\it caption}, message {\it message}, and a
352 \rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
353 or press Cancel to return NULL.
355 If {\it centre} is TRUE, the message text (which may include new line characters)
356 is centred; if FALSE, the message is left-justified.
358 \wxheading{Include files}
362 \membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
364 \func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
365 \param{int }{nsel}, \param{int *}{selection},
366 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
367 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
369 Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
370 listbox. The user may choose one or more item(s) and press OK or Cancel.
372 The number of initially selected choices, and array of the selected indices,
373 are passed in; this array will contain the user selections on exit, with
374 the function returning the number of selections. {\it selection} must be
375 as big as the number of choices, in case all are selected.
377 If Cancel is pressed, -1 is returned.
379 {\it choices} is an array of {\it n} strings for the listbox.
381 If {\it centre} is TRUE, the message text (which may include new line characters)
382 is centred; if FALSE, the message is left-justified.
384 \wxheading{Include files}
388 \membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
390 \func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
391 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
392 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
394 Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection
395 listbox. The user may choose an item and press OK to return a string or
396 Cancel to return NULL.
398 {\it choices} is an array of {\it n} strings for the listbox.
400 If {\it centre} is TRUE, the message text (which may include new line characters)
401 is centred; if FALSE, the message is left-justified.
403 \wxheading{Include files}
407 \membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
409 \func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
410 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
411 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
413 As {\bf wxGetSingleChoice} but returns the index representing the selected string.
414 If the user pressed cancel, -1 is returned.
416 \wxheading{Include files}
420 \membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
422 \func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
423 \param{const wxString\& }{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\
424 \param{int}{ y = -1}, \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
426 As {\bf wxGetSingleChoice} but takes an array of client data pointers
427 corresponding to the strings, and returns one of these pointers.
429 \wxheading{Include files}
433 \membersection{::wxMessageBox}\label{wxmessagebox}
435 \func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
436 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
438 General purpose message dialog. {\it style} may be a bit list of the
439 following identifiers:
441 \begin{twocollist}\itemsep=0pt
442 \twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
444 \twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
446 \twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
447 \twocolitem{wxCENTRE}{Centres the text.}
448 \twocolitem{wxICON\_EXCLAMATION}{Under Windows, displays an exclamation mark symbol.}
449 \twocolitem{wxICON\_HAND}{Under Windows, displays a hand symbol.}
450 \twocolitem{wxICON\_QUESTION}{Under Windows, displays a question mark symbol.}
451 \twocolitem{wxICON\_INFORMATION}{Under Windows, displays an information symbol.}
454 The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
460 int answer = wxMessageBox("Quit program?", "Confirm",
461 wxYES_NO | wxCANCEL, main_frame);
467 {\it message} may contain newline characters, in which case the
468 message will be split into separate lines, to cater for large messages.
470 Under Windows, the native MessageBox function is used unless wxCENTRE
471 is specified in the style, in which case a generic function is used.
472 This is because the native MessageBox function cannot centre text.
473 The symbols are not shown when the generic function is used.
475 \wxheading{Include files}
479 \section{GDI functions}\label{gdifunctions}
481 The following are relevant to the GDI (Graphics Device Interface).
483 \wxheading{Include files}
487 \membersection{::wxColourDisplay}
489 \func{bool}{wxColourDisplay}{\void}
491 Returns TRUE if the display is colour, FALSE otherwise.
493 \membersection{::wxDisplayDepth}
495 \func{int}{wxDisplayDepth}{\void}
497 Returns the depth of the display (a value of 1 denotes a monochrome display).
499 \membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
501 \func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
502 \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
504 Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
505 makes it into a placeable metafile by prepending a header containing the given
506 bounding box. The bounding box may be obtained from a device context after drawing
507 into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
509 In addition to adding the placeable metafile header, this function adds
510 the equivalent of the following code to the start of the metafile data:
513 SetMapMode(dc, MM_ANISOTROPIC);
514 SetWindowOrg(dc, minX, minY);
515 SetWindowExt(dc, maxX - minX, maxY - minY);
518 This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
520 Placeable metafiles may be imported by many Windows applications, and can be
521 used in RTF (Rich Text Format) files.
523 {\it scale} allows the specification of scale for the metafile.
525 This function is only available under Windows.
527 \membersection{::wxSetCursor}\label{wxsetcursor}
529 \func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
531 Globally sets the cursor; only has an effect in MS Windows.
532 See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
534 \section{Printer settings}\label{printersettings}
536 The following functions are used to control PostScript printing. Under
537 Windows, PostScript output can only be sent to a file.
539 \wxheading{Include files}
543 \membersection{::wxGetPrinterCommand}
545 \func{wxString}{wxGetPrinterCommand}{\void}
547 Gets the printer command used to print a file. The default is {\tt lpr}.
549 \membersection{::wxGetPrinterFile}
551 \func{wxString}{wxGetPrinterFile}{\void}
553 Gets the PostScript output filename.
555 \membersection{::wxGetPrinterMode}
557 \func{int}{wxGetPrinterMode}{\void}
559 Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
560 The default is PS\_PREVIEW.
562 \membersection{::wxGetPrinterOptions}
564 \func{wxString}{wxGetPrinterOptions}{\void}
566 Gets the additional options for the print command (e.g. specific printer). The default is nothing.
568 \membersection{::wxGetPrinterOrientation}
570 \func{int}{wxGetPrinterOrientation}{\void}
572 Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
574 \membersection{::wxGetPrinterPreviewCommand}
576 \func{wxString}{wxGetPrinterPreviewCommand}{\void}
578 Gets the command used to view a PostScript file. The default depends on the platform.
580 \membersection{::wxGetPrinterScaling}
582 \func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
584 Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
586 \membersection{::wxGetPrinterTranslation}
588 \func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
590 Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
592 \membersection{::wxSetPrinterCommand}
594 \func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
596 Sets the printer command used to print a file. The default is {\tt lpr}.
598 \membersection{::wxSetPrinterFile}
600 \func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
602 Sets the PostScript output filename.
604 \membersection{::wxSetPrinterMode}
606 \func{void}{wxSetPrinterMode}{\param{int }{mode}}
608 Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
609 The default is PS\_PREVIEW.
611 \membersection{::wxSetPrinterOptions}
613 \func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
615 Sets the additional options for the print command (e.g. specific printer). The default is nothing.
617 \membersection{::wxSetPrinterOrientation}
619 \func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
621 Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
623 \membersection{::wxSetPrinterPreviewCommand}
625 \func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
627 Sets the command used to view a PostScript file. The default depends on the platform.
629 \membersection{::wxSetPrinterScaling}
631 \func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
633 Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
635 \membersection{::wxSetPrinterTranslation}
637 \func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
639 Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
641 \section{Clipboard functions}\label{clipsboard}
643 These clipboard functions are implemented for Windows only.
645 \wxheading{Include files}
649 \membersection{::wxClipboardOpen}
651 \func{bool}{wxClipboardOpen}{\void}
653 Returns TRUE if this application has already opened the clipboard.
655 \membersection{::wxCloseClipboard}
657 \func{bool}{wxCloseClipboard}{\void}
659 Closes the clipboard to allow other applications to use it.
661 \membersection{::wxEmptyClipboard}
663 \func{bool}{wxEmptyClipboard}{\void}
665 Empties the clipboard.
667 \membersection{::wxEnumClipboardFormats}
669 \func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
671 Enumerates the formats found in a list of available formats that belong
672 to the clipboard. Each call to this function specifies a known
673 available format; the function returns the format that appears next in
676 {\it dataFormat} specifies a known format. If this parameter is zero,
677 the function returns the first format in the list.
679 The return value specifies the next known clipboard data format if the
680 function is successful. It is zero if the {\it dataFormat} parameter specifies
681 the last format in the list of available formats, or if the clipboard
684 Before it enumerates the formats function, an application must open the clipboard by using the
685 wxOpenClipboard function.
687 \membersection{::wxGetClipboardData}
689 \func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
691 Gets data from the clipboard.
693 {\it dataFormat} may be one of:
695 \begin{itemize}\itemsep=0pt
696 \item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
697 \item wxCF\_BITMAP: returns a new wxBitmap.
700 The clipboard must have previously been opened for this call to succeed.
702 \membersection{::wxGetClipboardFormatName}
704 \func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
706 Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
707 length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
709 \membersection{::wxIsClipboardFormatAvailable}
711 \func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
713 Returns TRUE if the given data format is available on the clipboard.
715 \membersection{::wxOpenClipboard}
717 \func{bool}{wxOpenClipboard}{\void}
719 Opens the clipboard for passing data to it or getting data from it.
721 \membersection{::wxRegisterClipboardFormat}
723 \func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
725 Registers the clipboard data format name and returns an identifier.
727 \membersection{::wxSetClipboardData}
729 \func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
731 Passes data to the clipboard.
733 {\it dataFormat} may be one of:
735 \begin{itemize}\itemsep=0pt
736 \item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
737 \item wxCF\_BITMAP: {\it data} is a wxBitmap.
738 \item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
739 \item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
742 The clipboard must have previously been opened for this call to succeed.
744 \section{Miscellaneous functions}\label{miscellany}
746 \membersection{::wxNewId}
748 \func{long}{wxNewId}{\void}
750 Generates an integer identifier unique to this run of the program.
752 \wxheading{Include files}
756 \membersection{::wxRegisterId}
758 \func{void}{wxRegisterId}{\param{long}{ id}}
760 Ensures that ids subsequently generated by {\bf NewId} do not clash with
763 \wxheading{Include files}
767 \membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
769 \func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
771 Changes the cursor to the given cursor for all windows in the application.
772 Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
773 to its previous state. These two calls can be nested, and a counter
774 ensures that only the outer calls take effect.
776 See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
778 \wxheading{Include files}
782 \membersection{::wxBell}
784 \func{void}{wxBell}{\void}
786 Ring the system bell.
788 \wxheading{Include files}
792 \membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
794 \func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
796 Creates and returns an object of the given class, if the class has been
797 registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
799 \membersection{::wxDDECleanUp}\label{wxddecleanup}
801 \func{void}{wxDDECleanUp}{\void}
803 Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
804 called by the application.
806 See also helpref{wxDDEInitialize}{wxddeinitialize}.
808 \wxheading{Include files}
812 \membersection{::wxDDEInitialize}\label{wxddeinitialize}
814 \func{void}{wxDDEInitialize}{\void}
816 Initializes the DDE system. May be called multiple times without harm.
818 This no longer needs to be called by the application: it will be called
819 by wxWindows if necessary.
821 See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
822 \helpref{wxDDECleanUp}{wxddecleanup}.
824 \wxheading{Include files}
828 \membersection{::wxDebugMsg}\label{wxdebugmsg}
830 \func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
832 Display a debugging message; under Windows, this will appear on the
833 debugger command window, and under Unix, it will be written to standard
836 The syntax is identical to {\bf printf}: pass a format string and a
837 variable list of arguments.
839 Note that under Windows, you can see the debugging messages without a
840 debugger if you have the DBWIN debug log application that comes with
843 {\bf Tip:} under Windows, if your application crashes before the
844 message appears in the debugging window, put a wxYield call after
845 each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
846 (at least for Watcom C++): preformat your messages and use OutputDebugString
849 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
851 \wxheading{Include files}
855 \membersection{::wxDisplaySize}
857 \func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
859 Gets the physical size of the display in pixels.
861 \wxheading{Include files}
865 \membersection{::wxEntry}\label{wxentry}
867 This initializes wxWindows in a platform-dependent way. Use this if you
868 are not using the default wxWindows entry code (e.g. main or WinMain). For example,
869 you can initialize wxWindows from an Microsoft Foundation Classes application using
872 \func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
873 \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
875 wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
876 function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
877 message loop will be entered.
879 \func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
880 \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
882 wxWindows initialization under Windows (for applications constructed as a DLL).
884 \func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
886 wxWindows initialization under Unix.
890 To clean up wxWindows, call wxApp::OnExit followed by the static function
891 wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:
894 int CTheApp::ExitInstance()
896 // OnExit isn't called by CleanUp so must be called explicitly.
900 return CWinApp::ExitInstance();
904 \wxheading{Include files}
908 \membersection{::wxError}\label{wxerror}
910 \func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
912 Displays {\it msg} and continues. This writes to standard error under
913 Unix, and pops up a message box under Windows. Used for internal
914 wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
916 \wxheading{Include files}
920 \membersection{::wxEndBusyCursor}\label{wxendbusycursor}
922 \func{void}{wxEndBusyCursor}{\void}
924 Changes the cursor back to the original cursor, for all windows in the application.
925 Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
927 See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
929 \wxheading{Include files}
933 \membersection{::wxExecute}\label{wxexecute}
935 \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
937 \func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
939 Executes another program in Unix or Windows.
941 The first form takes a command string, such as {\tt "emacs file.txt"}.
943 The second form takes an array of values: a command, any number of
944 arguments, terminated by NULL.
946 If {\it sync} is FALSE (the default), flow of control immediately returns.
947 If TRUE, the current application waits until the other program has terminated.
949 In the case of synchronous execution, the return value is trhe exit code of
950 the process (which terminates by the moment the function returns) and will be
951 $-1$ if the process couldn't be started and typically 0 if the process
952 terminated successfully.
954 For asynchronous execution, however, the return value is the process id and
955 zero value indicates that the command could not be executed.
957 If callback isn't NULL and if execution is asynchronous (note that callback
958 parameter can not be non NULL for synchronous execution),
959 \helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
960 the process finishes.
962 See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}.
964 \wxheading{Include files}
968 \membersection{::wxExit}\label{wxexit}
970 \func{void}{wxExit}{\void}
972 Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
973 Should only be used in an emergency: normally the top-level frame
974 should be deleted (after deleting all other frames) to terminate the
975 application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
977 \wxheading{Include files}
981 \membersection{::wxFatalError}\label{wxfatalerror}
983 \func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
985 Displays {\it msg} and exits. This writes to standard error under Unix,
986 and pops up a message box under Windows. Used for fatal internal
987 wxWindows errors. See also \helpref{wxError}{wxerror}.
989 \wxheading{Include files}
993 \membersection{::wxFindMenuItemId}
995 \func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
997 Find a menu item identifier associated with the given frame's menu bar.
999 \wxheading{Include files}
1003 \membersection{::wxFindWindowByLabel}
1005 \func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
1007 Find a window by its label. Depending on the type of window, the label may be a window title
1008 or panel item label. If {\it parent} is NULL, the search will start from all top-level
1009 frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1010 The search is recursive in both cases.
1012 \wxheading{Include files}
1016 \membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
1018 \func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
1020 Find a window by its name (as given in a window constructor or {\bf Create} function call).
1021 If {\it parent} is NULL, the search will start from all top-level
1022 frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1023 The search is recursive in both cases.
1025 If no such named window is found, {\bf wxFindWindowByLabel} is called.
1027 \wxheading{Include files}
1031 \membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
1033 \func{wxWindow *}{wxGetActiveWindow}{\void}
1035 Gets the currently active window (Windows only).
1037 \wxheading{Include files}
1041 \membersection{::wxGetDisplayName}\label{wxgetdisplayname}
1043 \func{wxString}{wxGetDisplayName}{\void}
1045 Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
1047 \wxheading{Include files}
1051 \membersection{::wxGetHomeDir}
1053 \func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}}
1055 Fills the buffer with a string representing the user's home directory (Unix only).
1057 \wxheading{Include files}
1061 \membersection{::wxGetHostName}
1063 \func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1065 Copies the host name of the machine the program is running on into the
1066 buffer {\it buf}, of maximum size {\it bufSize}, returning TRUE if
1067 successful. Under Unix, this will return a machine name. Under Windows,
1068 this returns ``windows''.
1070 \wxheading{Include files}
1074 \membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
1076 \func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}}
1078 Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
1080 If {\it resetTimer} is TRUE (the default), the timer is reset to zero
1083 See also \helpref{wxTimer}{wxtimer}.
1085 \wxheading{Include files}
1089 \membersection{::wxGetFreeMemory}\label{wxgetfreememory}
1091 \func{long}{wxGetFreeMemory}{\void}
1093 Returns the amount of free memory in Kbytes under environments which
1094 support it, and -1 if not supported. Currently, returns a positive value
1095 under Windows, and -1 under Unix.
1097 \wxheading{Include files}
1101 \membersection{::wxGetMousePosition}
1103 \func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}}
1105 Returns the mouse position in screen coordinates.
1107 \wxheading{Include files}
1111 \membersection{::wxGetOsVersion}
1113 \func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
1115 Gets operating system version information.
1117 \begin{twocollist}\itemsep=0pt
1118 \twocolitemruled{Platform}{Return tyes}
1119 \twocolitem{Macintosh}{Return value is wxMACINTOSH.}
1120 \twocolitem{GTK}{Return value is wxGTK, {\it major} is 1, {\it minor} is 0. (for GTK 1.0.X) }
1121 \twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
1122 \twocolitem{OS/2}{Return value is wxOS2\_PM.}
1123 \twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
1124 \twocolitem{Windows NT}{Return value is wxWINDOWS\_NT, {\it major} is 3, {\it minor} is 1.}
1125 \twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 3, {\it minor} is 1.}
1126 \twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
1127 \twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
1130 \wxheading{Include files}
1134 \membersection{::wxGetResource}\label{wxgetresource}
1136 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1137 \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
1139 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1140 \param{float *}{value}, \param{const wxString\& }{file = NULL}}
1142 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1143 \param{long *}{value}, \param{const wxString\& }{file = NULL}}
1145 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1146 \param{int *}{value}, \param{const wxString\& }{file = NULL}}
1148 Gets a resource value from the resource database (for example, WIN.INI, or
1149 .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1150 otherwise the specified file is used.
1152 Under X, if an application class (wxApp::GetClassName) has been defined,
1153 it is appended to the string /usr/lib/X11/app-defaults/ to try to find
1154 an applications default file when merging all resource databases.
1156 The reason for passing the result in an argument is that it
1157 can be convenient to define a default value, which gets overridden
1158 if the value exists in the resource file. It saves a separate
1159 test for that resource's existence, and it also allows
1160 the overloading of the function for different types.
1162 See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
1164 \wxheading{Include files}
1168 \membersection{::wxGetUserId}
1170 \func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1172 Copies the user's login identity (such as ``jacs'') into the buffer {\it
1173 buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1174 Under Windows, this returns ``user''.
1176 \wxheading{Include files}
1180 \membersection{::wxGetUserName}
1182 \func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1184 Copies the user's name (such as ``Julian Smart'') into the buffer {\it
1185 buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1186 Under Windows, this returns ``unknown''.
1188 \wxheading{Include files}
1192 \membersection{::wxKill}\label{wxkill}
1194 \func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
1196 Under Unix (the only supported platform), equivalent to the Unix kill function.
1197 Returns 0 on success, -1 on failure.
1199 Tip: sending a signal of 0 to a process returns -1 if the process does not exist.
1200 It does not raise a signal in the receiving process.
1202 \wxheading{Include files}
1206 \membersection{::wxIsBusy}\label{wxisbusy}
1208 \func{bool}{wxIsBusy}{\void}
1210 Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
1211 \helpref{wxEndBusyCursor}{wxendbusycursor} calls.
1213 See also \helpref{wxBusyCursor}{wxbusycursor}.
1215 \wxheading{Include files}
1219 \membersection{::wxLoadUserResource}\label{wxloaduserresource}
1221 \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
1223 Loads a user-defined Windows resource as a string. If the resource is found, the function creates
1224 a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
1226 The resource must be defined in the {\tt .rc} file using the following syntax:
1229 myResource TEXT file.ext
1232 where {\tt file.ext} is a file that the resource compiler can find.
1234 One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers
1235 cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed
1236 using \helpref{wxResourceParseString}{wxresourceparsestring}.
1238 This function is available under Windows only.
1240 \wxheading{Include files}
1244 \membersection{::wxNow}\label{wxnow}
1246 \func{wxString}{wxNow}{\void}
1248 Returns a string representing the current date and time.
1250 \wxheading{Include files}
1254 \membersection{::wxPostDelete}\label{wxpostdelete}
1256 \func{void}{wxPostDelete}{\param{wxObject *}{object}}
1258 Tells the system to delete the specified object when
1259 all other events have been processed. In some environments, it is
1260 necessary to use this instead of deleting a frame directly with the
1261 delete operator, because some GUIs will still send events to a deleted window.
1263 Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
1265 \wxheading{Include files}
1269 \membersection{::wxSetDisplayName}\label{wxsetdisplayname}
1271 \func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
1273 Under X only, sets the current display name. This is the X host and display name such
1274 as ``colonsay:0.0", and the function indicates which display should be used for creating
1275 windows from this point on. Setting the display within an application allows multiple
1276 displays to be used.
1278 See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
1280 \wxheading{Include files}
1284 \membersection{::wxShell}\label{wxshell}
1286 \func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
1288 Executes a command in an interactive shell window. If no command is
1289 specified, then just the shell is spawned.
1291 See also \helpref{wxExecute}{wxexecute}.
1293 \wxheading{Include files}
1297 \membersection{::wxSleep}\label{wxsleep}
1299 \func{void}{wxSleep}{\param{int}{ secs}}
1301 Sleeps for the specified number of seconds.
1303 \wxheading{Include files}
1307 \membersection{::wxStripMenuCodes}
1309 \func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
1311 \func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}}
1313 Strips any menu codes from {\it in} and places the result
1314 in {\it out} (or returns the new string, in the first form).
1316 Menu codes include \& (mark the next character with an underline
1317 as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
1319 \wxheading{Include files}
1323 \membersection{::wxStartTimer}\label{wxstarttimer}
1325 \func{void}{wxStartTimer}{\void}
1327 Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
1329 See also \helpref{wxTimer}{wxtimer}.
1331 \wxheading{Include files}
1335 \membersection{::wxToLower}\label{wxtolower}
1337 \func{char}{wxToLower}{\param{char }{ch}}
1339 Converts the character to lower case. This is implemented as a macro for efficiency.
1341 \wxheading{Include files}
1345 \membersection{::wxToUpper}\label{wxtoupper}
1347 \func{char}{wxToUpper}{\param{char }{ch}}
1349 Converts the character to upper case. This is implemented as a macro for efficiency.
1351 \wxheading{Include files}
1355 \membersection{::wxTrace}\label{wxtrace}
1357 \func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
1359 Takes printf-style variable argument syntax. Output
1360 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1362 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1364 \wxheading{Include files}
1368 \membersection{::wxTraceLevel}\label{wxtracelevel}
1370 \func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
1372 Takes printf-style variable argument syntax. Output
1373 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1374 The first argument should be the level at which this information is appropriate.
1375 It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
1378 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1380 \wxheading{Include files}
1384 \membersection{::wxWriteResource}\label{wxwriteresource}
1386 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1387 \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
1389 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1390 \param{float }{value}, \param{const wxString\& }{file = NULL}}
1392 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1393 \param{long }{value}, \param{const wxString\& }{file = NULL}}
1395 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1396 \param{int }{value}, \param{const wxString\& }{file = NULL}}
1398 Writes a resource value into the resource database (for example, WIN.INI, or
1399 .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1400 otherwise the specified file is used.
1402 Under X, the resource databases are cached until the internal function
1403 \rtfsp{\bf wxFlushResources} is called automatically on exit, when
1404 all updated resource databases are written to their files.
1406 Note that it is considered bad manners to write to the .Xdefaults
1407 file under Unix, although the WIN.INI file is fair game under Windows.
1409 See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
1411 \wxheading{Include files}
1415 \membersection{::wxYield}
1417 \func{bool}{wxYield}{\void}
1419 Yields control to pending messages in the windowing system. This can be useful, for example, when a
1420 time-consuming process writes to a text window. Without an occasional
1421 yield, the text window will not be updated properly, and (since Windows
1422 multitasking is cooperative) other processes will not respond.
1424 Caution should be exercised, however, since yielding may allow the
1425 user to perform actions which are not compatible with the current task.
1426 Disabling menu items or whole menus during processing can avoid unwanted
1429 \wxheading{Include files}
1433 \section{Macros}\label{macros}
1435 These macros are defined in wxWindows.
1437 \membersection{CLASSINFO}\label{classinfo}
1439 \func{wxClassInfo *}{CLASSINFO}{className}
1441 Returns a pointer to the wxClassInfo object associated with this class.
1443 \wxheading{Include files}
1447 \membersection{WXDEBUG\_NEW}\label{debugnew}
1449 \func{}{WXDEBUG\_NEW}{arg}
1451 This is defined in debug mode to be call the redefined new operator
1452 with filename and line number arguments. The definition is:
1455 #define WXDEBUG_NEW new(__FILE__,__LINE__)
1458 In non-debug mode, this is defined as the normal new operator.
1460 \wxheading{Include files}
1464 \membersection{DECLARE\_ABSTRACT\_CLASS}
1466 \func{}{DECLARE\_ABSTRACT\_CLASS}{className}
1468 Used inside a class declaration to declare that the class should be
1469 made known to the class hierarchy, but objects of this class cannot be created
1470 dynamically. The same as DECLARE\_CLASS.
1475 class wxCommand: public wxObject
1477 DECLARE_ABSTRACT_CLASS(wxCommand)
1486 \wxheading{Include files}
1490 \membersection{DECLARE\_APP}\label{declareapp}
1492 \func{}{DECLARE\_APP}{className}
1494 This is used in headers to create a forward declaration of the wxGetApp function implemented
1495 by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}.
1503 \wxheading{Include files}
1507 \membersection{DECLARE\_CLASS}
1509 \func{}{DECLARE\_CLASS}{className}
1511 Used inside a class declaration to declare that the class should be
1512 made known to the class hierarchy, but objects of this class cannot be created
1513 dynamically. The same as DECLARE\_ABSTRACT\_CLASS.
1515 \wxheading{Include files}
1519 \membersection{DECLARE\_DYNAMIC\_CLASS}
1521 \func{}{DECLARE\_DYNAMIC\_CLASS}{className}
1523 Used inside a class declaration to declare that the objects of this class should be dynamically
1524 createable from run-time type information.
1529 class wxFrame: public wxWindow
1531 DECLARE_DYNAMIC_CLASS(wxFrame)
1534 const wxString\& frameTitle;
1540 \wxheading{Include files}
1544 \membersection{IMPLEMENT\_ABSTRACT\_CLASS}
1546 \func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
1548 Used in a C++ implementation file to complete the declaration of
1549 a class that has run-time type information. The same as IMPLEMENT\_CLASS.
1554 IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
1556 wxCommand::wxCommand(void)
1562 \wxheading{Include files}
1566 \membersection{IMPLEMENT\_ABSTRACT\_CLASS2}
1568 \func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
1570 Used in a C++ implementation file to complete the declaration of
1571 a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
1573 \wxheading{Include files}
1577 \membersection{IMPLEMENT\_APP}\label{implementapp}
1579 \func{}{IMPLEMENT\_APP}{className}
1581 This is used in the application class implementation file to make the application class known to
1582 wxWindows for dynamic construction. You use this instead of
1593 IMPLEMENT_APP(MyApp)
1596 See also \helpref{DECLARE\_APP}{declareapp}.
1598 \wxheading{Include files}
1602 \membersection{IMPLEMENT\_CLASS}
1604 \func{}{IMPLEMENT\_CLASS}{className, baseClassName}
1606 Used in a C++ implementation file to complete the declaration of
1607 a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
1609 \wxheading{Include files}
1613 \membersection{IMPLEMENT\_CLASS2}
1615 \func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
1617 Used in a C++ implementation file to complete the declaration of a
1618 class that has run-time type information and two base classes. The
1619 same as IMPLEMENT\_ABSTRACT\_CLASS2.
1621 \wxheading{Include files}
1625 \membersection{IMPLEMENT\_DYNAMIC\_CLASS}
1627 \func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
1629 Used in a C++ implementation file to complete the declaration of
1630 a class that has run-time type information, and whose instances
1631 can be created dynamically.
1636 IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
1638 wxFrame::wxFrame(void)
1644 \wxheading{Include files}
1648 \membersection{IMPLEMENT\_DYNAMIC\_CLASS2}
1650 \func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
1652 Used in a C++ implementation file to complete the declaration of
1653 a class that has run-time type information, and whose instances
1654 can be created dynamically. Use this for classes derived from two
1657 \wxheading{Include files}
1661 \membersection{WXTRACE}\label{trace}
1663 \func{}{WXTRACE}{formatString, ...}
1665 Calls wxTrace with printf-style variable argument syntax. Output
1666 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1668 This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1670 \wxheading{Include files}
1674 \membersection{WXTRACELEVEL}\label{tracelevel}
1676 \func{}{WXTRACELEVEL}{level, formatString, ...}
1678 Calls wxTraceLevel with printf-style variable argument syntax. Output
1679 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1680 The first argument should be the level at which this information is appropriate.
1681 It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
1684 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1686 \wxheading{Include files}
1690 \section{wxWindows resource functions}\label{resourcefuncs}
1692 \overview{wxWindows resource system}{resourceformats}
1694 This section details functions for manipulating wxWindows (.WXR) resource
1695 files and loading user interface elements from resources.
1697 \normalbox{Please note that this use of the word `resource' is different from that used when talking
1698 about initialisation file resource reading and writing, using such functions
1699 as wxWriteResource and wxGetResource. It's just an unfortunate clash of terminology.}
1701 \helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
1703 See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
1704 loading from resource data.
1706 {\bf Warning:} this needs updating for wxWindows 2.
1708 \membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
1710 \func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
1712 Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
1713 \verb$#$defining a name to an integer). Unlikely to be used by an application except
1714 perhaps for implementing resource functionality for interpreted languages.
1716 \membersection{::wxResourceClear}
1718 \func{void}{wxResourceClear}{\void}
1720 Clears the wxWindows resource table.
1722 \membersection{::wxResourceCreateBitmap}
1724 \func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
1726 Creates a new bitmap from a file, static data, or Windows resource, given a valid
1727 wxWindows bitmap resource identifier. For example, if the .WXR file contains
1731 static const wxString\& aiai_resource = "bitmap(name = 'aiai_resource',\
1732 bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
1733 bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X']).";
1736 then this function can be called as follows:
1739 wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource");
1742 \membersection{::wxResourceCreateIcon}
1744 \func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
1746 Creates a new icon from a file, static data, or Windows resource, given a valid
1747 wxWindows icon resource identifier. For example, if the .WXR file contains
1751 static const wxString\& aiai_resource = "icon(name = 'aiai_resource',\
1752 icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
1753 icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X']).";
1756 then this function can be called as follows:
1759 wxIcon *icon = wxResourceCreateIcon("aiai_resource");
1762 \membersection{::wxResourceCreateMenuBar}
1764 \func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
1766 Creates a new menu bar given a valid wxWindows menubar resource
1767 identifier. For example, if the .WXR file contains the following:
1770 static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
1774 ['&Open File', 2, 'Open a file'],\
1775 ['&Save File', 3, 'Save a file'],\
1777 ['E&xit', 4, 'Exit program']\
1780 ['&About', 6, 'About this program']\
1785 then this function can be called as follows:
1788 wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
1792 \membersection{::wxResourceGetIdentifier}
1794 \func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
1796 Used for retrieving the integer value associated with an identifier.
1797 A zero value indicates that the identifier was not found.
1799 See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
1801 \membersection{::wxResourceParseData}\label{wxresourcedata}
1803 \func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
1805 Parses a string containing one or more wxWindows resource objects. If
1806 the resource objects are global static data that are included into the
1807 C++ program, then this function must be called for each variable
1808 containing the resource data, to make it known to wxWindows.
1810 {\it resource} should contain data in the following form:
1813 dialog(name = 'dialog1',
1814 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
1815 title = 'Test dialog box',
1816 x = 312, y = 234, width = 400, height = 300,
1818 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
1819 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
1820 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',
1821 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
1822 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
1823 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
1826 This function will typically be used after including a {\tt .wxr} file into
1827 a C++ program as follows:
1830 #include "dialog1.wxr"
1833 Each of the contained resources will declare a new C++ variable, and each
1834 of these variables should be passed to wxResourceParseData.
1836 \membersection{::wxResourceParseFile}
1838 \func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
1840 Parses a file containing one or more wxWindows resource objects
1841 in C++-compatible syntax. Use this function to dynamically load
1842 wxWindows resource data.
1844 \membersection{::wxResourceParseString}\label{wxresourceparsestring}
1846 \func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
1848 Parses a string containing one or more wxWindows resource objects. If
1849 the resource objects are global static data that are included into the
1850 C++ program, then this function must be called for each variable
1851 containing the resource data, to make it known to wxWindows.
1853 {\it resource} should contain data with the following form:
1856 static const wxString\& dialog1 = "dialog(name = 'dialog1',\
1857 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',\
1858 title = 'Test dialog box',\
1859 x = 312, y = 234, width = 400, height = 300,\
1861 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,\
1862 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],\
1863 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',\
1864 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',\
1865 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
1866 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).";
1869 This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
1870 load an entire {\tt .wxr file} into a string.
1872 \membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
1874 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width},
1875 \param{int }{height}, \param{wxResourceTable *}{table = NULL}}
1877 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}}
1879 Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system.
1880 This is required if other resources will use the bitmap data, since otherwise there
1881 is no connection between names used in resources, and the global bitmap data.
1883 \membersection{::wxResourceRegisterIconData}
1885 Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
1887 \section{Log functions}\label{logfunctions}
1889 These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
1890 further information.
1892 \wxheading{Include files}
1896 \membersection{::wxLogError}\label{wxlogerror}
1898 \func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
1900 The function to use for error messages, i.e. the
1901 messages that must be shown to the user. The default processing is to pop up a
1902 message box to inform the user about it.
1904 \membersection{::wxLogFatalError}\label{wxlogfatalerror}
1906 \func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}}
1908 Like \helpref{wxLogError}{wxlogerror}, but also
1909 terminates the program with the exit code 3. Using {\it abort()} standard
1910 function also terminates the program with this exit code.
1912 \membersection{::wxLogWarning}\label{wxlogwarning}
1914 \func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}}
1916 For warnings - they are also normally shown to the
1917 user, but don't interrupt the program work.
1919 \membersection{::wxLogMessage}\label{wxlogmessage}
1921 \func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}}
1923 for all normal, informational messages. They also
1924 appear in a message box by default (but it can be changed). Notice
1925 that the standard behaviour is to not show informational messages if there are
1926 any errors later - the logic being that the later error messages make the
1927 informational messages preceding them meaningless.
1929 \membersection{::wxLogVerbose}\label{wxlogverbose}
1931 \func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}}
1933 For verbose output. Normally, it's suppressed, but
1934 might be activated if the user wishes to know more details about the program
1935 progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
1937 \membersection{::wxLogStatus}\label{wxlogstatus}
1939 \func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}}
1941 For status messages - they will go into the status
1942 bar of the active or specified (as the first argument) \helpref{wxFrame}{wxframe} if it has one.
1944 \membersection{::wxLogSysError}\label{wxlogsyserror}
1946 \func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}}
1948 Mostly used by wxWindows itself, but might be
1949 handy for logging errors after system call (API function) failure. It logs the
1950 specified message text as well as the last system error code ({\it errno} or {\it ::GetLastError()} depending
1951 on the platform) and the corresponding error
1952 message. The second form of this function takes the error code explitly as the
1955 \membersection{::wxLogDebug}\label{wxlogdebug}
1957 \func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}}
1959 The right function for debug output. It only
1960 does anything at all in the debug mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined)
1961 and expands to nothing in release mode (otherwise).
1963 \membersection{::wxLogTrace}\label{wxlogtrace}
1965 \func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}}
1967 \func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}}
1969 As {\bf wxLogDebug}, only does something in debug
1970 build. The reason for making it a separate function from it is that usually
1971 there are a lot of trace messages, so it might make sense to separate them
1972 from other debug messages which would be flooded in them. Moreover, the second
1973 version of this function takes a trace mask as the first argument which allows
1974 to further restrict the amount of messages generated. The value of {\it mask} can be:
1976 \begin{itemize}\itemsep=0pt
1977 \item wxTraceMemAlloc: trace memory allocation (new/delete)
1978 \item wxTraceMessages: trace window messages/X callbacks
1979 \item wxTraceResAlloc: trace GDI resource allocation
1980 \item wxTraceRefCount: trace various ref counting operations
1983 \section{Debugging macros and functions}\label{debugmacros}
1985 Useful macros and functins for error checking and defensive programming. ASSERTs are only
1986 compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
1989 \wxheading{Include files}
1993 \membersection{::wxOnAssert}\label{wxonassert}
1995 \func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}}
1997 This function may be redefined to do something non trivial and is called
1998 whenever one of debugging macros fails (i.e. condition is false in an
2000 % TODO: this should probably be an overridable in wxApp.
2002 \membersection{wxASSERT}\label{wxassert}
2004 \func{}{wxASSERT}{\param{}{condition}}
2006 Assert macro. An error message will be generated if the condition is FALSE.
2008 \membersection{wxASSERT\_MSG}\label{wxassertmsg}
2010 \func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
2012 Assert macro with message. An error message will be generated if the condition is FALSE.
2014 \membersection{wxFAIL}\label{wxfail}
2016 \func{}{wxFAIL}{\param{}{condition}}
2018 Will always generate an assert error if this code is reached (in debug mode).
2020 \membersection{wxFAIL\_MSG}\label{wxfailmsg}
2022 \func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}}
2024 Will always generate an assert error with specified message if this code is reached (in debug mode).
2026 \membersection{wxCHECK}\label{wxcheck}
2028 \func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
2030 Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2031 This check is done even in release mode.
2033 \membersection{wxCHECK\_MSG}\label{wxcheckmsg}
2035 \func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
2037 Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2038 This check is done even in release mode.