]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/function.tex
wxLog fix as for wxMSW
[wxWidgets.git] / docs / latex / wx / function.tex
CommitLineData
a660d684
KB
1\chapter{Functions}\label{functions}
2\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
3\setfooter{\thepage}{}{}{}{}{\thepage}
4
5The functions defined in wxWindows are described here.
6
7\section{File functions}\label{filefunctions}
8
954b8ae6
JS
9\wxheading{Include files}
10
11<wx/utils.h>
12
13\wxheading{See also}
14
15\helpref{wxPathList}{wxpathlist}
a660d684
KB
16
17\membersection{::wxDirExists}
18
19\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
20
21Returns TRUE if the directory exists.
22
23\membersection{::wxDos2UnixFilename}
24
25\func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}}
26
e2a6f233 27Converts a DOS to a Unix filename by replacing backslashes with forward
a660d684
KB
28slashes.
29
30\membersection{::wxFileExists}
31
32\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
33
34Returns TRUE if the file exists.
35
36\membersection{::wxFileNameFromPath}
37
38\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
39
532372a3
JS
40\func{char*}{wxFileNameFromPath}{\param{char* }{path}}
41
42Returns the filename for a full path. The second form returns a pointer to
43temporary storage that should not be deallocated.
a660d684
KB
44
45\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
46
532372a3 47\func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}}
a660d684
KB
48
49This function does directory searching; returns the first file
532372a3 50that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
a660d684
KB
51get the next matching file.
52
53{\it spec} may contain wildcards.
54
55{\it flags} is reserved for future use.
56
57The returned filename is a pointer to static memory so should
58not be freed.
59
60For example:
61
62\begin{verbatim}
63 wxString f = wxFindFirstFile("/home/project/*.*");
532372a3 64 while (f != "")
a660d684
KB
65 {
66 ...
67 f = wxFindNextFile();
68 }
69\end{verbatim}
70
71\membersection{::wxFindNextFile}\label{wxfindnextfile}
72
73\func{wxString}{wxFindFirstFile}{\void}
74
75Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
76
631f1bfe
JS
77\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
78
79\func{wxString}{wxGetOSDirectory}{\void}
80
81Returns the Windows directory under Windows; on other platforms returns the empty string.
82
a660d684
KB
83\membersection{::wxIsAbsolutePath}
84
85\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
86
87Returns TRUE if the argument is an absolute filename, i.e. with a slash
88or drive name at the beginning.
89
90\membersection{::wxPathOnly}
91
92\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
93
532372a3 94Returns the directory part of the filename.
a660d684
KB
95
96\membersection{::wxUnix2DosFilename}
97
98\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
99
e2a6f233 100Converts a Unix to a DOS filename by replacing forward
a660d684
KB
101slashes with backslashes.
102
103\membersection{::wxConcatFiles}
104
105\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
106\param{const wxString\& }{file3}}
107
108Concatenates {\it file1} and {\it file2} to {\it file3}, returning
109TRUE if successful.
110
111\membersection{::wxCopyFile}
112
113\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
114
115Copies {\it file1} to {\it file2}, returning TRUE if successful.
116
7af89395
VZ
117\membersection{::wxGetCwd}\label{wxgetcwd}
118
119\func{wxString}{wxGetCwd}{\void}
120
121Returns a string containing the current (or working) directory.
122
a660d684
KB
123\membersection{::wxGetHostName}\label{wxgethostname}
124
125\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int }{sz}}
126
127Copies the current host machine's name into the supplied buffer.
128
129Under Windows or NT, this function first looks in the environment
130variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
131in the {\bf wxWindows} section of the WIN.INI file is tried.
132
133Returns TRUE if successful, FALSE otherwise.
134
135\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
136
137\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
138
139Copies the user's email address into the supplied buffer, by
140concatenating the values returned by \helpref{wxGetHostName}{wxgethostname}\rtfsp
141and \helpref{wxGetUserId}{wxgetuserid}.
142
143Returns TRUE if successful, FALSE otherwise.
144
145\membersection{::wxGetUserId}\label{wxgetuserid}
146
147\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int }{sz}}
148
149Copies the current user id into the supplied buffer.
150
151Under Windows or NT, this function first looks in the environment
152variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
153in the {\bf wxWindows} section of the WIN.INI file is tried.
154
155Returns TRUE if successful, FALSE otherwise.
156
157\membersection{::wxGetUserName}\label{wxgetusername}
158
159\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int }{sz}}
160
161Copies the current user name into the supplied buffer.
162
163Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
164in the {\bf wxWindows} section of the WIN.INI file. If PenWindows
165is running, the entry {\bf Current} in the section {\bf User} of
166the PENWIN.INI file is used.
167
168Returns TRUE if successful, FALSE otherwise.
169
170\membersection{::wxGetWorkingDirectory}
171
532372a3 172\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
a660d684 173
7af89395
VZ
174This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
175
a660d684
KB
176Copies the current working directory into the buffer if supplied, or
177copies the working directory into new storage (which you must delete yourself)
178if the buffer is NULL.
179
180{\it sz} is the size of the buffer if supplied.
181
182\membersection{::wxGetTempFileName}
183
532372a3 184\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}}
a660d684
KB
185
186Makes a temporary filename based on {\it prefix}, opens and closes the file,
187and places the name in {\it buf}. If {\it buf} is NULL, new store
188is allocated for the temporary filename using {\it new}.
189
190Under Windows, the filename will include the drive and name of the
191directory allocated for temporary files (usually the contents of the
e2a6f233 192TEMP variable). Under Unix, the {\tt /tmp} directory is used.
a660d684
KB
193
194It is the application's responsibility to create and delete the file.
195
196\membersection{::wxIsWild}\label{wxiswild}
197
198\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
199
200Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
201
202\membersection{::wxMatchWild}\label{wxmatchwild}
203
204\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
205
206Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it
207dot\_special}\/ is TRUE, filenames beginning with a dot are not matched
208with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
209
210\membersection{::wxMkdir}
211
212\func{bool}{wxMkdir}{\param{const wxString\& }{dir}}
213
214Makes the directory {\it dir}, returning TRUE if successful.
215
216\membersection{::wxRemoveFile}
217
218\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
219
220Removes {\it file}, returning TRUE if successful.
221
222\membersection{::wxRenameFile}
223
224\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
225
226Renames {\it file1} to {\it file2}, returning TRUE if successful.
227
228\membersection{::wxRmdir}
229
230\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
231
232Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS.
233
234The {\it flags} parameter is reserved for future use.
235
236\membersection{::wxSetWorkingDirectory}
237
238\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
239
240Sets the current working directory, returning TRUE if the operation succeeded.
241Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
242
d37fd2fa
VZ
243\membersection{::wxSplitPath}\label{wxsplitfunction}
244
245\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{const wxString *}{ path}, \param{const wxString *}{ name}, \param{const wxString *}{ ext}}
246
247This function splits a full file name into components: the path (including possible disk/drive
248specification under Windows), the base name and the extension. Any of the output parameters
249({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
250a particular component.
251
252wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
253Windows, however it will not consider backslashes as path separators under Unix (where backslash
254is a valid character in a filename).
255
256On entry, {\it fullname} should be non NULL (it may be empty though).
257
258On return, {\it path} contains the file path (without the trailing separator), {\it name}
259contains the file name and {\it ext} contains the file extension without leading dot. All
260three of them may be empty if the corresponding component is. The old contents of the
261strings pointed to by these parameters will be overwritten in any case (if the pointers
262are not NULL).
263
a660d684
KB
264\section{String functions}
265
266\membersection{::copystring}
267
268\func{char*}{copystring}{\param{const char* }{s}}
269
270Makes a copy of the string {\it s} using the C++ new operator, so it can be
271deleted with the {\it delete} operator.
272
273\membersection{::wxStringMatch}
274
275\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
276 \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
277
278Returns TRUE if the substring {\it s1} is found within {\it s2},
279ignoring case if {\it exact} is FALSE. If {\it subString} is FALSE,
280no substring matching is done.
281
282\membersection{::wxStringEq}\label{wxstringeq}
283
284\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
285
286A macro defined as:
287
288\begin{verbatim}
289#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
290\end{verbatim}
291
292\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
293
294\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
295
296Copies the given file to {\it stream}. Useful when converting an old application to
297use streams (within the document/view framework, for example).
298
299Use of this function requires the file wx\_doc.h to be included.
300
301\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
302
303\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
304
305Copies the given stream to the file {\it filename}. Useful when converting an old application to
306use streams (within the document/view framework, for example).
307
308Use of this function requires the file wx\_doc.h to be included.
309
310\section{Dialog functions}\label{dialogfunctions}
311
312Below are a number of convenience functions for getting input from the
313user or displaying messages. Note that in these functions the last three
314parameters are optional. However, it is recommended to pass a parent frame
315parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
316the front when the dialog box is popped up.
317
318\membersection{::wxFileSelector}\label{wxfileselector}
319
320\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = NULL},\\
321 \param{const wxString\& }{default\_filename = NULL}, \param{const wxString\& }{default\_extension = NULL},\\
322 \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\
323 \param{int}{ x = -1}, \param{int}{ y = -1}}
324
325Pops up a file selector box. In Windows, this is the common file selector
326dialog. In X, this is a file selector box with somewhat less functionality.
327The path and filename are distinct elements of a full file pathname.
328If path is NULL, the current directory will be used. If filename is NULL,
329no default filename will be supplied. The wildcard determines what files
330are displayed in the file selector, and file extension supplies a type
331extension for the required filename. Flags may be a combination of wxOPEN,
332wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, or 0. They are only significant
333at present in Windows.
334
335Both the X and Windows versions implement a wildcard filter. Typing a
336filename containing wildcards (*, ?) in the filename text item, and
337clicking on Ok, will result in only those files matching the pattern being
338displayed. In the X version, supplying no default name will result in the
339wildcard filter being inserted in the filename text item; the filter is
340ignored if a default name is supplied.
341
342Under Windows (only), the wildcard may be a specification for multiple
343types of file with a description for each, such as:
344
345\begin{verbatim}
346 "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif"
347\end{verbatim}
348
349The application must check for a NULL return value (the user pressed
350Cancel). For example:
351
352\begin{verbatim}
353const wxString\& s = wxFileSelector("Choose a file to open");
354if (s)
355{
356 ...
357}
358\end{verbatim}
359
360Remember that the returned pointer is temporary and should be copied
361if other wxWindows calls will be made before the value is to be used.
362
954b8ae6
JS
363\wxheading{Include files}
364
365<wx/filedlg.h>
366
a660d684
KB
367\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
368
369\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
370 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
371 \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = TRUE}}
372
373Pop up a dialog box with title set to {\it caption}, message {\it message}, and a
374\rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
532372a3 375or press Cancel to return the empty string.
a660d684
KB
376
377If {\it centre} is TRUE, the message text (which may include new line characters)
378is centred; if FALSE, the message is left-justified.
379
954b8ae6
JS
380\wxheading{Include files}
381
382<wx/textdlg.h>
383
a660d684
KB
384\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
385
386\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
387 \param{int }{nsel}, \param{int *}{selection},
388 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
389 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
390
391Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
392listbox. The user may choose one or more item(s) and press OK or Cancel.
393
394The number of initially selected choices, and array of the selected indices,
395are passed in; this array will contain the user selections on exit, with
396the function returning the number of selections. {\it selection} must be
397as big as the number of choices, in case all are selected.
398
399If Cancel is pressed, -1 is returned.
400
401{\it choices} is an array of {\it n} strings for the listbox.
402
403If {\it centre} is TRUE, the message text (which may include new line characters)
404is centred; if FALSE, the message is left-justified.
405
954b8ae6
JS
406\wxheading{Include files}
407
408<wx/choicdlg.h>
409
a660d684
KB
410\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
411
412\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
413 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
414 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
415
416Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection
417listbox. The user may choose an item and press OK to return a string or
532372a3 418Cancel to return the empty string.
a660d684
KB
419
420{\it choices} is an array of {\it n} strings for the listbox.
421
422If {\it centre} is TRUE, the message text (which may include new line characters)
423is centred; if FALSE, the message is left-justified.
424
954b8ae6
JS
425\wxheading{Include files}
426
427<wx/choicdlg.h>
428
a660d684
KB
429\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
430
431\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
432 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
433 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
434
435As {\bf wxGetSingleChoice} but returns the index representing the selected string.
436If the user pressed cancel, -1 is returned.
437
954b8ae6
JS
438\wxheading{Include files}
439
440<wx/choicdlg.h>
441
a660d684
KB
442\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
443
444\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
445 \param{const wxString\& }{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\
446 \param{int}{ y = -1}, \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
447
448As {\bf wxGetSingleChoice} but takes an array of client data pointers
449corresponding to the strings, and returns one of these pointers.
450
954b8ae6
JS
451\wxheading{Include files}
452
453<wx/choicdlg.h>
454
a660d684
KB
455\membersection{::wxMessageBox}\label{wxmessagebox}
456
457\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
458 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
459
460General purpose message dialog. {\it style} may be a bit list of the
461following identifiers:
462
463\begin{twocollist}\itemsep=0pt
464\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
465wxCANCEL.}
466\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
467wxYES\_NO or wxOK.}
468\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
469\twocolitem{wxCENTRE}{Centres the text.}
470\twocolitem{wxICON\_EXCLAMATION}{Under Windows, displays an exclamation mark symbol.}
471\twocolitem{wxICON\_HAND}{Under Windows, displays a hand symbol.}
472\twocolitem{wxICON\_QUESTION}{Under Windows, displays a question mark symbol.}
473\twocolitem{wxICON\_INFORMATION}{Under Windows, displays an information symbol.}
474\end{twocollist}
475
476The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
477
478For example:
479
480\begin{verbatim}
481 ...
482 int answer = wxMessageBox("Quit program?", "Confirm",
483 wxYES_NO | wxCANCEL, main_frame);
484 if (answer == wxYES)
485 delete main_frame;
486 ...
487\end{verbatim}
488
489{\it message} may contain newline characters, in which case the
490message will be split into separate lines, to cater for large messages.
491
492Under Windows, the native MessageBox function is used unless wxCENTRE
493is specified in the style, in which case a generic function is used.
494This is because the native MessageBox function cannot centre text.
495The symbols are not shown when the generic function is used.
496
954b8ae6
JS
497\wxheading{Include files}
498
499<wx/msgdlg.h>
500
a660d684
KB
501\section{GDI functions}\label{gdifunctions}
502
503The following are relevant to the GDI (Graphics Device Interface).
504
954b8ae6
JS
505\wxheading{Include files}
506
507<wx/gdicmn.h>
508
a660d684
KB
509\membersection{::wxColourDisplay}
510
511\func{bool}{wxColourDisplay}{\void}
512
513Returns TRUE if the display is colour, FALSE otherwise.
514
515\membersection{::wxDisplayDepth}
516
517\func{int}{wxDisplayDepth}{\void}
518
519Returns the depth of the display (a value of 1 denotes a monochrome display).
520
e2a6f233 521\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
a660d684 522
e2a6f233 523\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
a660d684
KB
524 \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
525
e2a6f233 526Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
a660d684
KB
527makes it into a placeable metafile by prepending a header containing the given
528bounding box. The bounding box may be obtained from a device context after drawing
529into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
530
531In addition to adding the placeable metafile header, this function adds
532the equivalent of the following code to the start of the metafile data:
533
534\begin{verbatim}
535 SetMapMode(dc, MM_ANISOTROPIC);
536 SetWindowOrg(dc, minX, minY);
537 SetWindowExt(dc, maxX - minX, maxY - minY);
538\end{verbatim}
539
e3065973 540This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
a660d684
KB
541
542Placeable metafiles may be imported by many Windows applications, and can be
543used in RTF (Rich Text Format) files.
544
545{\it scale} allows the specification of scale for the metafile.
546
547This function is only available under Windows.
548
549\membersection{::wxSetCursor}\label{wxsetcursor}
550
551\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
552
553Globally sets the cursor; only has an effect in MS Windows.
554See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
555
a660d684
KB
556\section{Printer settings}\label{printersettings}
557
558The following functions are used to control PostScript printing. Under
559Windows, PostScript output can only be sent to a file.
560
954b8ae6
JS
561\wxheading{Include files}
562
563<wx/dcps.h>
564
a660d684
KB
565\membersection{::wxGetPrinterCommand}
566
567\func{wxString}{wxGetPrinterCommand}{\void}
568
569Gets the printer command used to print a file. The default is {\tt lpr}.
570
571\membersection{::wxGetPrinterFile}
572
573\func{wxString}{wxGetPrinterFile}{\void}
574
575Gets the PostScript output filename.
576
577\membersection{::wxGetPrinterMode}
578
579\func{int}{wxGetPrinterMode}{\void}
580
581Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
582The default is PS\_PREVIEW.
583
584\membersection{::wxGetPrinterOptions}
585
586\func{wxString}{wxGetPrinterOptions}{\void}
587
588Gets the additional options for the print command (e.g. specific printer). The default is nothing.
589
590\membersection{::wxGetPrinterOrientation}
591
592\func{int}{wxGetPrinterOrientation}{\void}
593
594Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
595
596\membersection{::wxGetPrinterPreviewCommand}
597
598\func{wxString}{wxGetPrinterPreviewCommand}{\void}
599
600Gets the command used to view a PostScript file. The default depends on the platform.
601
602\membersection{::wxGetPrinterScaling}
603
604\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
605
606Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
607
608\membersection{::wxGetPrinterTranslation}
609
610\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
611
612Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
613
614\membersection{::wxSetPrinterCommand}
615
616\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
617
618Sets the printer command used to print a file. The default is {\tt lpr}.
619
620\membersection{::wxSetPrinterFile}
621
622\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
623
624Sets the PostScript output filename.
625
626\membersection{::wxSetPrinterMode}
627
628\func{void}{wxSetPrinterMode}{\param{int }{mode}}
629
630Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
631The default is PS\_PREVIEW.
632
633\membersection{::wxSetPrinterOptions}
634
635\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
636
637Sets the additional options for the print command (e.g. specific printer). The default is nothing.
638
639\membersection{::wxSetPrinterOrientation}
640
641\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
642
643Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
644
645\membersection{::wxSetPrinterPreviewCommand}
646
647\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
648
649Sets the command used to view a PostScript file. The default depends on the platform.
650
651\membersection{::wxSetPrinterScaling}
652
653\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
654
655Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
656
657\membersection{::wxSetPrinterTranslation}
658
659\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
660
661Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
662
663\section{Clipboard functions}\label{clipsboard}
664
665These clipboard functions are implemented for Windows only.
666
954b8ae6
JS
667\wxheading{Include files}
668
669<wx/clipbrd.h>
670
a660d684
KB
671\membersection{::wxClipboardOpen}
672
673\func{bool}{wxClipboardOpen}{\void}
674
675Returns TRUE if this application has already opened the clipboard.
676
677\membersection{::wxCloseClipboard}
678
679\func{bool}{wxCloseClipboard}{\void}
680
681Closes the clipboard to allow other applications to use it.
682
683\membersection{::wxEmptyClipboard}
684
685\func{bool}{wxEmptyClipboard}{\void}
686
687Empties the clipboard.
688
689\membersection{::wxEnumClipboardFormats}
690
691\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
692
693Enumerates the formats found in a list of available formats that belong
694to the clipboard. Each call to this function specifies a known
695available format; the function returns the format that appears next in
696the list.
697
698{\it dataFormat} specifies a known format. If this parameter is zero,
699the function returns the first format in the list.
700
701The return value specifies the next known clipboard data format if the
702function is successful. It is zero if the {\it dataFormat} parameter specifies
703the last format in the list of available formats, or if the clipboard
704is not open.
705
706Before it enumerates the formats function, an application must open the clipboard by using the
707wxOpenClipboard function.
708
709\membersection{::wxGetClipboardData}
710
711\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
712
713Gets data from the clipboard.
714
715{\it dataFormat} may be one of:
716
717\begin{itemize}\itemsep=0pt
718\item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
719\item wxCF\_BITMAP: returns a new wxBitmap.
720\end{itemize}
721
722The clipboard must have previously been opened for this call to succeed.
723
724\membersection{::wxGetClipboardFormatName}
725
726\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
727
728Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
729length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
730
731\membersection{::wxIsClipboardFormatAvailable}
732
733\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
734
735Returns TRUE if the given data format is available on the clipboard.
736
737\membersection{::wxOpenClipboard}
738
739\func{bool}{wxOpenClipboard}{\void}
740
741Opens the clipboard for passing data to it or getting data from it.
742
743\membersection{::wxRegisterClipboardFormat}
744
745\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
746
747Registers the clipboard data format name and returns an identifier.
748
749\membersection{::wxSetClipboardData}
750
751\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
752
753Passes data to the clipboard.
754
755{\it dataFormat} may be one of:
756
757\begin{itemize}\itemsep=0pt
758\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
759\item wxCF\_BITMAP: {\it data} is a wxBitmap.
760\item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
e2a6f233 761\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
a660d684
KB
762\end{itemize}
763
764The clipboard must have previously been opened for this call to succeed.
765
766\section{Miscellaneous functions}\label{miscellany}
767
954b8ae6 768\membersection{::wxNewId}
a660d684 769
954b8ae6 770\func{long}{wxNewId}{\void}
a660d684
KB
771
772Generates an integer identifier unique to this run of the program.
773
954b8ae6
JS
774\wxheading{Include files}
775
776<wx/utils.h>
a660d684 777
954b8ae6
JS
778\membersection{::wxRegisterId}
779
780\func{void}{wxRegisterId}{\param{long}{ id}}
a660d684
KB
781
782Ensures that ids subsequently generated by {\bf NewId} do not clash with
783the given {\bf id}.
784
954b8ae6
JS
785\wxheading{Include files}
786
787<wx/utils.h>
788
a660d684
KB
789\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
790
791\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
792
793Changes the cursor to the given cursor for all windows in the application.
794Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
795to its previous state. These two calls can be nested, and a counter
796ensures that only the outer calls take effect.
797
e2a6f233 798See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
a660d684 799
954b8ae6
JS
800\wxheading{Include files}
801
802<wx/utils.h>
803
a660d684
KB
804\membersection{::wxBell}
805
806\func{void}{wxBell}{\void}
807
808Ring the system bell.
809
954b8ae6 810\wxheading{Include files}
a660d684 811
954b8ae6 812<wx/utils.h>
a660d684
KB
813
814\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
815
816\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
817
818Creates and returns an object of the given class, if the class has been
819registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
820
e2a6f233
JS
821\membersection{::wxDDECleanUp}\label{wxddecleanup}
822
823\func{void}{wxDDECleanUp}{\void}
824
825Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
826called by the application.
827
828See also helpref{wxDDEInitialize}{wxddeinitialize}.
829
954b8ae6
JS
830\wxheading{Include files}
831
832<wx/dde.h>
833
e2a6f233
JS
834\membersection{::wxDDEInitialize}\label{wxddeinitialize}
835
836\func{void}{wxDDEInitialize}{\void}
837
838Initializes the DDE system. May be called multiple times without harm.
839
840This no longer needs to be called by the application: it will be called
841by wxWindows if necessary.
842
843See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
844\helpref{wxDDECleanUp}{wxddecleanup}.
845
954b8ae6
JS
846\wxheading{Include files}
847
848<wx/dde.h>
849
e2a6f233 850\membersection{::wxDebugMsg}\label{wxdebugmsg}
a660d684
KB
851
852\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
853
854Display a debugging message; under Windows, this will appear on the
e2a6f233 855debugger command window, and under Unix, it will be written to standard
a660d684
KB
856error.
857
858The syntax is identical to {\bf printf}: pass a format string and a
859variable list of arguments.
860
861Note that under Windows, you can see the debugging messages without a
862debugger if you have the DBWIN debug log application that comes with
863Microsoft C++.
864
865{\bf Tip:} under Windows, if your application crashes before the
866message appears in the debugging window, put a wxYield call after
867each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
868(at least for Watcom C++): preformat your messages and use OutputDebugString
869instead.
870
6fb26ea3
JS
871This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
872
954b8ae6
JS
873\wxheading{Include files}
874
875<wx/utils.h>
876
a660d684
KB
877\membersection{::wxDisplaySize}
878
879\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
880
881Gets the physical size of the display in pixels.
882
954b8ae6
JS
883\wxheading{Include files}
884
885<wx/gdicmn.h>
886
a660d684
KB
887\membersection{::wxEntry}\label{wxentry}
888
889This initializes wxWindows in a platform-dependent way. Use this if you
890are not using the default wxWindows entry code (e.g. main or WinMain). For example,
891you can initialize wxWindows from an Microsoft Foundation Classes application using
954b8ae6 892this function.
a660d684
KB
893
894\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
895 \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
896
897wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
898function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
899message loop will be entered.
900
901\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
902 \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
903
904wxWindows initialization under Windows (for applications constructed as a DLL).
905
906\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
907
e2a6f233 908wxWindows initialization under Unix.
a660d684 909
954b8ae6
JS
910\wxheading{Remarks}
911
912To clean up wxWindows, call wxApp::OnExit followed by the static function
913wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:
914
915\begin{verbatim}
916int CTheApp::ExitInstance()
917{
918 // OnExit isn't called by CleanUp so must be called explicitly.
919 wxTheApp->OnExit();
920 wxApp::CleanUp();
921
922 return CWinApp::ExitInstance();
923}
924\end{verbatim}
925
926\wxheading{Include files}
927
928<wx/app.h>
929
a660d684
KB
930\membersection{::wxError}\label{wxerror}
931
932\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
933
934Displays {\it msg} and continues. This writes to standard error under
e2a6f233 935Unix, and pops up a message box under Windows. Used for internal
a660d684
KB
936wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
937
954b8ae6
JS
938\wxheading{Include files}
939
940<wx/utils.h>
941
a660d684
KB
942\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
943
944\func{void}{wxEndBusyCursor}{\void}
945
946Changes the cursor back to the original cursor, for all windows in the application.
947Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
948
e2a6f233 949See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
a660d684 950
954b8ae6
JS
951\wxheading{Include files}
952
953<wx/utils.h>
954
a660d684
KB
955\membersection{::wxExecute}\label{wxexecute}
956
eafc087e 957\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
a660d684 958
e2a6f233 959\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
a660d684 960
e2a6f233 961Executes another program in Unix or Windows.
a660d684
KB
962
963The first form takes a command string, such as {\tt "emacs file.txt"}.
964
965The second form takes an array of values: a command, any number of
966arguments, terminated by NULL.
967
968If {\it sync} is FALSE (the default), flow of control immediately returns.
969If TRUE, the current application waits until the other program has terminated.
970
e6045e08
VZ
971In the case of synchronous execution, the return value is trhe exit code of
972the process (which terminates by the moment the function returns) and will be
973$-1$ if the process couldn't be started and typically 0 if the process
974terminated successfully.
975
976For asynchronous execution, however, the return value is the process id and
977zero value indicates that the command could not be executed.
a660d684 978
7e84f02d
VZ
979If callback isn't NULL and if execution is asynchronous (note that callback
980parameter can not be non NULL for synchronous execution),
eafc087e
GL
981\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
982the process finishes.
983
984See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}.
a660d684 985
954b8ae6
JS
986\wxheading{Include files}
987
988<wx/utils.h>
989
a660d684
KB
990\membersection{::wxExit}\label{wxexit}
991
992\func{void}{wxExit}{\void}
993
994Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
995Should only be used in an emergency: normally the top-level frame
996should be deleted (after deleting all other frames) to terminate the
997application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
998
954b8ae6
JS
999\wxheading{Include files}
1000
1001<wx/app.h>
1002
a660d684
KB
1003\membersection{::wxFatalError}\label{wxfatalerror}
1004
1005\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
1006
e2a6f233 1007Displays {\it msg} and exits. This writes to standard error under Unix,
a660d684
KB
1008and pops up a message box under Windows. Used for fatal internal
1009wxWindows errors. See also \helpref{wxError}{wxerror}.
1010
954b8ae6
JS
1011\wxheading{Include files}
1012
1013<wx/utils.h>
1014
a660d684
KB
1015\membersection{::wxFindMenuItemId}
1016
1017\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
1018
1019Find a menu item identifier associated with the given frame's menu bar.
1020
954b8ae6
JS
1021\wxheading{Include files}
1022
1023<wx/utils.h>
1024
a660d684
KB
1025\membersection{::wxFindWindowByLabel}
1026
1027\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
1028
1029Find a window by its label. Depending on the type of window, the label may be a window title
1030or panel item label. If {\it parent} is NULL, the search will start from all top-level
1031frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1032The search is recursive in both cases.
1033
954b8ae6
JS
1034\wxheading{Include files}
1035
1036<wx/utils.h>
1037
a660d684
KB
1038\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
1039
1040\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
1041
1042Find a window by its name (as given in a window constructor or {\bf Create} function call).
1043If {\it parent} is NULL, the search will start from all top-level
1044frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1045The search is recursive in both cases.
1046
1047If no such named window is found, {\bf wxFindWindowByLabel} is called.
1048
954b8ae6
JS
1049\wxheading{Include files}
1050
1051<wx/utils.h>
1052
a660d684
KB
1053\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
1054
1055\func{wxWindow *}{wxGetActiveWindow}{\void}
1056
1057Gets the currently active window (Windows only).
1058
954b8ae6
JS
1059\wxheading{Include files}
1060
1061<wx/windows.h>
1062
a660d684
KB
1063\membersection{::wxGetDisplayName}\label{wxgetdisplayname}
1064
1065\func{wxString}{wxGetDisplayName}{\void}
1066
1067Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
1068
954b8ae6
JS
1069\wxheading{Include files}
1070
1071<wx/utils.h>
1072
a660d684
KB
1073\membersection{::wxGetHomeDir}
1074
1075\func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}}
1076
e2a6f233 1077Fills the buffer with a string representing the user's home directory (Unix only).
a660d684 1078
954b8ae6
JS
1079\wxheading{Include files}
1080
1081<wx/utils.h>
1082
a660d684
KB
1083\membersection{::wxGetHostName}
1084
1085\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1086
1087Copies the host name of the machine the program is running on into the
1088buffer {\it buf}, of maximum size {\it bufSize}, returning TRUE if
e2a6f233 1089successful. Under Unix, this will return a machine name. Under Windows,
a660d684
KB
1090this returns ``windows''.
1091
954b8ae6
JS
1092\wxheading{Include files}
1093
1094<wx/utils.h>
1095
a660d684
KB
1096\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
1097
1098\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}}
1099
1100Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
1101
1102If {\it resetTimer} is TRUE (the default), the timer is reset to zero
1103by this call.
1104
1105See also \helpref{wxTimer}{wxtimer}.
1106
954b8ae6
JS
1107\wxheading{Include files}
1108
1109<wx/timer.h>
1110
e2a6f233 1111\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
a660d684
KB
1112
1113\func{long}{wxGetFreeMemory}{\void}
1114
1115Returns the amount of free memory in Kbytes under environments which
1116support it, and -1 if not supported. Currently, returns a positive value
e2a6f233 1117under Windows, and -1 under Unix.
a660d684 1118
954b8ae6
JS
1119\wxheading{Include files}
1120
1121<wx/utils.h>
1122
a660d684
KB
1123\membersection{::wxGetMousePosition}
1124
1125\func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}}
1126
1127Returns the mouse position in screen coordinates.
1128
954b8ae6
JS
1129\wxheading{Include files}
1130
1131<wx/utils.h>
1132
a660d684
KB
1133\membersection{::wxGetOsVersion}
1134
1135\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
1136
1137Gets operating system version information.
1138
1139\begin{twocollist}\itemsep=0pt
1140\twocolitemruled{Platform}{Return tyes}
1141\twocolitem{Macintosh}{Return value is wxMACINTOSH.}
12a44087 1142\twocolitem{GTK}{Return value is wxGTK, {\it major} is 1, {\it minor} is 0. (for GTK 1.0.X) }
a660d684
KB
1143\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
1144\twocolitem{OS/2}{Return value is wxOS2\_PM.}
1145\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
1146\twocolitem{Windows NT}{Return value is wxWINDOWS\_NT, {\it major} is 3, {\it minor} is 1.}
1147\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 3, {\it minor} is 1.}
1148\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
1149\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
1150\end{twocollist}
1151
954b8ae6
JS
1152\wxheading{Include files}
1153
1154<wx/utils.h>
1155
a660d684
KB
1156\membersection{::wxGetResource}\label{wxgetresource}
1157
1158\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1159 \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
1160
1161\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1162 \param{float *}{value}, \param{const wxString\& }{file = NULL}}
1163
1164\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1165 \param{long *}{value}, \param{const wxString\& }{file = NULL}}
1166
1167\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1168 \param{int *}{value}, \param{const wxString\& }{file = NULL}}
1169
1170Gets a resource value from the resource database (for example, WIN.INI, or
1171.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1172otherwise the specified file is used.
1173
e2a6f233 1174Under X, if an application class (wxApp::GetClassName) has been defined,
a660d684
KB
1175it is appended to the string /usr/lib/X11/app-defaults/ to try to find
1176an applications default file when merging all resource databases.
1177
1178The reason for passing the result in an argument is that it
1179can be convenient to define a default value, which gets overridden
1180if the value exists in the resource file. It saves a separate
1181test for that resource's existence, and it also allows
1182the overloading of the function for different types.
1183
e2a6f233 1184See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
a660d684 1185
954b8ae6
JS
1186\wxheading{Include files}
1187
1188<wx/utils.h>
1189
a660d684
KB
1190\membersection{::wxGetUserId}
1191
1192\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1193
1194Copies the user's login identity (such as ``jacs'') into the buffer {\it
1195buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1196Under Windows, this returns ``user''.
1197
954b8ae6
JS
1198\wxheading{Include files}
1199
1200<wx/utils.h>
1201
a660d684
KB
1202\membersection{::wxGetUserName}
1203
1204\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1205
1206Copies the user's name (such as ``Julian Smart'') into the buffer {\it
1207buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1208Under Windows, this returns ``unknown''.
1209
954b8ae6
JS
1210\wxheading{Include files}
1211
1212<wx/utils.h>
1213
a660d684
KB
1214\membersection{::wxKill}\label{wxkill}
1215
1216\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
1217
e2a6f233 1218Under Unix (the only supported platform), equivalent to the Unix kill function.
a660d684
KB
1219Returns 0 on success, -1 on failure.
1220
1221Tip: sending a signal of 0 to a process returns -1 if the process does not exist.
1222It does not raise a signal in the receiving process.
1223
954b8ae6 1224\wxheading{Include files}
a660d684 1225
954b8ae6 1226<wx/utils.h>
a660d684 1227
a660d684
KB
1228\membersection{::wxIsBusy}\label{wxisbusy}
1229
1230\func{bool}{wxIsBusy}{\void}
1231
1232Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
1233\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
1234
e2a6f233
JS
1235See also \helpref{wxBusyCursor}{wxbusycursor}.
1236
954b8ae6
JS
1237\wxheading{Include files}
1238
1239<wx/utils.h>
1240
a660d684
KB
1241\membersection{::wxLoadUserResource}\label{wxloaduserresource}
1242
1243\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
1244
1245Loads a user-defined Windows resource as a string. If the resource is found, the function creates
1246a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
1247
1248The resource must be defined in the {\tt .rc} file using the following syntax:
1249
1250\begin{verbatim}
1251myResource TEXT file.ext
1252\end{verbatim}
1253
1254where {\tt file.ext} is a file that the resource compiler can find.
1255
1256One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers
1257cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed
1258using \helpref{wxResourceParseString}{wxresourceparsestring}.
1259
1260This function is available under Windows only.
1261
954b8ae6
JS
1262\wxheading{Include files}
1263
1264<wx/utils.h>
1265
a660d684
KB
1266\membersection{::wxNow}\label{wxnow}
1267
1268\func{wxString}{wxNow}{\void}
1269
1270Returns a string representing the current date and time.
1271
954b8ae6
JS
1272\wxheading{Include files}
1273
1274<wx/utils.h>
1275
a660d684
KB
1276\membersection{::wxPostDelete}\label{wxpostdelete}
1277
1278\func{void}{wxPostDelete}{\param{wxObject *}{object}}
1279
954b8ae6 1280Tells the system to delete the specified object when
a660d684
KB
1281all other events have been processed. In some environments, it is
1282necessary to use this instead of deleting a frame directly with the
954b8ae6 1283delete operator, because some GUIs will still send events to a deleted window.
a660d684
KB
1284
1285Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
1286
954b8ae6
JS
1287\wxheading{Include files}
1288
1289<wx/utils.h>
1290
a660d684
KB
1291\membersection{::wxSetDisplayName}\label{wxsetdisplayname}
1292
1293\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
1294
1295Under X only, sets the current display name. This is the X host and display name such
1296as ``colonsay:0.0", and the function indicates which display should be used for creating
1297windows from this point on. Setting the display within an application allows multiple
1298displays to be used.
1299
1300See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
1301
954b8ae6
JS
1302\wxheading{Include files}
1303
1304<wx/utils.h>
1305
a660d684
KB
1306\membersection{::wxShell}\label{wxshell}
1307
1308\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
1309
1310Executes a command in an interactive shell window. If no command is
1311specified, then just the shell is spawned.
1312
1313See also \helpref{wxExecute}{wxexecute}.
1314
954b8ae6
JS
1315\wxheading{Include files}
1316
1317<wx/utils.h>
1318
e2a6f233 1319\membersection{::wxSleep}\label{wxsleep}
a660d684
KB
1320
1321\func{void}{wxSleep}{\param{int}{ secs}}
1322
e2a6f233 1323Sleeps for the specified number of seconds.
a660d684 1324
954b8ae6
JS
1325\wxheading{Include files}
1326
1327<wx/utils.h>
1328
a660d684
KB
1329\membersection{::wxStripMenuCodes}
1330
8a2c6ef8
JS
1331\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
1332
1333\func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}}
a660d684
KB
1334
1335Strips any menu codes from {\it in} and places the result
8a2c6ef8
JS
1336in {\it out} (or returns the new string, in the first form).
1337
1338Menu codes include \& (mark the next character with an underline
a660d684
KB
1339as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
1340
954b8ae6
JS
1341\wxheading{Include files}
1342
1343<wx/utils.h>
1344
a660d684
KB
1345\membersection{::wxStartTimer}\label{wxstarttimer}
1346
1347\func{void}{wxStartTimer}{\void}
1348
1349Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
1350
1351See also \helpref{wxTimer}{wxtimer}.
1352
954b8ae6
JS
1353\wxheading{Include files}
1354
1355<wx/timer.h>
1356
a660d684
KB
1357\membersection{::wxToLower}\label{wxtolower}
1358
1359\func{char}{wxToLower}{\param{char }{ch}}
1360
1361Converts the character to lower case. This is implemented as a macro for efficiency.
1362
954b8ae6
JS
1363\wxheading{Include files}
1364
1365<wx/utils.h>
1366
a660d684
KB
1367\membersection{::wxToUpper}\label{wxtoupper}
1368
1369\func{char}{wxToUpper}{\param{char }{ch}}
1370
1371Converts the character to upper case. This is implemented as a macro for efficiency.
1372
954b8ae6
JS
1373\wxheading{Include files}
1374
1375<wx/utils.h>
1376
a660d684
KB
1377\membersection{::wxTrace}\label{wxtrace}
1378
1379\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
1380
1381Takes printf-style variable argument syntax. Output
1382is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1383
6fb26ea3
JS
1384This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1385
954b8ae6
JS
1386\wxheading{Include files}
1387
1388<wx/memory.h>
1389
a660d684
KB
1390\membersection{::wxTraceLevel}\label{wxtracelevel}
1391
1392\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
1393
1394Takes printf-style variable argument syntax. Output
1395is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1396The first argument should be the level at which this information is appropriate.
1397It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
1398this value.
1399
6fb26ea3
JS
1400This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1401
954b8ae6
JS
1402\wxheading{Include files}
1403
1404<wx/memory.h>
1405
a660d684
KB
1406\membersection{::wxWriteResource}\label{wxwriteresource}
1407
1408\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1409 \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
1410
1411\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1412 \param{float }{value}, \param{const wxString\& }{file = NULL}}
1413
1414\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1415 \param{long }{value}, \param{const wxString\& }{file = NULL}}
1416
1417\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1418 \param{int }{value}, \param{const wxString\& }{file = NULL}}
1419
1420Writes a resource value into the resource database (for example, WIN.INI, or
1421.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1422otherwise the specified file is used.
1423
1424Under X, the resource databases are cached until the internal function
1425\rtfsp{\bf wxFlushResources} is called automatically on exit, when
1426all updated resource databases are written to their files.
1427
1428Note that it is considered bad manners to write to the .Xdefaults
e2a6f233 1429file under Unix, although the WIN.INI file is fair game under Windows.
a660d684 1430
e2a6f233 1431See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
a660d684 1432
954b8ae6
JS
1433\wxheading{Include files}
1434
1435<wx/utils.h>
1436
fd34e3a5 1437\membersection{::wxYield}\label{wxyield}
a660d684
KB
1438
1439\func{bool}{wxYield}{\void}
1440
1441Yields control to pending messages in the windowing system. This can be useful, for example, when a
1442time-consuming process writes to a text window. Without an occasional
1443yield, the text window will not be updated properly, and (since Windows
1444multitasking is cooperative) other processes will not respond.
1445
1446Caution should be exercised, however, since yielding may allow the
1447user to perform actions which are not compatible with the current task.
1448Disabling menu items or whole menus during processing can avoid unwanted
1449reentrance of code.
1450
954b8ae6
JS
1451\wxheading{Include files}
1452
1453<wx/utils.h>
1454
a660d684
KB
1455\section{Macros}\label{macros}
1456
1457These macros are defined in wxWindows.
1458
1459\membersection{CLASSINFO}\label{classinfo}
1460
1461\func{wxClassInfo *}{CLASSINFO}{className}
1462
1463Returns a pointer to the wxClassInfo object associated with this class.
1464
954b8ae6
JS
1465\wxheading{Include files}
1466
1467<wx/object.h>
1468
a660d684
KB
1469\membersection{WXDEBUG\_NEW}\label{debugnew}
1470
1471\func{}{WXDEBUG\_NEW}{arg}
1472
1473This is defined in debug mode to be call the redefined new operator
1474with filename and line number arguments. The definition is:
1475
1476\begin{verbatim}
1477#define WXDEBUG_NEW new(__FILE__,__LINE__)
1478\end{verbatim}
1479
1480In non-debug mode, this is defined as the normal new operator.
1481
954b8ae6
JS
1482\wxheading{Include files}
1483
1484<wx/object.h>
1485
a660d684
KB
1486\membersection{DECLARE\_ABSTRACT\_CLASS}
1487
1488\func{}{DECLARE\_ABSTRACT\_CLASS}{className}
1489
1490Used inside a class declaration to declare that the class should be
1491made known to the class hierarchy, but objects of this class cannot be created
1492dynamically. The same as DECLARE\_CLASS.
1493
1494Example:
1495
1496\begin{verbatim}
1497class wxCommand: public wxObject
1498{
1499 DECLARE_ABSTRACT_CLASS(wxCommand)
1500
1501 private:
1502 ...
1503 public:
1504 ...
1505};
1506\end{verbatim}
1507
954b8ae6
JS
1508\wxheading{Include files}
1509
1510<wx/object.h>
1511
a660d684
KB
1512\membersection{DECLARE\_APP}\label{declareapp}
1513
1514\func{}{DECLARE\_APP}{className}
1515
1516This is used in headers to create a forward declaration of the wxGetApp function implemented
1517by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}.
1518
1519Example:
1520
1521\begin{verbatim}
1522 DECLARE_APP(MyApp)
1523\end{verbatim}
1524
954b8ae6
JS
1525\wxheading{Include files}
1526
1527<wx/app.h>
1528
a660d684
KB
1529\membersection{DECLARE\_CLASS}
1530
1531\func{}{DECLARE\_CLASS}{className}
1532
1533Used inside a class declaration to declare that the class should be
1534made known to the class hierarchy, but objects of this class cannot be created
1535dynamically. The same as DECLARE\_ABSTRACT\_CLASS.
1536
954b8ae6
JS
1537\wxheading{Include files}
1538
1539<wx/object.h>
1540
a660d684
KB
1541\membersection{DECLARE\_DYNAMIC\_CLASS}
1542
1543\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
1544
1545Used inside a class declaration to declare that the objects of this class should be dynamically
1546createable from run-time type information.
1547
1548Example:
1549
1550\begin{verbatim}
1551class wxFrame: public wxWindow
1552{
1553 DECLARE_DYNAMIC_CLASS(wxFrame)
1554
1555 private:
1556 const wxString\& frameTitle;
1557 public:
1558 ...
1559};
1560\end{verbatim}
1561
954b8ae6
JS
1562\wxheading{Include files}
1563
1564<wx/object.h>
1565
a660d684
KB
1566\membersection{IMPLEMENT\_ABSTRACT\_CLASS}
1567
1568\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
1569
1570Used in a C++ implementation file to complete the declaration of
1571a class that has run-time type information. The same as IMPLEMENT\_CLASS.
1572
1573Example:
1574
1575\begin{verbatim}
1576IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
1577
1578wxCommand::wxCommand(void)
1579{
1580...
1581}
1582\end{verbatim}
1583
954b8ae6
JS
1584\wxheading{Include files}
1585
1586<wx/object.h>
1587
a660d684
KB
1588\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}
1589
1590\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
1591
1592Used in a C++ implementation file to complete the declaration of
1593a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
1594
954b8ae6
JS
1595\wxheading{Include files}
1596
1597<wx/object.h>
1598
a660d684
KB
1599\membersection{IMPLEMENT\_APP}\label{implementapp}
1600
1601\func{}{IMPLEMENT\_APP}{className}
1602
1603This is used in the application class implementation file to make the application class known to
1604wxWindows for dynamic construction. You use this instead of
1605
1606Old form:
1607
1608\begin{verbatim}
1609 MyApp myApp;
1610\end{verbatim}
1611
1612New form:
1613
1614\begin{verbatim}
1615 IMPLEMENT_APP(MyApp)
1616\end{verbatim}
1617
1618See also \helpref{DECLARE\_APP}{declareapp}.
1619
954b8ae6
JS
1620\wxheading{Include files}
1621
1622<wx/app.h>
1623
a660d684
KB
1624\membersection{IMPLEMENT\_CLASS}
1625
1626\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
1627
1628Used in a C++ implementation file to complete the declaration of
1629a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
1630
954b8ae6
JS
1631\wxheading{Include files}
1632
1633<wx/object.h>
1634
a660d684
KB
1635\membersection{IMPLEMENT\_CLASS2}
1636
1637\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
1638
1639Used in a C++ implementation file to complete the declaration of a
1640class that has run-time type information and two base classes. The
1641same as IMPLEMENT\_ABSTRACT\_CLASS2.
1642
954b8ae6
JS
1643\wxheading{Include files}
1644
1645<wx/object.h>
1646
a660d684
KB
1647\membersection{IMPLEMENT\_DYNAMIC\_CLASS}
1648
1649\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
1650
1651Used in a C++ implementation file to complete the declaration of
1652a class that has run-time type information, and whose instances
1653can be created dynamically.
1654
1655Example:
1656
1657\begin{verbatim}
1658IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
1659
1660wxFrame::wxFrame(void)
1661{
1662...
1663}
1664\end{verbatim}
1665
954b8ae6
JS
1666\wxheading{Include files}
1667
1668<wx/object.h>
1669
a660d684
KB
1670\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}
1671
1672\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
1673
1674Used in a C++ implementation file to complete the declaration of
1675a class that has run-time type information, and whose instances
1676can be created dynamically. Use this for classes derived from two
1677base classes.
1678
954b8ae6
JS
1679\wxheading{Include files}
1680
1681<wx/object.h>
1682
a660d684
KB
1683\membersection{WXTRACE}\label{trace}
1684
1685\func{}{WXTRACE}{formatString, ...}
1686
1687Calls wxTrace with printf-style variable argument syntax. Output
1688is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1689
6fb26ea3
JS
1690This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1691
954b8ae6
JS
1692\wxheading{Include files}
1693
1694<wx/memory.h>
1695
a660d684
KB
1696\membersection{WXTRACELEVEL}\label{tracelevel}
1697
1698\func{}{WXTRACELEVEL}{level, formatString, ...}
1699
1700Calls wxTraceLevel with printf-style variable argument syntax. Output
1701is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1702The first argument should be the level at which this information is appropriate.
1703It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
1704this value.
1705
6fb26ea3
JS
1706This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1707
954b8ae6
JS
1708\wxheading{Include files}
1709
1710<wx/memory.h>
1711
a660d684
KB
1712\section{wxWindows resource functions}\label{resourcefuncs}
1713
1714\overview{wxWindows resource system}{resourceformats}
1715
1716This section details functions for manipulating wxWindows (.WXR) resource
1717files and loading user interface elements from resources.
1718
1719\normalbox{Please note that this use of the word `resource' is different from that used when talking
1720about initialisation file resource reading and writing, using such functions
1721as wxWriteResource and wxGetResource. It's just an unfortunate clash of terminology.}
1722
1723\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
1724
1725See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
1726loading from resource data.
1727
954b8ae6
JS
1728{\bf Warning:} this needs updating for wxWindows 2.
1729
a660d684
KB
1730\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
1731
1732\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
1733
1734Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
1735\verb$#$defining a name to an integer). Unlikely to be used by an application except
1736perhaps for implementing resource functionality for interpreted languages.
1737
1738\membersection{::wxResourceClear}
1739
1740\func{void}{wxResourceClear}{\void}
1741
1742Clears the wxWindows resource table.
1743
1744\membersection{::wxResourceCreateBitmap}
1745
1746\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
1747
1748Creates a new bitmap from a file, static data, or Windows resource, given a valid
1749wxWindows bitmap resource identifier. For example, if the .WXR file contains
1750the following:
1751
1752\begin{verbatim}
1753static const wxString\& aiai_resource = "bitmap(name = 'aiai_resource',\
1754 bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
1755 bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X']).";
1756\end{verbatim}
1757
1758then this function can be called as follows:
1759
1760\begin{verbatim}
1761 wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource");
1762\end{verbatim}
1763
1764\membersection{::wxResourceCreateIcon}
1765
1766\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
1767
1768Creates a new icon from a file, static data, or Windows resource, given a valid
1769wxWindows icon resource identifier. For example, if the .WXR file contains
1770the following:
1771
1772\begin{verbatim}
1773static const wxString\& aiai_resource = "icon(name = 'aiai_resource',\
1774 icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
1775 icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X']).";
1776\end{verbatim}
1777
1778then this function can be called as follows:
1779
1780\begin{verbatim}
1781 wxIcon *icon = wxResourceCreateIcon("aiai_resource");
1782\end{verbatim}
1783
1784\membersection{::wxResourceCreateMenuBar}
1785
1786\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
1787
1788Creates a new menu bar given a valid wxWindows menubar resource
1789identifier. For example, if the .WXR file contains the following:
1790
1791\begin{verbatim}
1792static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
1793 menu = \
1794 [\
1795 ['&File', 1, '', \
1796 ['&Open File', 2, 'Open a file'],\
1797 ['&Save File', 3, 'Save a file'],\
1798 [],\
1799 ['E&xit', 4, 'Exit program']\
1800 ],\
1801 ['&Help', 5, '', \
1802 ['&About', 6, 'About this program']\
1803 ]\
1804 ]).";
1805\end{verbatim}
1806
1807then this function can be called as follows:
1808
1809\begin{verbatim}
1810 wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
1811\end{verbatim}
1812
1813
1814\membersection{::wxResourceGetIdentifier}
1815
1816\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
1817
1818Used for retrieving the integer value associated with an identifier.
1819A zero value indicates that the identifier was not found.
1820
1821See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
1822
1823\membersection{::wxResourceParseData}\label{wxresourcedata}
1824
1825\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
1826
1827Parses a string containing one or more wxWindows resource objects. If
1828the resource objects are global static data that are included into the
1829C++ program, then this function must be called for each variable
1830containing the resource data, to make it known to wxWindows.
1831
1832{\it resource} should contain data in the following form:
1833
1834\begin{verbatim}
1835dialog(name = 'dialog1',
1836 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
1837 title = 'Test dialog box',
1838 x = 312, y = 234, width = 400, height = 300,
1839 modal = 0,
1840 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
1841 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
1842 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',
1843 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
1844 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
1845 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
1846\end{verbatim}
1847
1848This function will typically be used after including a {\tt .wxr} file into
1849a C++ program as follows:
1850
1851\begin{verbatim}
1852#include "dialog1.wxr"
1853\end{verbatim}
1854
1855Each of the contained resources will declare a new C++ variable, and each
1856of these variables should be passed to wxResourceParseData.
1857
1858\membersection{::wxResourceParseFile}
1859
1860\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
1861
1862Parses a file containing one or more wxWindows resource objects
1863in C++-compatible syntax. Use this function to dynamically load
1864wxWindows resource data.
1865
1866\membersection{::wxResourceParseString}\label{wxresourceparsestring}
1867
1868\func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
1869
1870Parses a string containing one or more wxWindows resource objects. If
1871the resource objects are global static data that are included into the
1872C++ program, then this function must be called for each variable
1873containing the resource data, to make it known to wxWindows.
1874
1875{\it resource} should contain data with the following form:
1876
1877\begin{verbatim}
1878static const wxString\& dialog1 = "dialog(name = 'dialog1',\
1879 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',\
1880 title = 'Test dialog box',\
1881 x = 312, y = 234, width = 400, height = 300,\
1882 modal = 0,\
1883 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,\
1884 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],\
1885 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',\
1886 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',\
1887 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
1888 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).";
1889\end{verbatim}
1890
1891This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
1892load an entire {\tt .wxr file} into a string.
1893
1894\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
1895
1896\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width},
1897\param{int }{height}, \param{wxResourceTable *}{table = NULL}}
1898
1899\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}}
1900
1901Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system.
1902This is required if other resources will use the bitmap data, since otherwise there
1903is no connection between names used in resources, and the global bitmap data.
1904
1905\membersection{::wxResourceRegisterIconData}
1906
1907Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
1908
6fb26ea3
JS
1909\section{Log functions}\label{logfunctions}
1910
1911These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
1912further information.
1913
954b8ae6
JS
1914\wxheading{Include files}
1915
1916<wx/log.h>
1917
6fb26ea3
JS
1918\membersection{::wxLogError}\label{wxlogerror}
1919
1920\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
1921
1922The function to use for error messages, i.e. the
1923messages that must be shown to the user. The default processing is to pop up a
1924message box to inform the user about it.
1925
1926\membersection{::wxLogFatalError}\label{wxlogfatalerror}
1927
1928\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}}
1929
1930Like \helpref{wxLogError}{wxlogerror}, but also
1931terminates the program with the exit code 3. Using {\it abort()} standard
1932function also terminates the program with this exit code.
1933
1934\membersection{::wxLogWarning}\label{wxlogwarning}
1935
1936\func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}}
1937
1938For warnings - they are also normally shown to the
1939user, but don't interrupt the program work.
1940
1941\membersection{::wxLogMessage}\label{wxlogmessage}
1942
1943\func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}}
1944
1945for all normal, informational messages. They also
1946appear in a message box by default (but it can be changed). Notice
1947that the standard behaviour is to not show informational messages if there are
1948any errors later - the logic being that the later error messages make the
1949informational messages preceding them meaningless.
1950
1951\membersection{::wxLogVerbose}\label{wxlogverbose}
1952
1953\func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}}
1954
1955For verbose output. Normally, it's suppressed, but
1956might be activated if the user wishes to know more details about the program
1957progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
1958
1959\membersection{::wxLogStatus}\label{wxlogstatus}
1960
1961\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}}
1962
1963For status messages - they will go into the status
1964bar of the active or specified (as the first argument) \helpref{wxFrame}{wxframe} if it has one.
1965
1966\membersection{::wxLogSysError}\label{wxlogsyserror}
1967
1968\func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}}
1969
1970Mostly used by wxWindows itself, but might be
1971handy for logging errors after system call (API function) failure. It logs the
1972specified message text as well as the last system error code ({\it errno} or {\it ::GetLastError()} depending
1973on the platform) and the corresponding error
1974message. The second form of this function takes the error code explitly as the
1975first argument.
1976
1977\membersection{::wxLogDebug}\label{wxlogdebug}
1978
1979\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}}
1980
1981The right function for debug output. It only
1982does anything at all in the debug mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined)
1983and expands to nothing in release mode (otherwise).
1984
1985\membersection{::wxLogTrace}\label{wxlogtrace}
1986
1987\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}}
1988
1989\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}}
1990
1991As {\bf wxLogDebug}, only does something in debug
1992build. The reason for making it a separate function from it is that usually
1993there are a lot of trace messages, so it might make sense to separate them
1994from other debug messages which would be flooded in them. Moreover, the second
1995version of this function takes a trace mask as the first argument which allows
1996to further restrict the amount of messages generated. The value of {\it mask} can be:
1997
1998\begin{itemize}\itemsep=0pt
1999\item wxTraceMemAlloc: trace memory allocation (new/delete)
2000\item wxTraceMessages: trace window messages/X callbacks
2001\item wxTraceResAlloc: trace GDI resource allocation
2002\item wxTraceRefCount: trace various ref counting operations
2003\end{itemize}
2004
2005\section{Debugging macros and functions}\label{debugmacros}
2006
2007Useful macros and functins for error checking and defensive programming. ASSERTs are only
2008compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
2009builds.
2010
954b8ae6
JS
2011\wxheading{Include files}
2012
2013<wx/debug.h>
2014
6fb26ea3
JS
2015\membersection{::wxOnAssert}\label{wxonassert}
2016
2017\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}}
2018
2019This function may be redefined to do something non trivial and is called
2020whenever one of debugging macros fails (i.e. condition is false in an
5b6aa0ff
JS
2021assertion).
2022% TODO: this should probably be an overridable in wxApp.
6fb26ea3
JS
2023
2024\membersection{wxASSERT}\label{wxassert}
2025
2026\func{}{wxASSERT}{\param{}{condition}}
2027
2028Assert macro. An error message will be generated if the condition is FALSE.
2029
2030\membersection{wxASSERT\_MSG}\label{wxassertmsg}
2031
2032\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
2033
2034Assert macro with message. An error message will be generated if the condition is FALSE.
2035
2036\membersection{wxFAIL}\label{wxfail}
2037
2038\func{}{wxFAIL}{\param{}{condition}}
2039
2040Will always generate an assert error if this code is reached (in debug mode).
2041
2042\membersection{wxFAIL\_MSG}\label{wxfailmsg}
2043
2044\func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}}
2045
2046Will always generate an assert error with specified message if this code is reached (in debug mode).
2047
2048\membersection{wxCHECK}\label{wxcheck}
2049
2050\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
2051
2052Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2053This check is done even in release mode.
2054
2055\membersection{wxCHECK\_MSG}\label{wxcheckmsg}
2056
2057\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
2058
2059Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2060This check is done even in release mode.
2061