1 \chapter{Functions
}\label{functions
}
2 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
3 \setfooter{\thepage}{}{}{}{}{\thepage}
5 The functions and macros defined in wxWidgets are described here: you can
6 either look up a function using the alphabetical listing of them or find it in
7 the corresponding topic.
9 \section{Alphabetical functions and macros list
}\label{functionsalphabetically
}
11 \helpref{CLASSINFO
}{classinfo
}\\
12 \helpref{copystring
}{copystring
}\\
13 \helpref{DECLARE
\_ABSTRACT\_CLASS}{declareabstractclass
}\\
14 \helpref{DECLARE
\_APP}{declareapp
}\\
15 \helpref{DECLARE
\_CLASS}{declareclass
}\\
16 \helpref{DECLARE
\_DYNAMIC\_CLASS}{declaredynamicclass
}\\
17 \helpref{IMPLEMENT
\_ABSTRACT\_CLASS2}{implementabstractclass2
}\\
18 \helpref{IMPLEMENT
\_ABSTRACT\_CLASS}{implementabstractclass
}\\
19 \helpref{IMPLEMENT
\_APP}{implementapp
}\\
20 \helpref{IMPLEMENT
\_CLASS2}{implementclass2
}\\
21 \helpref{IMPLEMENT
\_CLASS}{implementclass
}\\
22 \helpref{IMPLEMENT
\_DYNAMIC\_CLASS2}{implementdynamicclass2
}\\
23 \helpref{IMPLEMENT
\_DYNAMIC\_CLASS}{implementdynamicclass
}\\
24 \helpref{wxCONCAT
}{wxconcat
}\\
25 \helpref{WXDEBUG
\_NEW}{debugnew
}\\
26 \helpref{WXTRACELEVEL
}{tracelevel
}\\
27 \helpref{WXTRACE
}{trace
}\\
28 \helpref{wxASSERT
\_MIN\_BITSIZE}{wxassertminbitsize
}\\
29 \helpref{wxASSERT
\_MSG}{wxassertmsg
}\\
30 \helpref{wxASSERT
}{wxassert
}\\
31 \helpref{wxBITMAP
}{wxbitmapmacro
}\\
32 \helpref{wxBeginBusyCursor
}{wxbeginbusycursor
}\\
33 \helpref{wxBell
}{wxbell
}\\
34 \helpref{wxCHANGE
\_UMASK}{wxchangeumask
}\\
35 \helpref{wxCHECK
}{wxcheck
}\\
36 \helpref{wxCHECK2
\_MSG}{wxcheck2msg
}\\
37 \helpref{wxCHECK2
}{wxcheck2
}\\
38 \helpref{wxCHECK
\_GCC\_VERSION}{wxcheckgccversion
}\\
39 \helpref{wxCHECK
\_MSG}{wxcheckmsg
}\\
40 \helpref{wxCHECK
\_RET}{wxcheckret
}\\
41 \helpref{wxCHECK
\_VERSION}{wxcheckversion
}\\
42 \helpref{wxCHECK
\_VERSION\_FULL}{wxcheckversionfull
}\\
43 \helpref{wxCHECK
\_W32API\_VERSION}{wxcheckw32apiversion
}\\
44 \helpref{wxClientDisplayRect
}{wxclientdisplayrect
}\\
45 \helpref{wxClipboardOpen
}{functionwxclipboardopen
}\\
46 \helpref{wxCloseClipboard
}{wxcloseclipboard
}\\
47 \helpref{wxColourDisplay
}{wxcolourdisplay
}\\
48 \helpref{wxCOMPILE
\_TIME\_ASSERT}{wxcompiletimeassert
}\\
49 \helpref{wxCOMPILE
\_TIME\_ASSERT2}{wxcompiletimeassert2
}\\
50 \helpref{wxConcatFiles
}{wxconcatfiles
}\\
51 \helpref{wxConstCast
}{wxconstcast
}\\
52 \helpref{wxCopyFile
}{wxcopyfile
}\\
53 \helpref{wxCreateDynamicObject
}{wxcreatedynamicobject
}\\
54 \helpref{wxCreateFileTipProvider
}{wxcreatefiletipprovider
}\\
55 \helpref{wxCRIT
\_SECT\_DECLARE}{wxcritsectdeclare
}\\
56 \helpref{wxCRIT
\_SECT\_DECLARE\_MEMBER}{wxcritsectdeclaremember
}\\
57 \helpref{wxCRIT
\_SECT\_LOCKER}{wxcritsectlocker
}\\
58 \helpref{wxCRITICAL
\_SECTION}{wxcriticalsectionmacro
}\\
% wxcs already taken!
59 \helpref{wxDDECleanUp
}{wxddecleanup
}\\
60 \helpref{wxDDEInitialize
}{wxddeinitialize
}\\
61 \helpref{wxDROP
\_ICON}{wxdropicon
}\\
62 \helpref{wxDebugMsg
}{wxdebugmsg
}\\
63 \helpref{wxDirSelector
}{wxdirselector
}\\
64 \helpref{wxDisplayDepth
}{wxdisplaydepth
}\\
65 \helpref{wxDisplaySize
}{wxdisplaysize
}\\
66 \helpref{wxDisplaySizeMM
}{wxdisplaysizemm
}\\
67 \helpref{wxDos2UnixFilename
}{wxdos2unixfilename
}\\
68 \helpref{wxDynamicCastThis
}{wxdynamiccastthis
}\\
69 \helpref{wxDynamicCast
}{wxdynamiccast
}\\
70 \helpref{wxDYNLIB
\_FUNCTION}{wxdynlibfunction
}\\
71 \helpref{wxEmptyClipboard
}{wxemptyclipboard
}\\
72 \helpref{wxEnableTopLevelWindows
}{wxenabletoplevelwindows
}\\
73 \helpref{wxEndBusyCursor
}{wxendbusycursor
}\\
74 \helpref{wxENTER
\_CRIT\_SECT}{wxentercritsect
}\\
75 \helpref{wxEntry
}{wxentry
}\\
76 \helpref{wxEnumClipboardFormats
}{wxenumclipboardformats
}\\
77 \helpref{wxError
}{wxerror
}\\
78 \helpref{wxExecute
}{wxexecute
}\\
79 \helpref{wxExit
}{wxexit
}\\
80 \helpref{wxEXPLICIT
}{wxexplicit
}\\
81 \helpref{wxFAIL
\_MSG}{wxfailmsg
}\\
82 \helpref{wxFAIL
}{wxfail
}\\
83 \helpref{wxFatalError
}{wxfatalerror
}\\
84 \helpref{wxFileExists
}{functionwxfileexists
}\\
85 \helpref{wxFileModificationTime
}{wxfilemodificationtime
}\\
86 \helpref{wxFileNameFromPath
}{wxfilenamefrompath
}\\
87 \helpref{wxFileSelector
}{wxfileselector
}\\
88 \helpref{wxFindFirstFile
}{wxfindfirstfile
}\\
89 \helpref{wxFindMenuItemId
}{wxfindmenuitemid
}\\
90 \helpref{wxFindNextFile
}{wxfindnextfile
}\\
91 \helpref{wxFindWindowAtPointer
}{wxfindwindowatpointer
}\\
92 \helpref{wxFindWindowAtPoint
}{wxfindwindowatpoint
}\\
93 \helpref{wxFindWindowByLabel
}{wxfindwindowbylabel
}\\
94 \helpref{wxFindWindowByName
}{wxfindwindowbyname
}\\
95 \helpref{wxFinite
}{wxfinite
}\\
96 \helpref{wxGetActiveWindow
}{wxgetactivewindow
}\\
97 \helpref{wxGetApp
}{wxgetapp
}\\
98 \helpref{wxGetBatteryState
}{wxgetbatterystate
}\\
99 \helpref{wxGetClipboardData
}{wxgetclipboarddata
}\\
100 \helpref{wxGetClipboardFormatName
}{wxgetclipboardformatname
}\\
101 \helpref{wxGetColourFromUser
}{wxgetcolourfromuser
}\\
102 \helpref{wxGetCwd
}{wxgetcwd
}\\
103 \helpref{wxGetDiskSpace
}{wxgetdiskspace
}\\
104 \helpref{wxGetDisplayName
}{wxgetdisplayname
}\\
105 \helpref{wxGetDisplaySize
}{wxdisplaysize
}\\
106 \helpref{wxGetDisplaySizeMM
}{wxdisplaysizemm
}\\
107 \helpref{wxGetElapsedTime
}{wxgetelapsedtime
}\\
108 \helpref{wxGetEmailAddress
}{wxgetemailaddress
}\\
109 \helpref{wxGetEnv
}{wxgetenv
}\\
110 \helpref{wxGetFileKind
}{wxgetfilekind
}\\
111 \helpref{wxGetFontFromUser
}{wxgetfontfromuser
}\\
112 \helpref{wxGetFreeMemory
}{wxgetfreememory
}\\
113 \helpref{wxGetFullHostName
}{wxgetfullhostname
}\\
114 \helpref{wxGetHomeDir
}{wxgethomedir
}\\
115 \helpref{wxGetHostName
}{wxgethostname
}\\
116 \helpref{wxGetKeyState
}{wxgetkeystate
}\\
117 \helpref{wxGetLocalTimeMillis
}{wxgetlocaltimemillis
}\\
118 \helpref{wxGetLocalTime
}{wxgetlocaltime
}\\
119 \helpref{wxGetMousePosition
}{wxgetmouseposition
}\\
120 \helpref{wxGetMultipleChoices
}{wxgetmultiplechoices
}\\
121 \helpref{wxGetMultipleChoice
}{wxgetmultiplechoice
}\\
122 \helpref{wxGetNumberFromUser
}{wxgetnumberfromuser
}\\
123 \helpref{wxGetOSDirectory
}{wxgetosdirectory
}\\
124 \helpref{wxGetOsDescription
}{wxgetosdescription
}\\
125 \helpref{wxGetOsVersion
}{wxgetosversion
}\\
126 \helpref{wxGetPasswordFromUser
}{wxgetpasswordfromuser
}\\
127 \helpref{wxGetPowerType
}{wxgetpowertype
}\\
128 \helpref{wxGetPrinterCommand
}{wxgetprintercommand
}\\
129 \helpref{wxGetPrinterFile
}{wxgetprinterfile
}\\
130 \helpref{wxGetPrinterMode
}{wxgetprintermode
}\\
131 \helpref{wxGetPrinterOptions
}{wxgetprinteroptions
}\\
132 \helpref{wxGetPrinterOrientation
}{wxgetprinterorientation
}\\
133 \helpref{wxGetPrinterPreviewCommand
}{wxgetprinterpreviewcommand
}\\
134 \helpref{wxGetPrinterScaling
}{wxgetprinterscaling
}\\
135 \helpref{wxGetPrinterTranslation
}{wxgetprintertranslation
}\\
136 \helpref{wxGetProcessId
}{wxgetprocessid
}\\
137 \helpref{wxGetResource
}{wxgetresource
}\\
138 \helpref{wxGetSingleChoiceData
}{wxgetsinglechoicedata
}\\
139 \helpref{wxGetSingleChoiceIndex
}{wxgetsinglechoiceindex
}\\
140 \helpref{wxGetSingleChoice
}{wxgetsinglechoice
}\\
141 \helpref{wxGetTempFileName
}{wxgettempfilename
}\\
142 \helpref{wxGetTextFromUser
}{wxgettextfromuser
}\\
143 \helpref{wxGetTopLevelParent
}{wxgettoplevelparent
}\\
144 \helpref{wxGetTranslation
}{wxgettranslation
}\\
145 \helpref{wxGetUTCTime
}{wxgetutctime
}\\
146 \helpref{wxGetUserHome
}{wxgetuserhome
}\\
147 \helpref{wxGetUserId
}{wxgetuserid
}\\
148 \helpref{wxGetUserName
}{wxgetusername
}\\
149 \helpref{wxGetWorkingDirectory
}{wxgetworkingdirectory
}\\
150 \helpref{wxGetenv
}{wxgetenvmacro
}\\
151 \helpref{wxHandleFatalExceptions
}{wxhandlefatalexceptions
}\\
152 \helpref{wxICON
}{wxiconmacro
}\\
153 \helpref{wxINTXX
\_SWAP\_ALWAYS}{intswapalways
}\\
154 \helpref{wxINTXX
\_SWAP\_ON\_BE}{intswaponbe
}\\
155 \helpref{wxINTXX
\_SWAP\_ON\_LE}{intswaponle
}\\
156 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}\\
157 \helpref{wxInitialize
}{wxinitialize
}\\
158 \helpref{wxIsAbsolutePath
}{wxisabsolutepath
}\\
159 \helpref{wxIsBusy
}{wxisbusy
}\\
160 \helpref{wxIsClipboardFormatAvailable
}{wxisclipboardformatavailable
}\\
161 \helpref{wxIsDebuggerRunning
}{wxisdebuggerrunning
}\\
162 \helpref{wxIsEmpty
}{wxisempty
}\\
163 \helpref{wxIsMainThread
}{wxismainthread
}\\
164 \helpref{wxIsNaN
}{wxisnan
}\\
165 \helpref{wxIsWild
}{wxiswild
}\\
166 \helpref{wxKill
}{wxkill
}\\
167 \helpref{wxLaunchDefaultBrowser
}{wxlaunchdefaultbrowser
}\\
168 \helpref{wxLEAVE
\_CRIT\_SECT}{wxleavecritsect
}\\
169 \helpref{wxLoadUserResource
}{wxloaduserresource
}\\
170 \helpref{wxLogDebug
}{wxlogdebug
}\\
171 \helpref{wxLogError
}{wxlogerror
}\\
172 \helpref{wxLogFatalError
}{wxlogfatalerror
}\\
173 \helpref{wxLogMessage
}{wxlogmessage
}\\
174 \helpref{wxLogStatus
}{wxlogstatus
}\\
175 \helpref{wxLogSysError
}{wxlogsyserror
}\\
176 \helpref{wxLogTrace
}{wxlogtrace
}\\
177 \helpref{wxLogVerbose
}{wxlogverbose
}\\
178 \helpref{wxLogWarning
}{wxlogwarning
}\\
179 \helpref{wxLL
}{wxll
}\\
180 \helpref{wxLongLongFmtSpec
}{wxlonglongfmtspec
}\\
181 \helpref{wxMakeMetafilePlaceable
}{wxmakemetafileplaceable
}\\
182 \helpref{wxMatchWild
}{wxmatchwild
}\\
183 \helpref{wxMessageBox
}{wxmessagebox
}\\
184 \helpref{wxMilliSleep
}{wxmillisleep
}\\
185 \helpref{wxMicroSleep
}{wxmicrosleep
}\\
186 \helpref{wxMkdir
}{wxmkdir
}\\
187 \helpref{wxMutexGuiEnter
}{wxmutexguienter
}\\
188 \helpref{wxMutexGuiLeave
}{wxmutexguileave
}\\
189 \helpref{wxNewId
}{wxnewid
}\\
190 \helpref{wxNow
}{wxnow
}\\
191 \helpref{wxOnAssert
}{wxonassert
}\\
192 \helpref{wxON
\_BLOCK\_EXIT}{wxonblockexit
}\\
193 \helpref{wxON
\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj
}\\
194 \helpref{wxOpenClipboard
}{wxopenclipboard
}\\
195 \helpref{wxParseCommonDialogsFilter
}{wxparsecommondialogsfilter
}\\
196 \helpref{wxDirExists
}{functionwxdirexists
}\\
197 \helpref{wxPathOnly
}{wxpathonly
}\\
198 \helpref{wxPostDelete
}{wxpostdelete
}\\
199 \helpref{wxPostEvent
}{wxpostevent
}\\
200 \helpref{wxRegisterClipboardFormat
}{wxregisterclipboardformat
}\\
201 \helpref{wxRegisterId
}{wxregisterid
}\\
202 \helpref{wxRemoveFile
}{wxremovefile
}\\
203 \helpref{wxRenameFile
}{wxrenamefile
}\\
204 \helpref{wxRmdir
}{wxrmdir
}\\
205 \helpref{wxSafeShowMessage
}{wxsafeshowmessage
}\\
206 \helpref{wxSafeYield
}{wxsafeyield
}\\
207 \helpref{wxSetClipboardData
}{wxsetclipboarddata
}\\
208 \helpref{wxSetCursor
}{wxsetcursor
}\\
209 \helpref{wxSetDisplayName
}{wxsetdisplayname
}\\
210 \helpref{wxSetEnv
}{wxsetenv
}\\
211 \helpref{wxSetPrinterCommand
}{wxsetprintercommand
}\\
212 \helpref{wxSetPrinterFile
}{wxsetprinterfile
}\\
213 \helpref{wxSetPrinterMode
}{wxsetprintermode
}\\
214 \helpref{wxSetPrinterOptions
}{wxsetprinteroptions
}\\
215 \helpref{wxSetPrinterOrientation
}{wxsetprinterorientation
}\\
216 \helpref{wxSetPrinterPreviewCommand
}{wxsetprinterpreviewcommand
}\\
217 \helpref{wxSetPrinterScaling
}{wxsetprinterscaling
}\\
218 \helpref{wxSetPrinterTranslation
}{wxsetprintertranslation
}\\
219 \helpref{wxSetWorkingDirectory
}{wxsetworkingdirectory
}\\
220 \helpref{wxShell
}{wxshell
}\\
221 \helpref{wxShowTip
}{wxshowtip
}\\
222 \helpref{wxShutdown
}{wxshutdown
}\\
223 \helpref{wxSleep
}{wxsleep
}\\
224 \helpref{wxSnprintf
}{wxsnprintf
}\\
225 \helpref{wxSplitPath
}{wxsplitfunction
}\\
226 \helpref{wxStartTimer
}{wxstarttimer
}\\
227 \helpref{wxStaticCast
}{wxstaticcast
}\\
228 \helpref{wxStrcmp
}{wxstrcmp
}\\
229 \helpref{wxStricmp
}{wxstricmp
}\\
230 \helpref{wxStringEq
}{wxstringeq
}\\
231 \helpref{wxStringMatch
}{wxstringmatch
}\\
232 \helpref{wxStripMenuCodes
}{wxstripmenucodes
}\\
233 \helpref{wxStrlen
}{wxstrlen
}\\
234 \helpref{wxSysErrorCode
}{wxsyserrorcode
}\\
235 \helpref{wxSysErrorMsg
}{wxsyserrormsg
}\\
237 \helpref{wxTraceLevel
}{wxtracelevel
}\\
238 \helpref{wxTrace
}{wxtrace
}\\
239 \helpref{wxTransferFileToStream
}{wxtransferfiletostream
}\\
240 \helpref{wxTransferStreamToFile
}{wxtransferstreamtofile
}\\
241 \helpref{wxTrap
}{wxtrap
}\\
242 \helpref{wxULL
}{wxull
}\\
243 \helpref{wxUninitialize
}{wxuninitialize
}\\
244 \helpref{wxUnix2DosFilename
}{wxunix2dosfilename
}\\
245 \helpref{wxUnsetEnv
}{wxunsetenv
}\\
246 \helpref{wxUsleep
}{wxusleep
}\\
247 \helpref{wxVaCopy
}{wxvacopy
}\\
248 \helpref{wxVsnprintf
}{wxvsnprintf
}\\
249 \helpref{wxWakeUpIdle
}{wxwakeupidle
}\\
250 \helpref{wxWriteResource
}{wxwriteresource
}\\
251 \helpref{wxYield
}{wxyield
}\\
252 \helpref{wx
\_const\_cast}{wxconstcastraw
}\\
253 \helpref{wx
\_reinterpret\_cast}{wxreinterpretcastraw
}\\
254 \helpref{wx
\_static\_cast}{wxstaticcastraw
}\\
255 \helpref{\_}{underscore
}\\
256 \helpref{wxPLURAL
}{wxplural
}\\
257 \helpref{\_T}{underscoret
}
261 \section{Version macros
}\label{versionfunctions
}
263 The following constants are defined in wxWidgets:
265 \begin{itemize
}\itemsep=
0pt
266 \item {\tt wxMAJOR
\_VERSION} is the major version of wxWidgets
267 \item {\tt wxMINOR
\_VERSION} is the minor version of wxWidgets
268 \item {\tt wxRELEASE
\_NUMBER} is the release number
269 \item {\tt wxSUBRELEASE
\_NUMBER} is the subrelease number which is $
0$ for all
273 For example, the values or these constants for wxWidgets
2.1.15 are
2,
1 and
276 Additionally,
{\tt wxVERSION
\_STRING} is a user-readable string containing
277 the full wxWidgets version and
{\tt wxVERSION
\_NUMBER} is a combination of the
278 three version numbers above: for
2.1.15, it is
2115 and it is
2200 for
281 The subrelease number is only used for the sources in between official releases
282 and so normally is not useful.
284 \wxheading{Include files
}
286 <wx/version.h> or <wx/defs.h>
289 \membersection{wxCHECK
\_GCC\_VERSION}\label{wxcheckgccversion
}
291 \func{bool
}{wxCHECK
\_GCC\_VERSION}{\param{}{major, minor, release
}}
293 Returns $
1$ if the compiler being used to compile the code is GNU C++
294 compiler (g++) version major.minor.release or greater. Otherwise, and also if
295 the compiler is not GNU C++ at all, returns $
0$.
298 \membersection{wxCHECK
\_VERSION}\label{wxcheckversion
}
300 \func{bool
}{wxCHECK
\_VERSION}{\param{}{major, minor, release
}}
302 This is a macro which evaluates to true if the current wxWidgets version is at
303 least major.minor.release.
305 For example, to test if the program is compiled with wxWidgets
2.2 or higher,
306 the following can be done:
310 #if wxCHECK_VERSION(
2,
2,
0)
311 if ( s.StartsWith("foo") )
312 #else // replacement code for old version
313 if ( strncmp(s, "foo",
3) ==
0 )
321 \membersection{wxCHECK
\_VERSION\_FULL}\label{wxcheckversionfull
}
323 \func{bool
}{wxCHECK
\_VERSION\_FULL}{\param{}{major, minor, release, subrel
}}
325 Same as
\helpref{wxCHECK
\_VERSION}{wxcheckversion
} but also checks that
326 \texttt{wxSUBRELEASE
\_NUMBER} is at least
\arg{subrel
}.
329 \membersection{wxCHECK
\_W32API\_VERSION}\label{wxcheckw32apiversion
}
331 \func{bool
}{wxCHECK
\_GCC\_VERSION}{\param{}{major, minor, release
}}
333 Returns $
1$ if the version of w32api headers used is major.minor.release or
334 greater. Otherwise, and also if we are not compiling with mingw32/cygwin under
335 Win32 at all, returns $
0$.
339 \section{Application initialization and termination
}\label{appinifunctions
}
341 The functions in this section are used on application startup/shutdown and also
342 to control the behaviour of the main event loop of the GUI programs.
345 \membersection{::wxEntry
}\label{wxentry
}
347 This initializes wxWidgets in a platform-dependent way. Use this if you
348 are not using the default wxWidgets entry code (e.g. main or WinMain). For example,
349 you can initialize wxWidgets from an Microsoft Foundation Classes application using
352 \func{void
}{wxEntry
}{\param{HANDLE
}{ hInstance
},
\param{HANDLE
}{ hPrevInstance
},
353 \param{const wxString\&
}{commandLine
},
\param{int
}{ cmdShow
},
\param{bool
}{ enterLoop = true
}}
355 wxWidgets initialization under Windows (non-DLL). If
{\it enterLoop
} is false, the
356 function will return immediately after calling wxApp::OnInit. Otherwise, the wxWidgets
357 message loop will be entered.
359 \func{void
}{wxEntry
}{\param{HANDLE
}{ hInstance
},
\param{HANDLE
}{ hPrevInstance
},
360 \param{WORD
}{ wDataSegment
},
\param{WORD
}{ wHeapSize
},
\param{const wxString\&
}{ commandLine
}}
362 wxWidgets initialization under Windows (for applications constructed as a DLL).
364 \func{int
}{wxEntry
}{\param{int
}{ argc
},
\param{const wxString\& *
}{argv
}}
366 wxWidgets initialization under Unix.
370 To clean up wxWidgets, call wxApp::OnExit followed by the static function
371 wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWidgets:
374 int CTheApp::ExitInstance()
376 // OnExit isn't called by CleanUp so must be called explicitly.
380 return CWinApp::ExitInstance();
384 \wxheading{Include files
}
390 \membersection{::wxGetApp
}\label{wxgetapp
}
392 \func{wxAppDerivedClass\&
}{wxGetApp
}{\void}
394 This function doesn't exist in wxWidgets but it is created by using
395 the
\helpref{IMPLEMENT
\_APP}{implementapp
} macro. Thus, before using it
396 anywhere but in the same module where this macro is used, you must make it
397 available using
\helpref{DECLARE
\_APP}{declareapp
}.
399 The advantage of using this function compared to directly using the global
400 wxTheApp pointer is that the latter is of type
{\tt wxApp *
} and so wouldn't
401 allow you to access the functions specific to your application class but not
402 present in wxApp while wxGetApp() returns the object of the right type.
405 \membersection{::wxHandleFatalExceptions
}\label{wxhandlefatalexceptions
}
407 \func{bool
}{wxHandleFatalExceptions
}{\param{bool
}{ doIt = true
}}
409 If
{\it doIt
} is true, the fatal exceptions (also known as general protection
410 faults under Windows or segmentation violations in the Unix world) will be
411 caught and passed to
\helpref{wxApp::OnFatalException
}{wxapponfatalexception
}.
412 By default, i.e. before this function is called, they will be handled in the
413 normal way which usually just means that the application will be terminated.
414 Calling wxHandleFatalExceptions() with
{\it doIt
} equal to false will restore
415 this default behaviour.
418 \membersection{::wxInitAllImageHandlers
}\label{wxinitallimagehandlers
}
420 \func{void
}{wxInitAllImageHandlers
}{\void}
422 Initializes all available image handlers. For a list of available handlers,
423 see
\helpref{wxImage
}{wximage
}.
427 \helpref{wxImage
}{wximage
},
\helpref{wxImageHandler
}{wximagehandler
}
429 \wxheading{Include files
}
434 \membersection{::wxInitialize
}\label{wxinitialize
}
436 \func{bool
}{wxInitialize
}{\void}
438 This function is used in wxBase only and only if you don't create
439 \helpref{wxApp
}{wxapp
} object at all. In this case you must call it from your
440 {\tt main()
} function before calling any other wxWidgets functions.
442 If the function returns
\false the initialization could not be performed,
443 in this case the library cannot be used and
444 \helpref{wxUninitialize
}{wxuninitialize
} shouldn't be called neither.
446 This function may be called several times but
447 \helpref{wxUninitialize
}{wxuninitialize
} must be called for each successful
448 call to this function.
450 \wxheading{Include files
}
455 \membersection{::wxSafeYield
}\label{wxsafeyield
}
457 \func{bool
}{wxSafeYield
}{\param{wxWindow*
}{ win = NULL
},
\param{bool
}{
458 onlyIfNeeded = false
}}
460 This function is similar to wxYield, except that it disables the user input to
461 all program windows before calling wxYield and re-enables it again
462 afterwards. If
{\it win
} is not NULL, this window will remain enabled,
463 allowing the implementation of some limited user interaction.
465 Returns the result of the call to
\helpref{::wxYield
}{wxyield
}.
467 \wxheading{Include files
}
472 \membersection{::wxUninitialize
}\label{wxuninitialize
}
474 \func{void
}{wxUninitialize
}{\void}
476 This function is for use in console (wxBase) programs only. It must be called
477 once for each previous successful call to
\helpref{wxInitialize
}{wxinitialize
}.
479 \wxheading{Include files
}
484 \membersection{::wxYield
}\label{wxyield
}
486 \func{bool
}{wxYield
}{\void}
488 Calls
\helpref{wxApp::Yield
}{wxappyield
}.
490 This function is kept only for backwards compatibility. Please use
491 the
\helpref{wxApp::Yield
}{wxappyield
} method instead in any new code.
493 \wxheading{Include files
}
495 <wx/app.h> or <wx/utils.h>
498 \membersection{::wxWakeUpIdle
}\label{wxwakeupidle
}
500 \func{void
}{wxWakeUpIdle
}{\void}
502 This functions wakes up the (internal and platform dependent) idle system, i.e. it
503 will force the system to send an idle event even if the system currently
{\it is
}
504 idle and thus would not send any idle event until after some other event would get
505 sent. This is also useful for sending events between two threads and is used by
506 the corresponding functions
\helpref{::wxPostEvent
}{wxpostevent
} and
507 \helpref{wxEvtHandler::AddPendingEvent
}{wxevthandleraddpendingevent
}.
509 \wxheading{Include files
}
515 \section{Process control functions
}\label{processfunctions
}
517 The functions in this section are used to launch or terminate the other
521 \membersection{::wxExecute
}\label{wxexecute
}
523 \func{long
}{wxExecute
}{\param{const wxString\&
}{command
},
\param{int
}{sync = wxEXEC
\_ASYNC},
\param{wxProcess *
}{callback = NULL
}}
525 \perlnote{In wxPerl this function is called
\texttt{Wx::ExecuteCommand
}}
527 \func{long
}{wxExecute
}{\param{char **
}{argv
},
\param{int
}{flags = wxEXEC
\_ASYNC},
\param{wxProcess *
}{callback = NULL
}}
529 \perlnote{In wxPerl this function is called
\texttt{Wx::ExecuteArgs
}}
531 \func{long
}{wxExecute
}{\param{const wxString\&
}{command
},
\param{wxArrayString\&
}{output
},
\param{int
}{flags =
0}}
533 \perlnote{In wxPerl this function is called
\texttt{Wx::ExecuteStdout
} and it
534 only takes the
{\tt command
} argument,
535 and returns a
2-element list
{\tt ( status, output )
}, where
{\tt output
} is
538 \func{long
}{wxExecute
}{\param{const wxString\&
}{command
},
\param{wxArrayString\&
}{output
},
\param{wxArrayString\&
}{errors
},
\param{int
}{flags =
0}}
540 \perlnote{In wxPerl this function is called
\texttt{Wx::ExecuteStdoutStderr
}
541 and it only takes the
{\tt command
} argument,
542 and returns a
3-element list
{\tt ( status, output, errors )
}, where
543 {\tt output
} and
{\tt errors
} are array references.
}
545 Executes another program in Unix or Windows.
547 The first form takes a command string, such as
{\tt "emacs file.txt"
}.
549 The second form takes an array of values: a command, any number of
550 arguments, terminated by NULL.
552 The semantics of the third and fourth versions is different from the first two
553 and is described in more details below.
555 If
{\it flags
} parameter contains
{\tt wxEXEC
\_ASYNC} flag (the default), flow
556 of control immediately returns. If it contains
{\tt wxEXEC
\_SYNC}, the current
557 application waits until the other program has terminated.
559 In the case of synchronous execution, the return value is the exit code of
560 the process (which terminates by the moment the function returns) and will be
561 $-
1$ if the process couldn't be started and typically
0 if the process
562 terminated successfully. Also, while waiting for the process to
563 terminate, wxExecute will call
\helpref{wxYield
}{wxyield
}. Because of this, by
564 default this function disables all application windows to avoid unexpected
565 reentrancies which could result from the users interaction with the program
566 while the child process is running. If you are sure that it is safe to not
567 disable the program windows, you may pass
\texttt{wxEXEC
\_NODISABLE} flag to
568 prevent this automatic disabling from happening.
570 For asynchronous execution, however, the return value is the process id and
571 zero value indicates that the command could not be executed. As an added
572 complication, the return value of $-
1$ in this case indicates that we didn't
573 launch a new process, but connected to the running one (this can only happen in
574 case of using DDE under Windows for command execution). In particular, in this,
575 and only this, case the calling code will not get the notification about
578 If callback isn't NULL and if execution is asynchronous,
579 \helpref{wxProcess::OnTerminate
}{wxprocessonterminate
} will be called when
580 the process finishes. Specifying this parameter also allows you to redirect the
581 standard input and/or output of the process being launched by calling
582 \helpref{Redirect
}{wxprocessredirect
}. If the child process IO is redirected,
583 under Windows the process window is not shown by default (this avoids having to
584 flush an unnecessary console for the processes which don't create any windows
585 anyhow) but a
{\tt wxEXEC
\_NOHIDE} flag can be used to prevent this from
586 happening, i.e. with this flag the child process window will be shown normally.
588 Under Unix the flag
{\tt wxEXEC
\_MAKE\_GROUP\_LEADER} may be used to ensure
589 that the new process is a group leader (this will create a new session if
590 needed). Calling
\helpref{wxKill
}{wxkill
} passing wxKILL
\_CHILDREN will
591 will kill this process as well as all of its children (except those which have
592 started their own session).
594 Finally, you may use the third overloaded version of this function to execute
595 a process (always synchronously, the contents of
\arg{flags
} is or'd with
596 \texttt{wxEXEC
\_SYNC}) and capture its output in the array
\arg{output
}. The
597 fourth version adds the possibility to additionally capture the messages from
598 standard error output in the
\arg{errors
} array.
600 {\bf NB:
} Currently wxExecute() can only be used from the main thread, calling
601 this function from another thread will result in an assert failure in debug
602 build and won't work.
606 \helpref{wxShell
}{wxshell
},
\helpref{wxProcess
}{wxprocess
},
\helpref{Exec sample
}{sampleexec
}.
608 \wxheading{Parameters
}
610 \docparam{command
}{The command to execute and any parameters to pass to it as a
613 \docparam{argv
}{The command to execute should be the first element of this
614 array, any additional ones are the command parameters and the array must be
615 terminated with a NULL pointer.
}
617 \docparam{flags
}{Combination of bit masks
{\tt wxEXEC
\_ASYNC},
\rtfsp
618 {\tt wxEXEC
\_SYNC} and
{\tt wxEXEC
\_NOHIDE}}
620 \docparam{callback
}{An optional pointer to
\helpref{wxProcess
}{wxprocess
}}
622 \wxheading{Include files
}
627 \membersection{::wxExit
}\label{wxexit
}
629 \func{void
}{wxExit
}{\void}
631 Exits application after calling
\helpref{wxApp::OnExit
}{wxapponexit
}.
632 Should only be used in an emergency: normally the top-level frame
633 should be deleted (after deleting all other frames) to terminate the
634 application. See
\helpref{wxCloseEvent
}{wxcloseevent
} and
\helpref{wxApp
}{wxapp
}.
636 \wxheading{Include files
}
641 \membersection{::wxKill
}\label{wxkill
}
643 \func{int
}{wxKill
}{\param{long
}{ pid
},
\param{int
}{ sig = wxSIGTERM
},
\param{wxKillError
}{*rc = NULL
},
\param{int
}{flags =
0}}
645 Equivalent to the Unix kill function: send the given signal
{\it sig
} to the
646 process with PID
{\it pid
}. The valid signal values are
651 wxSIGNONE =
0, // verify if the process exists under Unix
660 wxSIGKILL, // forcefully kill, dangerous!
666 wxSIGTERM // terminate the process gently
670 {\tt wxSIGNONE
},
{\tt wxSIGKILL
} and
{\tt wxSIGTERM
} have the same meaning
671 under both Unix and Windows but all the other signals are equivalent to
672 {\tt wxSIGTERM
} under Windows.
674 Returns
0 on success, -
1 on failure. If
{\it rc
} parameter is not NULL, it will
675 be filled with an element of
{\tt wxKillError
} enum:
680 wxKILL_OK, // no error
681 wxKILL_BAD_SIGNAL, // no such signal
682 wxKILL_ACCESS_DENIED, // permission denied
683 wxKILL_NO_PROCESS, // no such process
684 wxKILL_ERROR // another, unspecified error
688 The
{\it flags
} parameter can be wxKILL
\_NOCHILDREN (the default),
689 or wxKILL
\_CHILDREN, in which case the child processes of this
690 process will be killed too. Note that under Unix, for wxKILL
\_CHILDREN
691 to work you should have created the process by passing wxEXEC
\_MAKE\_GROUP\_LEADER
696 \helpref{wxProcess::Kill
}{wxprocesskill
},
\rtfsp
697 \helpref{wxProcess::Exists
}{wxprocessexists
},
\rtfsp
698 \helpref{Exec sample
}{sampleexec
}
700 \wxheading{Include files
}
705 \membersection{::wxGetProcessId
}\label{wxgetprocessid
}
707 \func{unsigned long
}{wxGetProcessId
}{\void}
709 Returns the number uniquely identifying the current process in the system.
711 If an error occurs, $
0$ is returned.
713 \wxheading{Include files
}
718 \membersection{::wxShell
}\label{wxshell
}
720 \func{bool
}{wxShell
}{\param{const wxString\&
}{command = NULL
}}
722 Executes a command in an interactive shell window. If no command is
723 specified, then just the shell is spawned.
725 See also
\helpref{wxExecute
}{wxexecute
},
\helpref{Exec sample
}{sampleexec
}.
727 \wxheading{Include files
}
732 \membersection{::wxShutdown
}\label{wxshutdown
}
734 \func{bool
}{wxShutdown
}{\param{wxShutdownFlags
}{flags
}}
736 This function shuts down or reboots the computer depending on the value of the
737 {\it flags
}. Please notice that doing this requires the corresponding access
738 rights (superuser under Unix,
{\tt SE
\_SHUTDOWN} privelege under Windows NT)
739 and that this function is only implemented under Unix and Win32.
741 \wxheading{Parameters
}
743 \docparam{flags
}{Either
{\tt wxSHUTDOWN
\_POWEROFF} or
{\tt wxSHUTDOWN
\_REBOOT}}
747 \true on success,
\false if an error occurred.
749 \wxheading{Include files
}
755 \section{Thread functions
}\label{threadfunctions
}
757 The functions and macros here mainly exist to make it writing the code which
758 may be compiled in multi thread build (
{\tt wxUSE
\_THREADS} $=
1$) as well as
759 in single thread configuration (
{\tt wxUSE
\_THREADS} $=
0$).
761 For example, a static variable must be protected against simultaneous access by
762 multiple threads in the former configuration but in the latter the extra
763 overhead of using the critical section is not needed. To solve this problem,
764 the
\helpref{wxCRITICAL
\_SECTION}{wxcriticalsectionmacro
} macro may be used
765 to create and use the critical section only when needed.
767 \wxheading{Include files
}
773 \helpref{wxThread
}{wxthread
},
\helpref{wxMutex
}{wxmutex
},
\helpref{Multithreading overview
}{wxthreadoverview
}
777 \membersection{wxCRIT
\_SECT\_DECLARE}\label{wxcritsectdeclare
}
779 \func{}{wxCRIT
\_SECT\_DECLARE}{\param{}{cs
}}
781 This macro declares a (static) critical section object named
{\it cs
} if
782 {\tt wxUSE
\_THREADS} is $
1$ and does nothing if it is $
0$.
786 \membersection{wxCRIT
\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember
}
788 \func{}{wxCRIT
\_SECT\_DECLARE}{\param{}{cs
}}
790 This macro declares a critical section object named
{\it cs
} if
791 {\tt wxUSE
\_THREADS} is $
1$ and does nothing if it is $
0$. As it doesn't
792 include the
{\tt static
} keyword (unlike
793 \helpref{wxCRIT
\_SECT\_DECLARE}{wxcritsectdeclare
}), it can be used to declare
794 a class or struct member which explains its name.
798 \membersection{wxCRIT
\_SECT\_LOCKER}\label{wxcritsectlocker
}
800 \func{}{wxCRIT
\_SECT\_LOCKER}{\param{}{name
},
\param{}{cs
}}
802 This macro creates a
\helpref{critical section lock
}{wxcriticalsectionlocker
}
803 object named
{\it name
} and associated with the critical section
{\it cs
} if
804 {\tt wxUSE
\_THREADS} is $
1$ and does nothing if it is $
0$.
808 \membersection{wxCRITICAL
\_SECTION}\label{wxcriticalsectionmacro
}
810 \func{}{wxCRITICAL
\_SECTION}{\param{}{name
}}
812 This macro combines
\helpref{wxCRIT
\_SECT\_DECLARE}{wxcritsectdeclare
} and
813 \helpref{wxCRIT
\_SECT\_LOCKER}{wxcritsectlocker
}: it creates a static critical
814 section object and also the lock object associated with it. Because of this, it
815 can be only used inside a function, not at global scope. For example:
820 static int s_counter =
0;
822 wxCRITICAL_SECTION(counter);
828 (note that we suppose that the function is called the first time from the main
829 thread so that the critical section object is initialized correctly by the time
830 other threads start calling it, if this is not the case this approach can
831 {\bf not
} be used and the critical section must be made a global instead).
835 \membersection{wxENTER
\_CRIT\_SECT}\label{wxentercritsect
}
837 \func{}{wxENTER
\_CRIT\_SECT}{\param{wxCriticalSection\&
}{cs
}}
839 This macro is equivalent to
\helpref{cs.Enter()
}{wxcriticalsectionenter
} if
840 {\tt wxUSE
\_THREADS} is $
1$ and does nothing if it is $
0$.
844 \membersection{::wxIsMainThread
}\label{wxismainthread
}
846 \func{bool
}{wxIsMainThread
}{\void}
848 Returns
\true if this thread is the main one. Always returns
\true if
849 {\tt wxUSE
\_THREADS} is $
0$.
853 \membersection{wxLEAVE
\_CRIT\_SECT}\label{wxleavecritsect
}
855 \func{}{wxLEAVE
\_CRIT\_SECT}{\param{wxCriticalSection\&
}{cs
}}
857 This macro is equivalent to
\helpref{cs.Leave()
}{wxcriticalsectionleave
} if
858 {\tt wxUSE
\_THREADS} is $
1$ and does nothing if it is $
0$.
862 \membersection{::wxMutexGuiEnter
}\label{wxmutexguienter
}
864 \func{void
}{wxMutexGuiEnter
}{\void}
866 This function must be called when any thread other than the main GUI thread
867 wants to get access to the GUI library. This function will block the execution
868 of the calling thread until the main thread (or any other thread holding the
869 main GUI lock) leaves the GUI library and no other thread will enter the GUI
870 library until the calling thread calls
\helpref{::wxMutexGuiLeave()
}{wxmutexguileave
}.
872 Typically, these functions are used like this:
875 void MyThread::Foo(void)
877 // before doing any GUI calls we must ensure that this thread is the only
883 my_window->DrawSomething();
889 Note that under GTK, no creation of top-level windows is allowed in any
890 thread but the main one.
892 This function is only defined on platforms which support preemptive
896 \membersection{::wxMutexGuiLeave
}\label{wxmutexguileave
}
898 \func{void
}{wxMutexGuiLeave
}{\void}
900 See
\helpref{::wxMutexGuiEnter()
}{wxmutexguienter
}.
902 This function is only defined on platforms which support preemptive
907 \section{File functions
}\label{filefunctions
}
909 \wxheading{Include files
}
915 \helpref{wxPathList
}{wxpathlist
}\\
916 \helpref{wxDir
}{wxdir
}\\
917 \helpref{wxFile
}{wxfile
}\\
918 \helpref{wxFileName
}{wxfilename
}
921 \membersection{::wxDos2UnixFilename
}\label{wxdos2unixfilename
}
923 \func{void
}{wxDos2UnixFilename
}{\param{wxChar *
}{s
}}
925 Converts a DOS to a Unix filename by replacing backslashes with forward
929 \membersection{::wxFileExists
}\label{functionwxfileexists
}
931 \func{bool
}{wxFileExists
}{\param{const wxString\&
}{filename
}}
933 Returns true if the file exists and is a plain file.
936 \membersection{::wxFileModificationTime
}\label{wxfilemodificationtime
}
938 \func{time
\_t}{wxFileModificationTime
}{\param{const wxString\&
}{filename
}}
940 Returns time of last modification of given file.
943 \membersection{::wxFileNameFromPath
}\label{wxfilenamefrompath
}
945 \func{wxString
}{wxFileNameFromPath
}{\param{const wxString\&
}{path
}}
947 \func{char *
}{wxFileNameFromPath
}{\param{char *
}{path
}}
949 {\bf NB:
} This function is obsolete, please use
950 \helpref{wxFileName::SplitPath
}{wxfilenamesplitpath
} instead.
952 Returns the filename for a full path. The second form returns a pointer to
953 temporary storage that should not be deallocated.
956 \membersection{::wxFindFirstFile
}\label{wxfindfirstfile
}
958 \func{wxString
}{wxFindFirstFile
}{\param{const char *
}{spec
},
\param{int
}{ flags =
0}}
960 This function does directory searching; returns the first file
961 that matches the path
{\it spec
}, or the empty string. Use
\helpref{wxFindNextFile
}{wxfindnextfile
} to
962 get the next matching file. Neither will
report the current directory "." or the
963 parent directory "..".
967 As of wx
2.5.2, these functions are not thread-safe! (they use static variables). You probably want to use
\helpref{wxDir::GetFirst
}{wxdirgetfirst
} or
\helpref{wxDirTraverser
}{wxdirtraverser
} instead.
969 {\it spec
} may contain wildcards.
971 {\it flags
} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
976 wxString f = wxFindFirstFile("/home/project/*.*");
980 f = wxFindNextFile();
985 \membersection{::wxFindNextFile
}\label{wxfindnextfile
}
987 \func{wxString
}{wxFindNextFile
}{\void}
989 Returns the next file that matches the path passed to
\helpref{wxFindFirstFile
}{wxfindfirstfile
}.
991 See
\helpref{wxFindFirstFile
}{wxfindfirstfile
} for an example.
994 \membersection{::wxGetDiskSpace
}\label{wxgetdiskspace
}
996 \func{bool
}{wxGetDiskSpace
}{\param{const wxString\&
}{path
},
\param{wxLongLong
}{*total = NULL
},
\param{wxLongLong
}{*free = NULL
}}
998 This function returns the total number of bytes and number of free bytes on
999 the disk containing the directory
{\it path
} (it should exist). Both
1000 {\it total
} and
{\it free
} parameters may be
{\tt NULL
} if the corresponding
1001 information is not needed.
1005 \true on success,
\false if an error occurred (for example, the
1006 directory doesn't exist).
1008 \wxheading{Portability
}
1010 This function is implemented for Win32,
1011 Mac OS and generic Unix provided the system has
{\tt statfs()
} function.
1013 This function first appeared in wxWidgets
2.3.2.
1016 \membersection{::wxGetFileKind
}\label{wxgetfilekind
}
1018 \func{wxFileKind
}{wxGetFileKind
}{\param{int
}{fd
}}
1020 \func{wxFileKind
}{wxGetFileKind
}{\param{FILE *
}{fp
}}
1022 Returns the type of an open file. Possible return values are:
1027 wxFILE_KIND_UNKNOWN,
1028 wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets
1029 wxFILE_KIND_TERMINAL, // a tty
1030 wxFILE_KIND_PIPE // a pipe
1035 \wxheading{Include files
}
1040 \membersection{::wxGetOSDirectory
}\label{wxgetosdirectory
}
1042 \func{wxString
}{wxGetOSDirectory
}{\void}
1044 Returns the Windows directory under Windows; on other platforms returns the empty string.
1047 \membersection{::wxIsAbsolutePath
}\label{wxisabsolutepath
}
1049 \func{bool
}{wxIsAbsolutePath
}{\param{const wxString\&
}{filename
}}
1051 Returns true if the argument is an absolute filename, i.e. with a slash
1052 or drive name at the beginning.
1055 \membersection{::wxDirExists
}\label{functionwxdirexists
}
1057 \func{bool
}{wxDirExists
}{\param{const wxString\&
}{dirname
}}
1059 Returns true if the path exists.
1062 \membersection{::wxPathOnly
}\label{wxpathonly
}
1064 \func{wxString
}{wxPathOnly
}{\param{const wxString\&
}{path
}}
1066 Returns the directory part of the filename.
1069 \membersection{::wxUnix2DosFilename
}\label{wxunix2dosfilename
}
1071 \func{void
}{wxUnix2DosFilename
}{\param{const wxString\&
}{s
}}
1073 Converts a Unix to a DOS filename by replacing forward
1074 slashes with backslashes.
1077 \membersection{wxCHANGE
\_UMASK}\label{wxchangeumask
}
1079 \func{}{wxCHANGE
\_UMASK}{\param{int
}{mask
}}
1081 Under Unix this macro changes the current process umask to the given value,
1082 unless it is equal to $-
1$ in which case nothing is done, and restores it to
1083 the original value on scope exit. It works by declaring a variable which sets
1084 umask to
\arg{mask
} in its constructor and restores it in its destructor.
1086 Under other platforms this macro expands to nothing.
1089 \membersection{::wxConcatFiles
}\label{wxconcatfiles
}
1091 \func{bool
}{wxConcatFiles
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
},
1092 \param{const wxString\&
}{file3
}}
1094 Concatenates
{\it file1
} and
{\it file2
} to
{\it file3
}, returning
1098 \membersection{::wxCopyFile
}\label{wxcopyfile
}
1100 \func{bool
}{wxCopyFile
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
},
\param{bool
}{overwrite = true
}}
1102 Copies
{\it file1
} to
{\it file2
}, returning true if successful. If
1103 {\it overwrite
} parameter is true (default), the destination file is overwritten
1104 if it exists, but if
{\it overwrite
} is false, the functions fails in this
1108 \membersection{::wxGetCwd
}\label{wxgetcwd
}
1110 \func{wxString
}{wxGetCwd
}{\void}
1112 Returns a string containing the current (or working) directory.
1115 \membersection{::wxGetWorkingDirectory
}\label{wxgetworkingdirectory
}
1117 \func{wxString
}{wxGetWorkingDirectory
}{\param{char *
}{buf=NULL
},
\param{int
}{sz=
1000}}
1119 {\bf NB:
} This function is obsolete: use
\helpref{wxGetCwd
}{wxgetcwd
} instead.
1121 Copies the current working directory into the buffer if supplied, or
1122 copies the working directory into new storage (which you
{\emph must
} delete
1123 yourself) if the buffer is NULL.
1125 {\it sz
} is the size of the buffer if supplied.
1128 \membersection{::wxGetTempFileName
}\label{wxgettempfilename
}
1130 \func{char *
}{wxGetTempFileName
}{\param{const wxString\&
}{prefix
},
\param{char *
}{buf=NULL
}}
1132 \func{bool
}{wxGetTempFileName
}{\param{const wxString\&
}{prefix
},
\param{wxString\&
}{buf
}}
1134 %% Makes a temporary filename based on {\it prefix}, opens and closes the file,
1135 %% and places the name in {\it buf}. If {\it buf} is NULL, new store
1136 %% is allocated for the temporary filename using {\it new}.
1138 %% Under Windows, the filename will include the drive and name of the
1139 %% directory allocated for temporary files (usually the contents of the
1140 %% TEMP variable). Under Unix, the {\tt /tmp} directory is used.
1142 %% It is the application's responsibility to create and delete the file.
1144 {\bf NB:
} These functions are obsolete, please use
\rtfsp
1145 \helpref{wxFileName::CreateTempFileName
}{wxfilenamecreatetempfilename
}\rtfsp
1149 \membersection{::wxIsWild
}\label{wxiswild
}
1151 \func{bool
}{wxIsWild
}{\param{const wxString\&
}{pattern
}}
1153 Returns true if the pattern contains wildcards. See
\helpref{wxMatchWild
}{wxmatchwild
}.
1156 \membersection{::wxMatchWild
}\label{wxmatchwild
}
1158 \func{bool
}{wxMatchWild
}{\param{const wxString\&
}{pattern
},
\param{const wxString\&
}{text
},
\param{bool
}{ dot
\_special}}
1160 Returns true if the
\arg{pattern
}\/ matches the
{\it text
}\/; if
{\it
1161 dot
\_special}\/ is true, filenames beginning with a dot are not matched
1162 with wildcard characters. See
\helpref{wxIsWild
}{wxiswild
}.
1165 \membersection{::wxMkdir
}\label{wxmkdir
}
1167 \func{bool
}{wxMkdir
}{\param{const wxString\&
}{dir
},
\param{int
}{perm =
0777}}
1169 Makes the directory
\arg{dir
}, returning true if successful.
1171 {\it perm
} is the access mask for the directory for the systems on which it is
1172 supported (Unix) and doesn't have effect for the other ones.
1175 \membersection{::wxParseCommonDialogsFilter
}\label{wxparsecommondialogsfilter
}
1177 \func{int
}{wxParseCommonDialogsFilter
}{\param{const wxString\&
}{wildCard
},
\param{wxArrayString\&
}{descriptions
},
\param{wxArrayString\&
}{filters
}}
1179 Parses the
\arg{wildCard
}, returning the number of filters.
1180 Returns
0 if none or if there's a problem.
1181 The arrays will contain an equal number of items found before the error.
1182 On platforms where native dialogs handle only one filter per entry,
1183 entries in arrays are automatically adjusted.
1184 \arg{wildCard
} is in the form:
1186 "All files
(*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
1189 \membersection{::wxRemoveFile}\label{wxremovefile}
1191 \func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
1193 Removes \arg{file}, returning true if successful.
1196 \membersection{::wxRenameFile}\label{wxrenamefile}
1198 \func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
1200 Renames \arg{file1} to \arg{file2}, returning true if successful.
1203 \membersection{::wxRmdir}\label{wxrmdir}
1205 \func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
1207 Removes the directory {\it dir}, returning true if successful. Does not work under VMS.
1209 The {\it flags} parameter is reserved for future use.
1212 \membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory}
1214 \func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
1216 Sets the current working directory, returning true if the operation succeeded.
1217 Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
1220 \membersection{::wxSplitPath}\label{wxsplitfunction}
1222 \func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
1224 {\bf NB:} This function is obsolete, please use
1225 \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
1227 This function splits a full file name into components: the path (including possible disk/drive
1228 specification under Windows), the base name and the extension. Any of the output parameters
1229 ({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
1230 a particular component.
1232 wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
1233 Windows, however it will not consider backslashes as path separators under Unix (where backslash
1234 is a valid character in a filename).
1236 On entry, {\it fullname} should be non-NULL (it may be empty though).
1238 On return, {\it path} contains the file path (without the trailing separator), {\it name}
1239 contains the file name and {\it ext} contains the file extension without leading dot. All
1240 three of them may be empty if the corresponding component is. The old contents of the
1241 strings pointed to by these parameters will be overwritten in any case (if the pointers
1245 \membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
1247 \func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
1249 Copies the given file to {\it stream}. Useful when converting an old application to
1250 use streams (within the document/view framework, for example).
1252 \wxheading{Include files}
1257 \membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
1259 \func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
1261 Copies the given stream to the file {\it filename}. Useful when converting an old application to
1262 use streams (within the document/view framework, for example).
1264 \wxheading{Include files}
1270 \section{Network, user and OS functions}\label{networkfunctions}
1272 The functions in this section are used to retrieve information about the
1273 current computer and/or user characteristics.
1276 \membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
1278 \func{wxString}{wxGetEmailAddress}{\void}
1280 \func{bool}{wxGetEmailAddress}{\param{char * }{buf}, \param{int }{sz}}
1282 Copies the user's email address into the supplied buffer, by
1283 concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
1284 and \helpref{wxGetUserId}{wxgetuserid}.
1286 Returns true if successful, false otherwise.
1288 \wxheading{Include files}
1293 \membersection{::wxGetFreeMemory}\label{wxgetfreememory}
1295 \func{wxMemorySize}{wxGetFreeMemory}{\void}
1297 Returns the amount of free memory in bytes under environments which
1298 support it, and -1 if not supported or failed to perform measurement.
1300 \wxheading{Include files}
1305 \membersection{::wxGetFullHostName}\label{wxgetfullhostname}
1307 \func{wxString}{wxGetFullHostName}{\void}
1309 Returns the FQDN (fully qualified domain host name) or an empty string on
1312 \wxheading{See also}
1314 \helpref{wxGetHostName}{wxgethostname}
1316 \wxheading{Include files}
1321 \membersection{::wxGetHomeDir}\label{wxgethomedir}
1323 \func{wxString}{wxGetHomeDir}{\void}
1325 Return the (current) user's home directory.
1327 \wxheading{See also}
1329 \helpref{wxGetUserHome}{wxgetuserhome}
1331 \wxheading{Include files}
1336 \membersection{::wxGetHostName}\label{wxgethostname}
1338 \func{wxString}{wxGetHostName}{\void}
1340 \func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
1342 Copies the current host machine's name into the supplied buffer. Please note
1343 that the returned name is {\it not} fully qualified, i.e. it does not include
1346 Under Windows or NT, this function first looks in the environment
1347 variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
1348 in the {\bf wxWidgets} section of the WIN.INI file is tried.
1350 The first variant of this function returns the hostname if successful or an
1351 empty string otherwise. The second (deprecated) function returns true
1352 if successful, false otherwise.
1354 \wxheading{See also}
1356 \helpref{wxGetFullHostName}{wxgetfullhostname}
1358 \wxheading{Include files}
1363 \membersection{::wxGetOsDescription}\label{wxgetosdescription}
1365 \func{wxString}{wxGetOsDescription}{\void}
1367 Returns the string containing the description of the current platform in a
1368 user-readable form. For example, this function may return strings like
1369 {\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}.
1371 \wxheading{See also}
1373 \helpref{::wxGetOsVersion}{wxgetosversion}
1375 \wxheading{Include files}
1380 \membersection{::wxGetOsVersion}\label{wxgetosversion}
1382 \func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
1384 Gets operating system version information.
1386 \begin{twocollist}\itemsep=0pt
1387 \twocolitemruled{Platform}{Return types}
1388 \twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X.
1390 Both {\it major} and {\it minor} have to be looked at as hexadecimal numbers. So System 10.2.4 returns 0x10, resp 16 for {\it major} and 0x24, resp 36 for {\it minor}. }
1391 \twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. }
1392 \twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
1393 \twocolitem{OS/2}{Return value is wxOS2\_PM.}
1394 \twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
1395 \twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}.}
1396 \twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.}
1397 \twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.}
1398 \twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
1399 \twocolitem{Windows PocketPC}{Return value is wxWINDOWS\_POCKETPC, version is returned in {\it major} and {\it minor}.}
1400 \twocolitem{Windows Smartphone}{Return value is wxWINDOWS\_SMARTPHONE, version is returned in {\it major} and {\it minor}.}
1401 \twocolitem{Windows CE (non-specific)}{Return value is wxWINDOWS\_CE, version is returned in {\it major} and {\it minor}.}
1402 \twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
1405 \wxheading{See also}
1407 \helpref{::wxGetOsDescription}{wxgetosdescription}
1409 \wxheading{Include files}
1414 \membersection{::wxGetUserHome}\label{wxgetuserhome}
1416 \func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
1418 Returns the home directory for the given user. If the username is empty
1419 (default value), this function behaves like
1420 \helpref{wxGetHomeDir}{wxgethomedir}.
1422 \wxheading{Include files}
1427 \membersection{::wxGetUserId}\label{wxgetuserid}
1429 \func{wxString}{wxGetUserId}{\void}
1431 \func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
1433 This function returns the "user id" also known as "login name" under Unix i.e.
1434 something like "jsmith". It uniquely identifies the current user (on this system).
1436 Under Windows or NT, this function first looks in the environment
1437 variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
1438 in the {\bf wxWidgets} section of the WIN.INI file is tried.
1440 The first variant of this function returns the login name if successful or an
1441 empty string otherwise. The second (deprecated) function returns true
1442 if successful, false otherwise.
1444 \wxheading{See also}
1446 \helpref{wxGetUserName}{wxgetusername}
1448 \wxheading{Include files}
1453 \membersection{::wxGetUserName}\label{wxgetusername}
1455 \func{wxString}{wxGetUserName}{\void}
1457 \func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
1459 This function returns the full user name (something like "Mr. John Smith").
1461 Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
1462 in the {\bf wxWidgets} section of the WIN.INI file. If PenWindows
1463 is running, the entry {\bf Current} in the section {\bf User} of
1464 the PENWIN.INI file is used.
1466 The first variant of this function returns the user name if successful or an
1467 empty string otherwise. The second (deprecated) function returns \true
1468 if successful, \false otherwise.
1470 \wxheading{See also}
1472 \helpref{wxGetUserId}{wxgetuserid}
1474 \wxheading{Include files}
1480 \section{String functions}\label{stringfunctions}
1483 \membersection{::copystring}\label{copystring}
1485 \func{char *}{copystring}{\param{const char *}{s}}
1487 Makes a copy of the string {\it s} using the C++ new operator, so it can be
1488 deleted with the {\it delete} operator.
1490 This function is deprecated, use \helpref{wxString}{wxstring} class instead.
1493 \membersection{::wxGetTranslation}\label{wxgettranslation}
1495 \func{const char *}{wxGetTranslation}{\param{const char * }{str}}
1497 \func{const char *}{wxGetTranslation}{\param{const char * }{str}, \param{const char * }{strPlural}, \param{size\_t }{n}}
1499 This function returns the translation of string {\it str} in the current
1500 \helpref{locale}{wxlocale}. If the string is not found in any of the loaded
1501 message catalogs (see \helpref{internationalization overview}{internationalization}), the
1502 original string is returned. In debug build, an error message is logged -- this
1503 should help to find the strings which were not yet translated. As this function
1504 is used very often, an alternative (and also common in Unix world) syntax is
1505 provided: the \helpref{\_()}{underscore} macro is defined to do the same thing
1506 as wxGetTranslation.
1508 The second form is used when retrieving translation of string that has
1509 different singular and plural form in English or different plural forms in some
1510 other language. It takes two extra arguments: as above, \arg{str}
1511 parameter must contain the singular form of the string to be converted and
1512 is used as the key for the search in the catalog. The \arg{strPlural} parameter
1513 is the plural form (in English). The parameter \arg{n} is used to determine the
1514 plural form. If no message catalog is found \arg{str} is returned if `n == 1',
1515 otherwise \arg{strPlural}.
1517 See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150}
1518 for additional information on plural forms handling. For a shorter alternative
1519 see the \helpref{wxPLURAL()}{wxplural} macro.
1521 Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}.
1523 Note that this function is not suitable for literal strings in Unicode
1524 builds, since the literal strings must be enclosed into
1525 \helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them
1526 unrecognised by \texttt{xgettext}, and so they are not extracted to the message
1527 catalog. Instead, use the \helpref{\_()}{underscore} and
1528 \helpref{wxPLURAL}{wxplural} macro for all literal strings.
1531 \membersection{::wxIsEmpty}\label{wxisempty}
1533 \func{bool}{wxIsEmpty}{\param{const char *}{ p}}
1535 Returns \true if the pointer is either {\tt NULL} or points to an empty
1536 string, \false otherwise.
1539 \membersection{::wxStrcmp}\label{wxstrcmp}
1541 \func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}}
1543 Returns a negative value, 0, or positive value if {\it p1} is less than, equal
1544 to or greater than {\it p2}. The comparison is case-sensitive.
1546 This function complements the standard C function {\it stricmp()} which performs
1547 case-insensitive comparison.
1550 \membersection{::wxStricmp}\label{wxstricmp}
1552 \func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
1554 Returns a negative value, 0, or positive value if {\it p1} is less than, equal
1555 to or greater than {\it p2}. The comparison is case-insensitive.
1557 This function complements the standard C function {\it strcmp()} which performs
1558 case-sensitive comparison.
1561 \membersection{::wxStringMatch}\label{wxstringmatch}
1563 \func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
1564 \param{bool}{ subString = true}, \param{bool}{ exact = false}}
1566 {\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
1568 Returns \true if the substring {\it s1} is found within {\it s2},
1569 ignoring case if {\it exact} is false. If {\it subString} is \false,
1570 no substring matching is done.
1573 \membersection{::wxStringEq}\label{wxstringeq}
1575 \func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
1577 {\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead.
1582 #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
1586 \membersection{::wxStrlen}\label{wxstrlen}
1588 \func{size\_t}{wxStrlen}{\param{const char *}{ p}}
1590 This is a safe version of standard function {\it strlen()}: it does exactly the
1591 same thing (i.e. returns the length of the string) except that it returns 0 if
1592 {\it p} is the {\tt NULL} pointer.
1595 \membersection{::wxSnprintf}\label{wxsnprintf}
1597 \func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
1599 This function replaces the dangerous standard function {\tt sprintf()} and is
1600 like {\tt snprintf()} available on some platforms. The only difference with
1601 sprintf() is that an additional argument - buffer size - is taken and the
1602 buffer is never overflowed.
1604 Returns the number of characters copied to the buffer or -1 if there is not
1607 \wxheading{See also}
1609 \helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
1612 \membersection{wxT}\label{wxt}
1614 \func{wxChar}{wxT}{\param{char }{ch}}
1616 \func{const wxChar *}{wxT}{\param{const char *}{s}}
1618 wxT() is a macro which can be used with character and string literals (in other
1619 words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in
1620 Unicode build configuration. Please see the
1621 \helpref{Unicode overview}{unicode} for more information.
1623 This macro is simply returns the value passed to it without changes in ASCII
1624 build. In fact, its definition is:
1627 #define wxT(x) L ## x
1634 \membersection{wxTRANSLATE}\label{wxtranslate}
1636 \func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}}
1638 This macro doesn't do anything in the program code -- it simply expands to the
1639 value of its argument (except in Unicode build where it is equivalent to
1640 \helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT
1641 with the same string which would be really unreadable).
1643 However it does have a purpose and it is to mark the literal strings for the
1644 extraction into the message catalog created by {\tt xgettext} program. Usually
1645 this is achieved using \helpref{\_()}{underscore} but that macro not only marks
1646 the string for extraction but also expands into a
1647 \helpref{wxGetTranslation}{wxgettranslation} function call which means that it
1648 cannot be used in some situations, notably for static array
1651 Here is an example which should make it more clear: suppose that you have a
1652 static array of strings containing the weekday names and which have to be
1653 translated (note that it is a bad example, really, as
1654 \helpref{wxDateTime}{wxdatetime} already can be used to get the localized week
1655 day names already). If you write
1658 static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
1660 // use weekdays[n] as usual
1663 the code wouldn't compile because the function calls are forbidden in the array
1664 initializer. So instead you should do
1667 static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
1669 // use wxGetTranslation(weekdays[n])
1674 Note that although the code {\bf would} compile if you simply omit
1675 wxTRANSLATE() in the above, it wouldn't work as expected because there would be
1676 no translations for the weekday names in the program message catalog and
1677 wxGetTranslation wouldn't find them.
1679 \membersection{::wxVsnprintf}\label{wxvsnprintf}
1681 \func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
1683 The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list }
1684 argument instead of arbitrary number of parameters.
1686 \wxheading{See also}
1688 \helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
1692 \membersection{\_}\label{underscore}
1694 \func{const wxChar *}{\_}{\param{const char *}{s}}
1696 This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation}
1697 function, so it marks the message for the extraction by {\tt xgettext} just as
1698 \helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of
1699 the string for the current locale during execution.
1701 Don't confuse this macro with \helpref{\_T()}{underscoret}!
1704 \membersection{wxPLURAL}\label{wxplural}
1706 \func{const wxChar *}{wxPLURAL}{\param{const char *}{sing}, \param{const char *}{plur}, \param{size\_t}{n}}
1708 This macro is identical to \helpref{\_()}{underscore} but for the plural variant
1709 of \helpref{wxGetTranslation}{wxgettranslation}.
1712 \membersection{\_T}\label{underscoret}
1714 \func{wxChar}{\_T}{\param{char }{ch}}
1716 \func{const wxChar *}{\_T}{\param{const wxChar }{ch}}
1718 This macro is exactly the same as \helpref{wxT}{wxt} and is defined in
1719 wxWidgets simply because it may be more intuitive for Windows programmers as
1720 the standard Win32 headers also define it (as well as yet another name for the
1721 same macro which is {\tt \_TEXT()}).
1723 Don't confuse this macro with \helpref{\_()}{underscore}!
1727 \section{Dialog functions}\label{dialogfunctions}
1729 Below are a number of convenience functions for getting input from the
1730 user or displaying messages. Note that in these functions the last three
1731 parameters are optional. However, it is recommended to pass a parent frame
1732 parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
1733 the front when the dialog box is popped up.
1736 \membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
1738 \func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
1740 Changes the cursor to the given cursor for all windows in the application.
1741 Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
1742 to its previous state. These two calls can be nested, and a counter
1743 ensures that only the outer calls take effect.
1745 See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
1747 \wxheading{Include files}
1752 \membersection{::wxBell}\label{wxbell}
1754 \func{void}{wxBell}{\void}
1756 Ring the system bell.
1758 \wxheading{Include files}
1763 \membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
1765 \func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
1766 \param{size\_t }{currentTip}}
1768 This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
1769 used with \helpref{wxShowTip}{wxshowtip}.
1771 \docparam{filename}{The name of the file containing the tips, one per line}
1772 \docparam{currentTip}{The index of the first tip to show - normally this index
1773 is remembered between the 2 program runs.}
1775 \wxheading{See also}
1777 \helpref{Tips overview}{tipsoverview}
1779 \wxheading{Include files}
1784 \membersection{::wxDirSelector}\label{wxdirselector}
1786 \func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\
1787 \param{const wxString\& }{default\_path = ""},\\
1788 \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\
1789 \param{wxWindow *}{parent = NULL}}
1791 Pops up a directory selector dialog. The arguments have the same meaning as
1792 those of wxDirDialog::wxDirDialog(). The message is displayed at the top,
1793 and the default\_path, if specified, is set as the initial selection.
1795 The application must check for an empty return value (if the user pressed
1796 Cancel). For example:
1799 const wxString& dir = wxDirSelector("Choose a folder");
1806 \wxheading{Include files}
1811 \membersection{::wxFileSelector}\label{wxfileselector}
1813 \func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
1814 \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\
1815 \param{const wxString\& }{wildcard = "*.*"}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\
1816 \param{int}{ x = -1}, \param{int}{ y = -1}}
1818 Pops up a file selector box. In Windows, this is the common file selector
1819 dialog. In X, this is a file selector box with the same functionality.
1820 The path and filename are distinct elements of a full file pathname.
1821 If path is empty, the current directory will be used. If filename is empty,
1822 no default filename will be supplied. The wildcard determines what files
1823 are displayed in the file selector, and file extension supplies a type
1824 extension for the required filename. Flags may be a combination of wxOPEN,
1825 wxSAVE, wxOVERWRITE\_PROMPT, wxFILE\_MUST\_EXIST, wxMULTIPLE or 0.
1827 Both the Unix and Windows versions implement a wildcard filter. Typing a
1828 filename containing wildcards (*, ?) in the filename text item, and
1829 clicking on Ok, will result in only those files matching the pattern being
1832 The wildcard may be a specification for multiple types of file
1833 with a description for each, such as:
1836 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
1839 The application must check for an empty return value (the user pressed
1840 Cancel). For example:
1843 wxString filename = wxFileSelector("Choose a file to open");
1844 if ( !filename.empty() )
1846 // work with the file
1849 //else: cancelled by user
1852 \wxheading{Include files}
1857 \membersection{::wxEndBusyCursor}\label{wxendbusycursor}
1859 \func{void}{wxEndBusyCursor}{\void}
1861 Changes the cursor back to the original cursor, for all windows in the application.
1862 Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
1864 See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
1866 \wxheading{Include files}
1871 \membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
1873 \func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}}
1875 Shows the colour selection dialog and returns the colour selected by user or
1876 invalid colour (use \helpref{wxColour::Ok}{wxcolourok} to test whether a colour
1877 is valid) if the dialog was cancelled.
1879 \wxheading{Parameters}
1881 \docparam{parent}{The parent window for the colour selection dialog}
1883 \docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
1885 \wxheading{Include files}
1890 \membersection{::wxGetFontFromUser}\label{wxgetfontfromuser}
1892 \func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}}
1894 Shows the font selection dialog and returns the font selected by user or
1895 invalid font (use \helpref{wxFont::Ok}{wxfontok} to test whether a font
1896 is valid) if the dialog was cancelled.
1898 \wxheading{Parameters}
1900 \docparam{parent}{The parent window for the font selection dialog}
1902 \docparam{fontInit}{If given, this will be the font initially selected in the dialog.}
1904 \wxheading{Include files}
1910 \membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
1912 \func{size\_t}{wxGetMultipleChoices}{\\
1913 \param{wxArrayInt\& }{selections},\\
1914 \param{const wxString\& }{message},\\
1915 \param{const wxString\& }{caption},\\
1916 \param{const wxArrayString\& }{aChoices},\\
1917 \param{wxWindow *}{parent = NULL},\\
1918 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1919 \param{bool}{ centre = true},\\
1920 \param{int }{width=150}, \param{int }{height=200}}
1922 \func{size\_t}{wxGetMultipleChoices}{\\
1923 \param{wxArrayInt\& }{selections},\\
1924 \param{const wxString\& }{message},\\
1925 \param{const wxString\& }{caption},\\
1926 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
1927 \param{wxWindow *}{parent = NULL},\\
1928 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1929 \param{bool}{ centre = true},\\
1930 \param{int }{width=150}, \param{int }{height=200}}
1932 Pops up a dialog box containing a message, OK/Cancel buttons and a
1933 multiple-selection listbox. The user may choose an arbitrary (including 0)
1934 number of items in the listbox whose indices will be returned in
1935 {\it selection} array. The initial contents of this array will be used to
1936 select the items when the dialog is shown.
1938 You may pass the list of strings to choose from either using {\it choices}
1939 which is an array of {\it n} strings for the listbox or by using a single
1940 {\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
1942 If {\it centre} is true, the message text (which may include new line
1943 characters) is centred; if false, the message is left-justified.
1945 \wxheading{Include files}
1949 \perlnote{In wxPerl there is just an array reference in place of {\tt n}
1950 and {\tt choices}, and no {\tt selections} parameter; the function
1951 returns an array containing the user selections.}
1954 \membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
1956 \func{long}{wxGetNumberFromUser}{
1957 \param{const wxString\& }{message},
1958 \param{const wxString\& }{prompt},
1959 \param{const wxString\& }{caption},
1960 \param{long }{value},
1961 \param{long }{min = 0},
1962 \param{long }{max = 100},
1963 \param{wxWindow *}{parent = NULL},
1964 \param{const wxPoint\& }{pos = wxDefaultPosition}}
1966 Shows a dialog asking the user for numeric input. The dialogs title is set to
1967 {\it caption}, it contains a (possibly) multiline {\it message} above the
1968 single line {\it prompt} and the zone for entering the number.
1970 The number entered must be in the range {\it min}..{\it max} (both of which
1971 should be positive) and {\it value} is the initial value of it. If the user
1972 enters an invalid value or cancels the dialog, the function will return -1.
1974 Dialog is centered on its {\it parent} unless an explicit position is given in
1977 \wxheading{Include files}
1982 \membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
1984 \func{wxString}{wxGetPasswordFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
1985 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
1986 \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}}
1988 Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered
1989 in the dialog is not shown on screen but replaced with stars. This is intended
1990 to be used for entering passwords as the function name implies.
1992 \wxheading{Include files}
1997 \membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
1999 \func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
2000 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
2001 \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}}
2003 Pop up a dialog box with title set to {\it caption}, {\it message}, and a
2004 \rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
2005 or press Cancel to return the empty string.
2007 If {\it centre} is true, the message text (which may include new line characters)
2008 is centred; if false, the message is left-justified.
2010 \wxheading{Include files}
2015 \membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
2017 \func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
2018 \param{int }{nsel}, \param{int *}{selection},
2019 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
2020 \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
2022 Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
2023 listbox. The user may choose one or more item(s) and press OK or Cancel.
2025 The number of initially selected choices, and array of the selected indices,
2026 are passed in; this array will contain the user selections on exit, with
2027 the function returning the number of selections. {\it selection} must be
2028 as big as the number of choices, in case all are selected.
2030 If Cancel is pressed, -1 is returned.
2032 {\it choices} is an array of {\it n} strings for the listbox.
2034 If {\it centre} is true, the message text (which may include new line characters)
2035 is centred; if false, the message is left-justified.
2037 \wxheading{Include files}
2042 \membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
2044 \func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
2045 \param{const wxString\& }{caption},\\
2046 \param{const wxArrayString\& }{aChoices},\\
2047 \param{wxWindow *}{parent = NULL},\\
2048 \param{int}{ x = -1}, \param{int}{ y = -1},\\
2049 \param{bool}{ centre = true},\\
2050 \param{int }{width=150}, \param{int }{height=200}}
2052 \func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
2053 \param{const wxString\& }{caption},\\
2054 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
2055 \param{wxWindow *}{parent = NULL},\\
2056 \param{int}{ x = -1}, \param{int}{ y = -1},\\
2057 \param{bool}{ centre = true},\\
2058 \param{int }{width=150}, \param{int }{height=200}}
2060 Pops up a dialog box containing a message, OK/Cancel buttons and a
2061 single-selection listbox. The user may choose an item and press OK to return a
2062 string or Cancel to return the empty string. Use
2063 \helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex} if empty string is a
2064 valid choice and if you want to be able to detect pressing Cancel reliably.
2066 You may pass the list of strings to choose from either using {\it choices}
2067 which is an array of {\it n} strings for the listbox or by using a single
2068 {\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
2070 If {\it centre} is true, the message text (which may include new line
2071 characters) is centred; if false, the message is left-justified.
2073 \wxheading{Include files}
2077 \perlnote{In wxPerl there is just an array reference in place of {\tt n}
2081 \membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
2083 \func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
2084 \param{const wxString\& }{caption},\\
2085 \param{const wxArrayString\& }{aChoices},\\
2086 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
2087 \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
2089 \func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
2090 \param{const wxString\& }{caption},\\
2091 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
2092 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
2093 \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
2095 As {\bf wxGetSingleChoice} but returns the index representing the selected
2096 string. If the user pressed cancel, -1 is returned.
2098 \wxheading{Include files}
2102 \perlnote{In wxPerl there is just an array reference in place of {\tt n}
2106 \membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
2108 \func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
2109 \param{const wxString\& }{caption},\\
2110 \param{const wxArrayString\& }{aChoices},\\
2111 \param{const wxString\& }{client\_data[]},\\
2112 \param{wxWindow *}{parent = NULL},\\
2113 \param{int}{ x = -1}, \param{int}{ y = -1},\\
2114 \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
2116 \func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
2117 \param{const wxString\& }{caption},\\
2118 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
2119 \param{const wxString\& }{client\_data[]},\\
2120 \param{wxWindow *}{parent = NULL},\\
2121 \param{int}{ x = -1}, \param{int}{ y = -1},\\
2122 \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
2124 As {\bf wxGetSingleChoice} but takes an array of client data pointers
2125 corresponding to the strings, and returns one of these pointers or NULL if
2126 Cancel was pressed. The {\it client\_data} array must have the same number of
2127 elements as {\it choices} or {\it aChoices}!
2129 \wxheading{Include files}
2133 \perlnote{In wxPerl there is just an array reference in place of {\tt n}
2134 and {\tt choices}, and the client data array must have the
2135 same length as the choices array.}
2138 \membersection{::wxIsBusy}\label{wxisbusy}
2140 \func{bool}{wxIsBusy}{\void}
2142 Returns true if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
2143 \helpref{wxEndBusyCursor}{wxendbusycursor} calls.
2145 See also \helpref{wxBusyCursor}{wxbusycursor}.
2147 \wxheading{Include files}
2152 \membersection{::wxMessageBox}\label{wxmessagebox}
2154 \func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK},\\
2155 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
2157 General purpose message dialog. {\it style} may be a bit list of the
2158 following identifiers:
2160 \begin{twocollist}\itemsep=0pt
2161 \twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
2163 \twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
2165 \twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
2166 \twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.}
2167 \twocolitem{wxICON\_HAND}{Displays an error symbol.}
2168 \twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.}
2169 \twocolitem{wxICON\_QUESTION}{Displays a question mark symbol.}
2170 \twocolitem{wxICON\_INFORMATION}{Displays an information symbol.}
2173 The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
2179 int answer = wxMessageBox("Quit program?", "Confirm",
2180 wxYES_NO | wxCANCEL, main_frame);
2181 if (answer == wxYES)
2182 main_frame->Close();
2186 {\it message} may contain newline characters, in which case the
2187 message will be split into separate lines, to cater for large messages.
2189 \wxheading{Include files}
2194 \membersection{::wxShowTip}\label{wxshowtip}
2196 \func{bool}{wxShowTip}{\param{wxWindow *}{parent},
2197 \param{wxTipProvider *}{tipProvider},
2198 \param{bool }{showAtStartup = true}}
2200 This function shows a "startup tip" to the user. The return value is the
2201 state of the `Show tips at startup' checkbox.
2203 \docparam{parent}{The parent window for the modal dialog}
2205 \docparam{tipProvider}{An object which is used to get the text of the tips.
2206 It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
2208 \docparam{showAtStartup}{Should be true if startup tips are shown, false
2209 otherwise. This is used as the initial value for "Show tips at startup"
2210 checkbox which is shown in the tips dialog.}
2212 \wxheading{See also}
2214 \helpref{Tips overview}{tipsoverview}
2216 \wxheading{Include files}
2223 \section{Math functions}\label{mathfunctions}
2225 \wxheading{Include files}
2230 \membersection{wxFinite}\label{wxfinite}
2232 \func{int}{wxFinite}{\param{double }{x}}
2234 Returns a non-zero value if {\it x} is neither infinite or NaN (not a number),
2235 returns 0 otherwise.
2238 \membersection{wxIsNaN}\label{wxisnan}
2240 \func{bool}{wxIsNaN}{\param{double }{x}}
2242 Returns a non-zero value if {\it x} is NaN (not a number), returns 0
2248 \section{GDI functions}\label{gdifunctions}
2250 The following are relevant to the GDI (Graphics Device Interface).
2252 \wxheading{Include files}
2257 \membersection{wxBITMAP}\label{wxbitmapmacro}
2259 \func{}{wxBITMAP}{bitmapName}
2261 This macro loads a bitmap from either application resources (on the platforms
2262 for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
2263 avoid using {\tt \#ifdef}s when creating bitmaps.
2265 \wxheading{See also}
2267 \helpref{Bitmaps and icons overview}{wxbitmapoverview},
2268 \helpref{wxICON}{wxiconmacro}
2270 \wxheading{Include files}
2275 \membersection{::wxClientDisplayRect}\label{wxclientdisplayrect}
2277 \func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
2278 \param{int *}{width}, \param{int *}{height}}
2280 \func{wxRect}{wxGetClientDisplayRect}{\void}
2282 Returns the dimensions of the work area on the display. On Windows
2283 this means the area not covered by the taskbar, etc. Other platforms
2284 are currently defaulting to the whole display until a way is found to
2285 provide this info for all window managers, etc.
2288 \membersection{::wxColourDisplay}\label{wxcolourdisplay}
2290 \func{bool}{wxColourDisplay}{\void}
2292 Returns true if the display is colour, false otherwise.
2295 \membersection{::wxDisplayDepth}\label{wxdisplaydepth}
2297 \func{int}{wxDisplayDepth}{\void}
2299 Returns the depth of the display (a value of 1 denotes a monochrome display).
2302 \membersection{::wxDisplaySize}\label{wxdisplaysize}
2304 \func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
2306 \func{wxSize}{wxGetDisplaySize}{\void}
2308 Returns the display size in pixels.
2311 \membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm}
2313 \func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
2315 \func{wxSize}{wxGetDisplaySizeMM}{\void}
2317 Returns the display size in millimeters.
2320 \membersection{::wxDROP\_ICON}\label{wxdropicon}
2322 \func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
2324 This macro creates either a cursor (MSW) or an icon (elsewhere) with the given
2325 name. Under MSW, the cursor is loaded from the resource file and the icon is
2326 loaded from XPM file under other platforms.
2328 This macro should be used with
2329 \helpref{wxDropSource constructor}{wxdropsourcewxdropsource}.
2331 \wxheading{Include files}
2336 \membersection{wxICON}\label{wxiconmacro}
2338 \func{}{wxICON}{iconName}
2340 This macro loads an icon from either application resources (on the platforms
2341 for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
2342 avoid using {\tt \#ifdef}s when creating icons.
2344 \wxheading{See also}
2346 \helpref{Bitmaps and icons overview}{wxbitmapoverview},
2347 \helpref{wxBITMAP}{wxbitmapmacro}
2349 \wxheading{Include files}
2354 \membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
2356 \func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
2357 \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
2359 Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
2360 makes it into a placeable metafile by prepending a header containing the given
2361 bounding box. The bounding box may be obtained from a device context after drawing
2362 into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
2364 In addition to adding the placeable metafile header, this function adds
2365 the equivalent of the following code to the start of the metafile data:
2368 SetMapMode(dc, MM_ANISOTROPIC);
2369 SetWindowOrg(dc, minX, minY);
2370 SetWindowExt(dc, maxX - minX, maxY - minY);
2373 This simulates the wxMM\_TEXT mapping mode, which wxWidgets assumes.
2375 Placeable metafiles may be imported by many Windows applications, and can be
2376 used in RTF (Rich Text Format) files.
2378 {\it scale} allows the specification of scale for the metafile.
2380 This function is only available under Windows.
2383 \membersection{::wxSetCursor}\label{wxsetcursor}
2385 \func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
2387 Globally sets the cursor; only has an effect in Windows and GTK.
2388 See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
2392 \section{Printer settings}\label{printersettings}
2394 {\bf NB:} These routines are obsolete and should no longer be used!
2396 The following functions are used to control PostScript printing. Under
2397 Windows, PostScript output can only be sent to a file.
2399 \wxheading{Include files}
2404 \membersection{::wxGetPrinterCommand}\label{wxgetprintercommand}
2406 \func{wxString}{wxGetPrinterCommand}{\void}
2408 Gets the printer command used to print a file. The default is {\tt lpr}.
2411 \membersection{::wxGetPrinterFile}\label{wxgetprinterfile}
2413 \func{wxString}{wxGetPrinterFile}{\void}
2415 Gets the PostScript output filename.
2418 \membersection{::wxGetPrinterMode}\label{wxgetprintermode}
2420 \func{int}{wxGetPrinterMode}{\void}
2422 Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
2423 The default is PS\_PREVIEW.
2426 \membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions}
2428 \func{wxString}{wxGetPrinterOptions}{\void}
2430 Gets the additional options for the print command (e.g. specific printer). The default is nothing.
2433 \membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation}
2435 \func{int}{wxGetPrinterOrientation}{\void}
2437 Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
2440 \membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand}
2442 \func{wxString}{wxGetPrinterPreviewCommand}{\void}
2444 Gets the command used to view a PostScript file. The default depends on the platform.
2447 \membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling}
2449 \func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
2451 Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
2454 \membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation}
2456 \func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
2458 Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
2461 \membersection{::wxSetPrinterCommand}\label{wxsetprintercommand}
2463 \func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
2465 Sets the printer command used to print a file. The default is {\tt lpr}.
2468 \membersection{::wxSetPrinterFile}\label{wxsetprinterfile}
2470 \func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
2472 Sets the PostScript output filename.
2475 \membersection{::wxSetPrinterMode}\label{wxsetprintermode}
2477 \func{void}{wxSetPrinterMode}{\param{int }{mode}}
2479 Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
2480 The default is PS\_PREVIEW.
2483 \membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions}
2485 \func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
2487 Sets the additional options for the print command (e.g. specific printer). The default is nothing.
2490 \membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation}
2492 \func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
2494 Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
2497 \membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand}
2499 \func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
2501 Sets the command used to view a PostScript file. The default depends on the platform.
2504 \membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling}
2506 \func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
2508 Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
2511 \membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation}
2513 \func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
2515 Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
2519 \section{Clipboard functions}\label{clipsboard}
2521 These clipboard functions are implemented for Windows only. The use of these functions
2522 is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard}
2525 \wxheading{Include files}
2530 \membersection{::wxClipboardOpen}\label{functionwxclipboardopen}
2532 \func{bool}{wxClipboardOpen}{\void}
2534 Returns true if this application has already opened the clipboard.
2537 \membersection{::wxCloseClipboard}\label{wxcloseclipboard}
2539 \func{bool}{wxCloseClipboard}{\void}
2541 Closes the clipboard to allow other applications to use it.
2544 \membersection{::wxEmptyClipboard}\label{wxemptyclipboard}
2546 \func{bool}{wxEmptyClipboard}{\void}
2548 Empties the clipboard.
2551 \membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats}
2553 \func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
2555 Enumerates the formats found in a list of available formats that belong
2556 to the clipboard. Each call to this function specifies a known
2557 available format; the function returns the format that appears next in
2560 {\it dataFormat} specifies a known format. If this parameter is zero,
2561 the function returns the first format in the list.
2563 The return value specifies the next known clipboard data format if the
2564 function is successful. It is zero if the {\it dataFormat} parameter specifies
2565 the last format in the list of available formats, or if the clipboard
2568 Before it enumerates the formats function, an application must open the clipboard by using the
2569 wxOpenClipboard function.
2572 \membersection{::wxGetClipboardData}\label{wxgetclipboarddata}
2574 \func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
2576 Gets data from the clipboard.
2578 {\it dataFormat} may be one of:
2580 \begin{itemize}\itemsep=0pt
2581 \item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
2582 \item wxCF\_BITMAP: returns a new wxBitmap.
2585 The clipboard must have previously been opened for this call to succeed.
2588 \membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname}
2590 \func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
2592 Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
2593 length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
2596 \membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable}
2598 \func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
2600 Returns true if the given data format is available on the clipboard.
2603 \membersection{::wxOpenClipboard}\label{wxopenclipboard}
2605 \func{bool}{wxOpenClipboard}{\void}
2607 Opens the clipboard for passing data to it or getting data from it.
2610 \membersection{::wxRegisterClipboardFormat}\label{wxregisterclipboardformat}
2612 \func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
2614 Registers the clipboard data format name and returns an identifier.
2617 \membersection{::wxSetClipboardData}\label{wxsetclipboarddata}
2619 \func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
2621 Passes data to the clipboard.
2623 {\it dataFormat} may be one of:
2625 \begin{itemize}\itemsep=0pt
2626 \item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
2627 \item wxCF\_BITMAP: {\it data} is a wxBitmap.
2628 \item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
2629 \item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
2632 The clipboard must have previously been opened for this call to succeed.
2637 \section{Miscellaneous functions}\label{miscellany}
2640 \membersection{wxCONCAT}\label{wxconcat}
2642 \func{}{wxCONCAT}{\param{}{x}, \param{}{y}}
2644 This macro returns the concatenation of two tokens \arg{x} and \arg{y}.
2647 \membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction}
2649 \func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}}
2651 When loading a function from a DLL you always have to cast the returned
2652 {\tt void *} pointer to the correct type and, even more annoyingly, you have to
2653 repeat this type twice if you want to declare and define a function pointer all
2656 This macro makes this slightly less painful by allowing you to specify the
2657 type only once, as the first parameter, and creating a variable of this type
2658 named after the function but with {\tt pfn} prefix and initialized with the
2659 function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary}
2662 \wxheading{Parameters}
2664 \docparam{type}{the type of the function}
2666 \docparam{name}{the name of the function to load, not a string (without quotes,
2667 it is quoted automatically by the macro)}
2669 \docparam{dynlib}{the library to load the function from}
2673 \membersection{wxEXPLICIT}\label{wxexplicit}
2675 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if
2676 the compiler supports it or nothing otherwise. Thus, it can be used even in the
2677 code which might have to be compiled with an old compiler without support for
2678 this language feature but still take advantage of it when it is available.
2681 \membersection{::wxGetKeyState}\label{wxgetkeystate}
2683 \func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}}
2685 For normal keys, returns \true if the specified key is currently down.
2687 For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
2688 \true if the key is toggled such that its LED indicator is lit. There is
2689 currently no way to test whether togglable keys are up or down.
2691 Even though there are virtual key codes defined for mouse buttons, they
2692 cannot be used with this function currently.
2694 \wxheading{Include files}
2699 \membersection{wxLL}\label{wxll}
2701 \func{wxLongLong\_t}{wxLL}{\param{}{number}}
2703 This macro is defined for the platforms with a native 64 bit integer type and
2704 allows to define 64 bit compile time constants:
2708 wxLongLong_t ll = wxLL(0x1234567890abcdef);
2712 \wxheading{Include files}
2716 \wxheading{See also}
2718 \helpref{wxULL}{wxull}, \helpref{wxLongLong}{wxlonglong}
2721 \membersection{wxLongLongFmtSpec}\label{wxlonglongfmtspec}
2723 This macro is defined to contain the {\tt printf()} format specifier using
2724 which 64 bit integer numbers (i.e. those of type {\tt wxLongLong\_t}) can be
2725 printed. Example of using it:
2729 wxLongLong_t ll = wxLL(0x1234567890abcdef);
2730 printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
2734 \wxheading{See also}
2736 \helpref{wxLL}{wxll}
2738 \wxheading{Include files}
2743 \membersection{::wxNewId}\label{wxnewid}
2745 \func{long}{wxNewId}{\void}
2747 Generates an integer identifier unique to this run of the program.
2749 \wxheading{Include files}
2754 \membersection{wxON\_BLOCK\_EXIT}\label{wxonblockexit}
2756 \func{}{wxON\_BLOCK\_EXIT0}{\param{}{func}}
2757 \func{}{wxON\_BLOCK\_EXIT1}{\param{}{func}, \param{}{p1}}
2758 \func{}{wxON\_BLOCK\_EXIT2}{\param{}{func}, \param{}{p1}, \param{}{p2}}
2760 This family of macros allows to ensure that the global function \arg{func}
2761 with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is
2762 executed on scope exit, whether due to a normal function return or because an
2763 exception has been thrown. A typical example of its usage:
2765 void *buf = malloc(size);
2766 wxON_BLOCK_EXIT1(free, buf);
2769 Please see the original article by Andrei Alexandrescu and Petru Marginean
2770 published in December 2000 issue of \emph{C/C++ Users Journal} for more
2773 \wxheading{Include files}
2777 \wxheading{See also}
2779 \helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}
2782 \membersection{wxON\_BLOCK\_EXIT\_OBJ}\label{wxonblockexitobj}
2784 \func{}{wxON\_BLOCK\_EXIT\_OBJ0}{\param{}{obj}, \param{}{method}}
2785 \func{}{wxON\_BLOCK\_EXIT\_OBJ1}{\param{}{obj}, \param{}{method}, \param{}{p1}}
2786 \func{}{wxON\_BLOCK\_EXIT\_OBJ2}{\param{}{obj}, \param{}{method}, \param{}{p1}, \param{}{p2}}
2788 This family of macros is similar to \helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}
2789 but calls a method of the given object instead of a free function.
2791 \wxheading{Include files}
2796 \membersection{::wxRegisterId}\label{wxregisterid}
2798 \func{void}{wxRegisterId}{\param{long}{ id}}
2800 Ensures that ids subsequently generated by {\bf NewId} do not clash with
2803 \wxheading{Include files}
2808 \membersection{::wxDDECleanUp}\label{wxddecleanup}
2810 \func{void}{wxDDECleanUp}{\void}
2812 Called when wxWidgets exits, to clean up the DDE system. This no longer needs to be
2813 called by the application.
2815 See also \helpref{wxDDEInitialize}{wxddeinitialize}.
2817 \wxheading{Include files}
2822 \membersection{::wxDDEInitialize}\label{wxddeinitialize}
2824 \func{void}{wxDDEInitialize}{\void}
2826 Initializes the DDE system. May be called multiple times without harm.
2828 This no longer needs to be called by the application: it will be called
2829 by wxWidgets if necessary.
2831 See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},\rtfsp
2832 \helpref{wxDDECleanUp}{wxddecleanup}.
2834 \wxheading{Include files}
2839 \membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
2841 \func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = true}}
2843 This function enables or disables all top level windows. It is used by
2844 \helpref{::wxSafeYield}{wxsafeyield}.
2846 \wxheading{Include files}
2851 \membersection{::wxFindMenuItemId}\label{wxfindmenuitemid}
2853 \func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
2855 Find a menu item identifier associated with the given frame's menu bar.
2857 \wxheading{Include files}
2862 \membersection{::wxFindWindowByLabel}\label{wxfindwindowbylabel}
2864 \func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
2866 {\bf NB:} This function is obsolete, please use
2867 \helpref{wxWindow::FindWindowByLabel}{wxwindowfindwindowbylabel} instead.
2869 Find a window by its label. Depending on the type of window, the label may be a window title
2870 or panel item label. If {\it parent} is NULL, the search will start from all top-level
2871 frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
2872 The search is recursive in both cases.
2874 \wxheading{Include files}
2879 \membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
2881 \func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
2883 {\bf NB:} This function is obsolete, please use
2884 \helpref{wxWindow::FindWindowByName}{wxwindowfindwindowbyname} instead.
2886 Find a window by its name (as given in a window constructor or {\bf Create} function call).
2887 If {\it parent} is NULL, the search will start from all top-level
2888 frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
2889 The search is recursive in both cases.
2891 If no such named window is found, {\bf wxFindWindowByLabel} is called.
2893 \wxheading{Include files}
2898 \membersection{::wxFindWindowAtPoint}\label{wxfindwindowatpoint}
2900 \func{wxWindow *}{wxFindWindowAtPoint}{\param{const wxPoint\& }{pt}}
2902 Find the deepest window at the given mouse position in screen coordinates,
2903 returning the window if found, or NULL if not.
2906 \membersection{::wxFindWindowAtPointer}\label{wxfindwindowatpointer}
2908 \func{wxWindow *}{wxFindWindowAtPointer}{\param{wxPoint\& }{pt}}
2910 Find the deepest window at the mouse pointer position, returning the window
2911 and current pointer position in screen coordinates.
2914 \membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
2916 \func{wxWindow *}{wxGetActiveWindow}{\void}
2918 Gets the currently active window (Windows only).
2920 \wxheading{Include files}
2925 \membersection{::wxGetBatteryState}\label{wxgetbatterystate}
2927 \func{wxBatteryState}{wxGetBatteryState}{\void}
2929 Returns battery state as one of \texttt{wxBATTERY\_NORMAL\_STATE},
2930 \texttt{wxBATTERY\_LOW\_STATE}, \texttt{wxBATTERY\_CRITICAL\_STATE},
2931 \texttt{wxBATTERY\_SHUTDOWN\_STATE} or \texttt{wxBATTERY\_UNKNOWN\_STATE}.
2932 \texttt{wxBATTERY\_UNKNOWN\_STATE} is also the default on platforms where
2933 this feature is not implemented.
2935 \wxheading{Include files}
2940 \membersection{::wxGetDisplayName}\label{wxgetdisplayname}
2942 \func{wxString}{wxGetDisplayName}{\void}
2944 Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
2946 \wxheading{Include files}
2951 \membersection{::wxGetPowerType}\label{wxgetpowertype}
2953 \func{wxPowerType}{wxGetPowerType}{\void}
2955 Returns the type of power source as one of \texttt{wxPOWER\_SOCKET},
2956 \texttt{wxPOWER\_BATTERY} or \texttt{wxPOWER\_UNKNOWN}.
2957 \texttt{wxPOWER\_UNKNOWN} is also the default on platforms where this
2958 feature is not implemented.
2960 \wxheading{Include files}
2965 \membersection{::wxGetMousePosition}\label{wxgetmouseposition}
2967 \func{wxPoint}{wxGetMousePosition}{\void}
2969 Returns the mouse position in screen coordinates.
2971 \wxheading{Include files}
2976 \membersection{::wxGetResource}\label{wxgetresource}
2978 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2979 \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
2981 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2982 \param{float *}{value}, \param{const wxString\& }{file = NULL}}
2984 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2985 \param{long *}{value}, \param{const wxString\& }{file = NULL}}
2987 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2988 \param{int *}{value}, \param{const wxString\& }{file = NULL}}
2990 Gets a resource value from the resource database (for example, WIN.INI, or
2991 .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
2992 otherwise the specified file is used.
2994 Under X, if an application class (wxApp::GetClassName) has been defined,
2995 it is appended to the string /usr/lib/X11/app-defaults/ to try to find
2996 an applications default file when merging all resource databases.
2998 The reason for passing the result in an argument is that it
2999 can be convenient to define a default value, which gets overridden
3000 if the value exists in the resource file. It saves a separate
3001 test for that resource's existence, and it also allows
3002 the overloading of the function for different types.
3004 See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
3006 \wxheading{Include files}
3011 \membersection{::wxGetStockLabel}\label{wxgetstocklabel}
3013 \func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{wxString }{accelerator = wxEmptyString}}
3015 Returns label that should be used for given {\it id} element.
3017 \wxheading{Parameters}
3019 \docparam{id}{given id of the \helpref{wxMenuItem}{wxmenuitem}, \helpref{wxButton}{wxbutton}, \helpref{wxToolBar}{wxtoolbar} tool, etc.}
3021 \docparam{withCodes}{if false then strip accelerator code from the label;
3022 usefull for getting labels without accelerator char code like for toolbar tooltip or
3023 under platforms without traditional keyboard like smartphones}
3025 \docparam{accelerator}{optional accelerator string automatically added to label; useful
3026 for building labels for \helpref{wxMenuItem}{wxmenuitem}}
3028 \wxheading{Include files}
3033 \membersection{::wxGetTopLevelParent}\label{wxgettoplevelparent}
3035 \func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}}
3037 Returns the first top level parent of the given window, or in other words, the
3038 frame or dialog containing it, or {\tt NULL}.
3040 \wxheading{Include files}
3045 \membersection{::wxLaunchDefaultBrowser}\label{wxlaunchdefaultbrowser}
3047 \func{bool}{wxLaunchDefaultBrowser}{\param{const wxString\& }{sUrl}}
3049 Launches the user's default browser and tells it to open the location at {\tt sUrl}.
3051 Returns true if the application was successfully launched.
3053 \wxheading{Include files}
3057 \membersection{::wxLoadUserResource}\label{wxloaduserresource}
3059 \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
3061 Loads a user-defined Windows resource as a string. If the resource is found, the function creates
3062 a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
3064 The resource must be defined in the {\tt .rc} file using the following syntax:
3067 myResource TEXT file.ext
3070 where {\tt file.ext} is a file that the resource compiler can find.
3072 This function is available under Windows only.
3074 \wxheading{Include files}
3079 \membersection{::wxPostDelete}\label{wxpostdelete}
3081 \func{void}{wxPostDelete}{\param{wxObject *}{object}}
3083 Tells the system to delete the specified object when
3084 all other events have been processed. In some environments, it is
3085 necessary to use this instead of deleting a frame directly with the
3086 delete operator, because some GUIs will still send events to a deleted window.
3088 Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
3090 \wxheading{Include files}
3095 \membersection{::wxPostEvent}\label{wxpostevent}
3097 \func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
3099 In a GUI application, this function posts {\it event} to the specified {\it dest}
3100 object using \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
3101 Otherwise, it dispatches {\it event} immediately using
3102 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}.
3103 See the respective documentation for details (and caveats).
3105 \wxheading{Include files}
3110 \membersection{::wxSetDisplayName}\label{wxsetdisplayname}
3112 \func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
3114 Under X only, sets the current display name. This is the X host and display name such
3115 as ``colonsay:0.0", and the function indicates which display should be used for creating
3116 windows from this point on. Setting the display within an application allows multiple
3117 displays to be used.
3119 See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
3121 \wxheading{Include files}
3126 \membersection{::wxStripMenuCodes}\label{wxstripmenucodes}
3128 \func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
3130 \func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}}
3132 {\bf NB:} This function is obsolete, please use
3133 \helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead.
3135 Strips any menu codes from {\it in} and places the result
3136 in {\it out} (or returns the new string, in the first form).
3138 Menu codes include \& (mark the next character with an underline
3139 as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
3141 \wxheading{Include files}
3146 \membersection{wxULL}\label{wxull}
3148 \func{wxLongLong\_t}{wxULL}{\param{}{number}}
3150 This macro is defined for the platforms with a native 64 bit integer type and
3151 allows to define unsigned 64 bit compile time constants:
3155 unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef);
3159 \wxheading{Include files}
3163 \wxheading{See also}
3165 \helpref{wxLL}{wxll}, \helpref{wxLongLong}{wxlonglong}
3168 \membersection{wxVaCopy}\label{wxvacopy}
3170 \func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{argptrSrc}}
3172 This macro is the same as the standard C99 \texttt{va\_copy} for the compilers
3173 which support it or its replacement for those that don't. It must be used to
3174 preserve the value of a \texttt{va\_list} object if you need to use it after
3175 passing it to another function because it can be modified by the latter.
3177 As with \texttt{va\_start}, each call to \texttt{wxVaCopy} must have a matching
3181 \membersection{::wxWriteResource}\label{wxwriteresource}
3183 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
3184 \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
3186 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
3187 \param{float }{value}, \param{const wxString\& }{file = NULL}}
3189 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
3190 \param{long }{value}, \param{const wxString\& }{file = NULL}}
3192 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
3193 \param{int }{value}, \param{const wxString\& }{file = NULL}}
3195 Writes a resource value into the resource database (for example, WIN.INI, or
3196 .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
3197 otherwise the specified file is used.
3199 Under X, the resource databases are cached until the internal function
3200 \rtfsp{\bf wxFlushResources} is called automatically on exit, when
3201 all updated resource databases are written to their files.
3203 Note that it is considered bad manners to write to the .Xdefaults
3204 file under Unix, although the WIN.INI file is fair game under Windows.
3206 See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
3208 \wxheading{Include files}
3214 \section{Byte order macros}\label{byteordermacros}
3216 The endian-ness issues (that is the difference between big-endian and
3217 little-endian architectures) are important for the portable programs working
3218 with the external binary data (for example, data files or data coming from
3219 network) which is usually in some fixed, platform-independent format. The
3220 macros are helpful for transforming the data to the correct format.
3223 \membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways}
3225 \func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}}
3227 \func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}}
3229 \func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}}
3231 \func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
3233 These macros will swap the bytes of the {\it value} variable from little
3234 endian to big endian or vice versa unconditionally, i.e. independently of the
3238 \membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe}
3240 \func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}}
3242 \func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}}
3244 \func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}}
3246 \func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}}
3248 This macro will swap the bytes of the {\it value} variable from little
3249 endian to big endian or vice versa if the program is compiled on a
3250 big-endian architecture (such as Sun work stations). If the program has
3251 been compiled on a little-endian architecture, the value will be unchanged.
3253 Use these macros to read data from and write data to a file that stores
3254 data in little-endian (for example Intel i386) format.
3257 \membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
3259 \func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}}
3261 \func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}}
3263 \func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}}
3265 \func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}}
3267 This macro will swap the bytes of the {\it value} variable from little
3268 endian to big endian or vice versa if the program is compiled on a
3269 little-endian architecture (such as Intel PCs). If the program has
3270 been compiled on a big-endian architecture, the value will be unchanged.
3272 Use these macros to read data from and write data to a file that stores
3273 data in big-endian format.
3277 \section{RTTI functions}\label{rttimacros}
3279 wxWidgets uses its own RTTI ("run-time type identification") system which
3280 predates the current standard C++ RTTI and so is kept for backwards
3281 compatibility reasons but also because it allows some things which the
3282 standard RTTI doesn't directly support (such as creating a class from its
3285 The standard C++ RTTI can be used in the user code without any problems and in
3286 general you shouldn't need to use the functions and the macros in this section
3287 unless you are thinking of modifying or adding any wxWidgets classes.
3289 \wxheading{See also}
3291 \helpref{RTTI overview}{runtimeclassoverview}
3294 \membersection{CLASSINFO}\label{classinfo}
3296 \func{wxClassInfo *}{CLASSINFO}{className}
3298 Returns a pointer to the wxClassInfo object associated with this class.
3300 \wxheading{Include files}
3305 \membersection{DECLARE\_ABSTRACT\_CLASS}\label{declareabstractclass}
3307 \func{}{DECLARE\_ABSTRACT\_CLASS}{className}
3309 Used inside a class declaration to declare that the class should be
3310 made known to the class hierarchy, but objects of this class cannot be created
3311 dynamically. The same as DECLARE\_CLASS.
3316 class wxCommand: public wxObject
3318 DECLARE_ABSTRACT_CLASS(wxCommand)
3327 \wxheading{Include files}
3332 \membersection{DECLARE\_APP}\label{declareapp}
3334 \func{}{DECLARE\_APP}{className}
3336 This is used in headers to create a forward declaration of the
3337 \helpref{wxGetApp}{wxgetapp} function implemented by
3338 \helpref{IMPLEMENT\_APP}{implementapp}. It creates the declaration
3339 {\tt className\& wxGetApp(void)}.
3347 \wxheading{Include files}
3352 \membersection{DECLARE\_CLASS}\label{declareclass}
3354 \func{}{DECLARE\_CLASS}{className}
3356 Used inside a class declaration to declare that the class should be
3357 made known to the class hierarchy, but objects of this class cannot be created
3358 dynamically. The same as DECLARE\_ABSTRACT\_CLASS.
3360 \wxheading{Include files}
3365 \membersection{DECLARE\_DYNAMIC\_CLASS}\label{declaredynamicclass}
3367 \func{}{DECLARE\_DYNAMIC\_CLASS}{className}
3369 Used inside a class declaration to make the class known to wxWidgets RTTI
3370 system and also declare that the objects of this class should be dynamically
3371 creatable from run-time type information. Notice that this implies that the
3372 class should have a default constructor, if this is not the case consider using
3373 \helpref{DECLARE\_CLASS}{declareclass}.
3378 class wxFrame: public wxWindow
3380 DECLARE_DYNAMIC_CLASS(wxFrame)
3383 const wxString& frameTitle;
3389 \wxheading{Include files}
3394 \membersection{IMPLEMENT\_ABSTRACT\_CLASS}\label{implementabstractclass}
3396 \func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
3398 Used in a C++ implementation file to complete the declaration of
3399 a class that has run-time type information. The same as IMPLEMENT\_CLASS.
3404 IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
3406 wxCommand::wxCommand(void)
3412 \wxheading{Include files}
3417 \membersection{IMPLEMENT\_ABSTRACT\_CLASS2}\label{implementabstractclass2}
3419 \func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
3421 Used in a C++ implementation file to complete the declaration of
3422 a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
3424 \wxheading{Include files}
3429 \membersection{IMPLEMENT\_APP}\label{implementapp}
3431 \func{}{IMPLEMENT\_APP}{className}
3433 This is used in the application class implementation file to make the application class known to
3434 wxWidgets for dynamic construction. You use this instead of
3445 IMPLEMENT_APP(MyApp)
3448 See also \helpref{DECLARE\_APP}{declareapp}.
3450 \wxheading{Include files}
3455 \membersection{IMPLEMENT\_CLASS}\label{implementclass}
3457 \func{}{IMPLEMENT\_CLASS}{className, baseClassName}
3459 Used in a C++ implementation file to complete the declaration of
3460 a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
3462 \wxheading{Include files}
3467 \membersection{IMPLEMENT\_CLASS2}\label{implementclass2}
3469 \func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
3471 Used in a C++ implementation file to complete the declaration of a
3472 class that has run-time type information and two base classes. The
3473 same as IMPLEMENT\_ABSTRACT\_CLASS2.
3475 \wxheading{Include files}
3480 \membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass}
3482 \func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
3484 Used in a C++ implementation file to complete the declaration of
3485 a class that has run-time type information, and whose instances
3486 can be created dynamically.
3491 IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
3493 wxFrame::wxFrame(void)
3499 \wxheading{Include files}
3504 \membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2}
3506 \func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
3508 Used in a C++ implementation file to complete the declaration of
3509 a class that has run-time type information, and whose instances
3510 can be created dynamically. Use this for classes derived from two
3513 \wxheading{Include files}
3518 \membersection{wxConstCast}\label{wxconstcast}
3520 \func{classname *}{wxConstCast}{ptr, classname}
3522 This macro expands into {\tt const\_cast<classname *>(ptr)} if the compiler
3523 supports {\it const\_cast} or into an old, C-style cast, otherwise.
3525 \wxheading{See also}
3527 \helpref{wx\_const\_cast}{wxconstcastraw}\\
3528 \helpref{wxDynamicCast}{wxdynamiccast}\\
3529 \helpref{wxStaticCast}{wxstaticcast}
3532 \membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
3534 \func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
3536 Creates and returns an object of the given class, if the class has been
3537 registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
3540 \membersection{WXDEBUG\_NEW}\label{debugnew}
3542 \func{}{WXDEBUG\_NEW}{arg}
3544 This is defined in debug mode to be call the redefined new operator
3545 with filename and line number arguments. The definition is:
3548 #define WXDEBUG_NEW new(__FILE__,__LINE__)
3551 In non-debug mode, this is defined as the normal new operator.
3553 \wxheading{Include files}
3558 \membersection{wxDynamicCast}\label{wxdynamiccast}
3560 \func{classname *}{wxDynamicCast}{ptr, classname}
3562 This macro returns the pointer {\it ptr} cast to the type {\it classname *} if
3563 the pointer is of this type (the check is done during the run-time) or
3564 {\tt NULL} otherwise. Usage of this macro is preferred over obsoleted
3565 wxObject::IsKindOf() function.
3567 The {\it ptr} argument may be {\tt NULL}, in which case {\tt NULL} will be
3573 wxWindow *win = wxWindow::FindFocus();
3574 wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
3577 // a text control has the focus...
3581 // no window has the focus or it is not a text control
3585 \wxheading{See also}
3587 \helpref{RTTI overview}{runtimeclassoverview}\\
3588 \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
3589 \helpref{wxConstCast}{wxconstcast}\\
3590 \helpref{wxStaticCast}{wxstaticcast}
3593 \membersection{wxDynamicCastThis}\label{wxdynamiccastthis}
3595 \func{classname *}{wxDynamicCastThis}{classname}
3597 This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the
3598 latter provokes spurious compilation warnings from some compilers (because it
3599 tests whether {\tt this} pointer is non {\tt NULL} which is always true), so
3600 this macro should be used to avoid them.
3602 \wxheading{See also}
3604 \helpref{wxDynamicCast}{wxdynamiccast}
3607 \membersection{wxStaticCast}\label{wxstaticcast}
3609 \func{classname *}{wxStaticCast}{ptr, classname}
3611 This macro checks that the cast is valid in debug mode (an assert failure will
3612 result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the
3613 result of executing an equivalent of {\tt static\_cast<classname *>(ptr)}.
3615 \wxheading{See also}
3617 \helpref{wx\_static\_cast}{wxstaticcastraw}\\
3618 \helpref{wxDynamicCast}{wxdynamiccast}\\
3619 \helpref{wxConstCast}{wxconstcast}
3622 \membersection{wx\_const\_cast}\label{wxconstcastraw}
3624 \func{T}{wx\_const\_cast}{T, x}
3626 Same as \texttt{const\_cast<T>(x)} if the compiler supports const cast or
3627 \texttt{(T)x} for old compilers. Unlike \helpref{wxConstCast}{wxconstcast},
3628 the cast it to the type \arg{T} and not to \texttt{T *} and also the order of
3629 arguments is the same as for the standard cast.
3631 \wxheading{See also}
3633 \helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\
3634 \helpref{wx\_static\_cast}{wxstaticcastraw}
3637 \membersection{wx\_reinterpret\_cast}\label{wxreinterpretcastraw}
3639 \func{T}{wx\_reinterpret\_cast}{T, x}
3641 Same as \texttt{reinterpret\_cast<T>(x)} if the compiler supports reinterpret cast or
3642 \texttt{(T)x} for old compilers.
3644 \wxheading{See also}
3646 \helpref{wx\_const\_cast}{wxconstcastraw},\\
3647 \helpref{wx\_static\_cast}{wxstaticcastraw}
3650 \membersection{wx\_static\_cast}\label{wxstaticcastraw}
3652 \func{T}{wx\_static\_cast}{T, x}
3654 Same as \texttt{static\_cast<T>(x)} if the compiler supports static cast or
3655 \texttt{(T)x} for old compilers. Unlike \helpref{wxStaticCast}{wxstaticcast},
3656 there are no checks being done and the meaning of the macro arguments is exactly
3657 the same as for the standard static cast, i.e. \arg{T} is the full type name and
3658 star is not appended to it.
3660 \wxheading{See also}
3662 \helpref{wx\_const\_cast}{wxconstcastraw},\\
3663 \helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}
3667 \section{Log functions}\label{logfunctions}
3669 These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
3670 further information. The functions use (implicitly) the currently active log
3671 target, so their descriptions here may not apply if the log target is not the
3672 standard one (installed by wxWidgets in the beginning of the program).
3674 \wxheading{Include files}
3679 \membersection{::wxDebugMsg}\label{wxdebugmsg}
3681 \func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
3683 {\bf NB:} This function is now obsolete, replaced by \helpref{Log
3684 functions}{logfunctions} and \helpref{wxLogDebug}{wxlogdebug} in particular.
3686 Display a debugging message; under Windows, this will appear on the
3687 debugger command window, and under Unix, it will be written to standard
3690 The syntax is identical to {\bf printf}: pass a format string and a
3691 variable list of arguments.
3693 {\bf Tip:} under Windows, if your application crashes before the
3694 message appears in the debugging window, put a wxYield call after
3695 each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
3696 (at least for Watcom C++): preformat your messages and use OutputDebugString
3699 \wxheading{Include files}
3704 \membersection{::wxError}\label{wxerror}
3706 \func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Internal Error"}}
3708 {\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
3711 Displays {\it msg} and continues. This writes to standard error under
3712 Unix, and pops up a message box under Windows. Used for internal
3713 wxWidgets errors. See also \helpref{wxFatalError}{wxfatalerror}.
3715 \wxheading{Include files}
3720 \membersection{::wxFatalError}\label{wxfatalerror}
3722 \func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Fatal Error"}}
3724 {\bf NB:} This function is now obsolete, please use
3725 \helpref{wxLogFatalError}{wxlogfatalerror} instead.
3727 Displays {\it msg} and exits. This writes to standard error under Unix,
3728 and pops up a message box under Windows. Used for fatal internal
3729 wxWidgets errors. See also \helpref{wxError}{wxerror}.
3731 \wxheading{Include files}
3736 \membersection{::wxLogError}\label{wxlogerror}
3738 \func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}}
3740 \func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3742 The functions to use for error messages, i.e. the messages that must be shown
3743 to the user. The default processing is to pop up a message box to inform the
3747 \membersection{::wxLogFatalError}\label{wxlogfatalerror}
3749 \func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}}
3751 \func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3753 Like \helpref{wxLogError}{wxlogerror}, but also
3754 terminates the program with the exit code 3. Using {\it abort()} standard
3755 function also terminates the program with this exit code.
3758 \membersection{::wxLogWarning}\label{wxlogwarning}
3760 \func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}}
3762 \func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3764 For warnings - they are also normally shown to the user, but don't interrupt
3768 \membersection{::wxLogMessage}\label{wxlogmessage}
3770 \func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}}
3772 \func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3774 For all normal, informational messages. They also appear in a message box by
3775 default (but it can be changed).
3777 \membersection{::wxLogVerbose}\label{wxlogverbose}
3779 \func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}}
3781 \func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3783 For verbose output. Normally, it is suppressed, but
3784 might be activated if the user wishes to know more details about the program
3785 progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
3788 \membersection{::wxLogStatus}\label{wxlogstatus}
3790 \func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}}
3792 \func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
3794 \func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}}
3796 \func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3798 Messages logged by these functions will appear in the statusbar of the {\it
3799 frame} or of the top level application window by default (i.e. when using
3800 the second version of the functions).
3802 If the target frame doesn't have a statusbar, the message will be lost.
3805 \membersection{::wxLogSysError}\label{wxlogsyserror}
3807 \func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}}
3809 \func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3811 Mostly used by wxWidgets itself, but might be handy for logging errors after
3812 system call (API function) failure. It logs the specified message text as well
3813 as the last system error code ({\it errno} or {\it ::GetLastError()} depending
3814 on the platform) and the corresponding error message. The second form
3815 of this function takes the error code explicitly as the first argument.
3817 \wxheading{See also}
3819 \helpref{wxSysErrorCode}{wxsyserrorcode},
3820 \helpref{wxSysErrorMsg}{wxsyserrormsg}
3823 \membersection{::wxLogDebug}\label{wxlogdebug}
3825 \func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}}
3827 \func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3829 The right functions for debug output. They only do something in debug
3830 mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) and expand to
3831 nothing in release mode (otherwise).
3834 \membersection{::wxLogTrace}\label{wxlogtrace}
3836 \func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}}
3838 \func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3840 \func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
3842 \func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
3844 \func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
3846 \func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
3848 As {\bf wxLogDebug}, trace functions only do something in debug build and
3849 expand to nothing in the release one. The reason for making
3850 it a separate function from it is that usually there are a lot of trace
3851 messages, so it might make sense to separate them from other debug messages.
3853 The trace messages also usually can be separated into different categories and
3854 the second and third versions of this function only log the message if the
3855 {\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This
3856 allows to selectively trace only some operations and not others by changing
3857 the value of the trace mask (possible during the run-time).
3859 For the second function (taking a string mask), the message is logged only if
3860 the mask has been previously enabled by the call to
3861 \helpref{AddTraceMask}{wxlogaddtracemask} or by setting
3862 \helpref{{\tt WXTRACE} environment variable}{envvars}.
3863 The predefined string trace masks
3864 used by wxWidgets are:
3866 \begin{itemize}\itemsep=0pt
3867 \item wxTRACE\_MemAlloc: trace memory allocation (new/delete)
3868 \item wxTRACE\_Messages: trace window messages/X callbacks
3869 \item wxTRACE\_ResAlloc: trace GDI resource allocation
3870 \item wxTRACE\_RefCount: trace various ref counting operations
3871 \item wxTRACE\_OleCalls: trace OLE method calls (Win32 only)
3874 {\bf Caveats:} since both the mask and the format string are strings,
3875 this might lead to function signature confusion in some cases:
3876 if you intend to call the format string only version of wxLogTrace,
3877 then add a \%s format string parameter and then supply a second string parameter for that \%s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function.
3878 In this case you'll unfortunately have to avoid having two leading
3879 string parameters, e.g. by adding a bogus integer (with its \%d format string).
3881 The third version of the function only logs the message if all the bits
3882 corresponding to the {\it mask} are set in the wxLog trace mask which can be
3883 set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less
3884 flexible than the previous one because it doesn't allow defining the user
3885 trace masks easily - this is why it is deprecated in favour of using string
3888 \begin{itemize}\itemsep=0pt
3889 \item wxTraceMemAlloc: trace memory allocation (new/delete)
3890 \item wxTraceMessages: trace window messages/X callbacks
3891 \item wxTraceResAlloc: trace GDI resource allocation
3892 \item wxTraceRefCount: trace various ref counting operations
3893 \item wxTraceOleCalls: trace OLE method calls (Win32 only)
3897 \membersection{::wxSafeShowMessage}\label{wxsafeshowmessage}
3899 \func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}}
3901 This function shows a message to the user in a safe way and should be safe to
3902 call even before the application has been initialized or if it is currently in
3903 some other strange state (for example, about to crash). Under Windows this
3904 function shows a message box using a native dialog instead of
3905 \helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere
3906 it simply prints the message to the standard output using the title as prefix.
3908 \wxheading{Parameters}
3910 \docparam{title}{The title of the message box shown to the user or the prefix
3911 of the message string}
3913 \docparam{text}{The text to show to the user}
3915 \wxheading{See also}
3917 \helpref{wxLogFatalError}{wxlogfatalerror}
3919 \wxheading{Include files}
3924 \membersection{::wxSysErrorCode}\label{wxsyserrorcode}
3926 \func{unsigned long}{wxSysErrorCode}{\void}
3928 Returns the error code from the last system call. This function uses
3929 {\tt errno} on Unix platforms and {\tt GetLastError} under Win32.
3931 \wxheading{See also}
3933 \helpref{wxSysErrorMsg}{wxsyserrormsg},
3934 \helpref{wxLogSysError}{wxlogsyserror}
3937 \membersection{::wxSysErrorMsg}\label{wxsyserrormsg}
3939 \func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}}
3941 Returns the error message corresponding to the given system error code. If
3942 {\it errCode} is $0$ (default), the last error code (as returned by
3943 \helpref{wxSysErrorCode}{wxsyserrorcode}) is used.
3945 \wxheading{See also}
3947 \helpref{wxSysErrorCode}{wxsyserrorcode},
3948 \helpref{wxLogSysError}{wxlogsyserror}
3951 \membersection{WXTRACE}\label{trace}
3953 \wxheading{Include files}
3957 \func{}{WXTRACE}{formatString, ...}
3959 {\bf NB:} This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
3961 Calls wxTrace with printf-style variable argument syntax. Output
3962 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
3964 \wxheading{Include files}
3969 \membersection{WXTRACELEVEL}\label{tracelevel}
3971 \func{}{WXTRACELEVEL}{level, formatString, ...}
3973 {\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
3975 Calls wxTraceLevel with printf-style variable argument syntax. Output
3976 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
3977 The first argument should be the level at which this information is appropriate.
3978 It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
3981 \wxheading{Include files}
3986 \membersection{::wxTrace}\label{wxtrace}
3988 \func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
3990 {\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
3992 Takes printf-style variable argument syntax. Output
3993 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
3995 \wxheading{Include files}
4000 \membersection{::wxTraceLevel}\label{wxtracelevel}
4002 \func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
4004 {\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
4006 Takes printf-style variable argument syntax. Output
4007 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
4008 The first argument should be the level at which this information is appropriate.
4009 It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
4012 \wxheading{Include files}
4018 \section{Time functions}\label{timefunctions}
4020 The functions in this section deal with getting the current time and
4021 starting/stopping the global timers. Please note that the timer functions are
4022 deprecated because they work with one global timer only and
4023 \helpref{wxTimer}{wxtimer} and/or \helpref{wxStopWatch}{wxstopwatch} classes
4024 should be used instead. For retrieving the current time, you may also use
4025 \helpref{wxDateTime::Now}{wxdatetimenow} or
4026 \helpref{wxDateTime::UNow}{wxdatetimeunow} methods.
4029 \membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
4031 \func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = true}}
4033 Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
4035 If {\it resetTimer} is true (the default), the timer is reset to zero
4038 See also \helpref{wxTimer}{wxtimer}.
4040 \wxheading{Include files}
4045 \membersection{::wxGetLocalTime}\label{wxgetlocaltime}
4047 \func{long}{wxGetLocalTime}{\void}
4049 Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
4051 \wxheading{See also}
4053 \helpref{wxDateTime::Now}{wxdatetimenow}
4055 \wxheading{Include files}
4060 \membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis}
4062 \func{wxLongLong}{wxGetLocalTimeMillis}{\void}
4064 Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
4066 \wxheading{See also}
4068 \helpref{wxDateTime::Now}{wxdatetimenow},\\
4069 \helpref{wxLongLong}{wxlonglong}
4071 \wxheading{Include files}
4076 \membersection{::wxGetUTCTime}\label{wxgetutctime}
4078 \func{long}{wxGetUTCTime}{\void}
4080 Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
4082 \wxheading{See also}
4084 \helpref{wxDateTime::Now}{wxdatetimenow}
4086 \wxheading{Include files}
4091 \membersection{::wxMicroSleep}\label{wxmicrosleep}
4093 \func{void}{wxMicroSleep}{\param{unsigned long}{ microseconds}}
4095 Sleeps for the specified number of microseconds. The microsecond resolution may
4096 not, in fact, be available on all platforms (currently only Unix platforms with
4097 nanosleep(2) may provide it) in which case this is the same as
4098 \helpref{wxMilliSleep}{wxmillisleep}(\arg{microseconds}$/1000$).
4100 \wxheading{Include files}
4105 \membersection{::wxMilliSleep}\label{wxmillisleep}
4107 \func{void}{wxMilliSleep}{\param{unsigned long}{ milliseconds}}
4109 Sleeps for the specified number of milliseconds. Notice that usage of this
4110 function is encouraged instead of calling usleep(3) directly because the
4111 standard usleep() function is not MT safe.
4113 \wxheading{Include files}
4118 \membersection{::wxNow}\label{wxnow}
4120 \func{wxString}{wxNow}{\void}
4122 Returns a string representing the current date and time.
4124 \wxheading{Include files}
4129 \membersection{::wxSleep}\label{wxsleep}
4131 \func{void}{wxSleep}{\param{int}{ secs}}
4133 Sleeps for the specified number of seconds.
4135 \wxheading{Include files}
4140 \membersection{::wxStartTimer}\label{wxstarttimer}
4142 \func{void}{wxStartTimer}{\void}
4144 Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
4146 See also \helpref{wxTimer}{wxtimer}.
4148 \wxheading{Include files}
4153 \membersection{::wxUsleep}\label{wxusleep}
4155 \func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
4157 This function is deprecated because its name is misleading: notice that the
4158 argument is in milliseconds, not microseconds. Please use either
4159 \helpref{wxMilliSleep}{wxmillisleep} or \helpref{wxMicroSleep}{wxmicrosleep}
4160 depending on the resolution you need.
4164 \section{Debugging macros and functions}\label{debugmacros}
4166 Useful macros and functions for error checking and defensive programming.
4167 wxWidgets defines three families of the assert-like macros:
4168 the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined
4169 (in other words, in the debug build) but disappear completely in the release
4170 build. On the other hand, the wxCHECK macros stay event in release builds but a
4171 check failure doesn't generate any user-visible effects then. Finally, the
4172 compile time assertions don't happen during the run-time but result in the
4173 compilation error messages if the condition they check fail.
4175 \wxheading{Include files}
4180 \membersection{::wxOnAssert}\label{wxonassert}
4182 \func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{cond}, \param{const char *}{msg = NULL}}
4184 This function is called whenever one of debugging macros fails (i.e. condition
4185 is false in an assertion). It is only defined in the debug mode, in release
4186 builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything.
4188 To override the default behaviour in the debug builds which is to show the user
4189 a dialog asking whether he wants to abort the program, continue or continue
4190 ignoring any subsequent assert failures, you may override
4191 \helpref{wxApp::OnAssert}{wxapponassert} which is called by this function if
4192 the global application object exists.
4195 \membersection{wxASSERT}\label{wxassert}
4197 \func{}{wxASSERT}{\param{}{condition}}
4199 Assert macro. An error message will be generated if the condition is false in
4200 debug mode, but nothing will be done in the release build.
4202 Please note that the condition in wxASSERT() should have no side effects
4203 because it will not be executed in release mode at all.
4205 \wxheading{See also}
4207 \helpref{wxASSERT\_MSG}{wxassertmsg},\\
4208 \helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
4211 \membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize}
4213 \func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
4215 This macro results in a
4216 \helpref{compile time assertion failure}{wxcompiletimeassert} if the size
4217 of the given type {\it type} is less than {\it size} bits.
4219 You may use it like this, for example:
4222 // we rely on the int being able to hold values up to 2^32
4223 wxASSERT_MIN_BITSIZE(int, 32);
4225 // can't work with the platforms using UTF-8 for wchar_t
4226 wxASSERT_MIN_BITSIZE(wchar_t, 16);
4230 \membersection{wxASSERT\_MSG}\label{wxassertmsg}
4232 \func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
4234 Assert macro with message. An error message will be generated if the condition is false.
4236 \wxheading{See also}
4238 \helpref{wxASSERT}{wxassert},\\
4239 \helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
4242 \membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert}
4244 \func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
4246 Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the
4247 specified {\it condition} is false. The compiler error message should include
4248 the {\it msg} identifier - please note that it must be a valid C++ identifier
4249 and not a string unlike in the other cases.
4251 This macro is mostly useful for testing the expressions involving the
4252 {\tt sizeof} operator as they can't be tested by the preprocessor but it is
4253 sometimes desirable to test them at the compile time.
4255 Note that this macro internally declares a struct whose name it tries to make
4256 unique by using the {\tt \_\_LINE\_\_} in it but it may still not work if you
4257 use it on the same line in two different source files. In this case you may
4258 either change the line in which either of them appears on or use the
4259 \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} macro.
4261 Also note that Microsoft Visual C++ has a bug which results in compiler errors
4262 if you use this macro with `Program Database For Edit And Continue'
4263 (\texttt{/ZI}) option, so you shouldn't use it (`Program Database'
4264 (\texttt{/Zi}) is ok though) for the code making use of this macro.
4266 \wxheading{See also}
4268 \helpref{wxASSERT\_MSG}{wxassertmsg},\\
4269 \helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}
4272 \membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2}
4274 \func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}}
4276 This macro is identical to \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}
4277 except that it allows you to specify a unique {\it name} for the struct
4278 internally defined by this macro to avoid getting the compilation errors
4279 described \helpref{above}{wxcompiletimeassert}.
4282 \membersection{wxFAIL}\label{wxfail}
4284 \func{}{wxFAIL}{\void}
4286 Will always generate an assert error if this code is reached (in debug mode).
4288 See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
4291 \membersection{wxFAIL\_MSG}\label{wxfailmsg}
4293 \func{}{wxFAIL\_MSG}{\param{}{msg}}
4295 Will always generate an assert error with specified message if this code is reached (in debug mode).
4297 This macro is useful for marking unreachable" code areas, for example
4298 it may be used in the "default:" branch of a switch statement if all possible
4299 cases are processed above.
4301 \wxheading{See also}
4303 \helpref{wxFAIL}{wxfail}
4306 \membersection{wxCHECK}\label{wxcheck}
4308 \func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
4310 Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
4311 This check is done even in release mode.
4314 \membersection{wxCHECK\_MSG}\label{wxcheckmsg}
4316 \func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
4318 Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
4319 This check is done even in release mode.
4321 This macro may be only used in non void functions, see also
4322 \helpref{wxCHECK\_RET}{wxcheckret}.
4325 \membersection{wxCHECK\_RET}\label{wxcheckret}
4327 \func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}}
4329 Checks that the condition is true, and returns if not (FAILs with given error
4330 message in debug mode). This check is done even in release mode.
4332 This macro should be used in void functions instead of
4333 \helpref{wxCHECK\_MSG}{wxcheckmsg}.
4336 \membersection{wxCHECK2}\label{wxcheck2}
4338 \func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}}
4340 Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute
4341 {\it operation} if it is not. This is a generalisation of
4342 \helpref{wxCHECK}{wxcheck} and may be used when something else than just
4343 returning from the function must be done when the {\it condition} is false.
4345 This check is done even in release mode.
4348 \membersection{wxCHECK2\_MSG}\label{wxcheck2msg}
4350 \func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}}
4352 This is the same as \helpref{wxCHECK2}{wxcheck2}, but
4353 \helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
4354 instead of wxFAIL() if the {\it condition} is false.
4357 \membersection{::wxTrap}\label{wxtrap}
4359 \func{void}{wxTrap}{\void}
4361 In debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) this function generates a
4362 debugger exception meaning that the control is passed to the debugger if one is
4363 attached to the process. Otherwise the program just terminates abnormally.
4365 In release mode this function does nothing.
4367 \wxheading{Include files}
4373 \membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning}
4375 \func{bool}{wxIsDebuggerRunning}{\void}
4377 Returns \true if the program is running under debugger, \false otherwise.
4379 Please note that this function is currently only implemented for Win32 and Mac
4380 builds using CodeWarrior and always returns \false elsewhere.
4385 \section{Environment access functions}\label{environfunctions}
4387 The functions in this section allow to access (get) or change value of
4388 environment variables in a portable way. They are currently implemented under
4389 Win32 and POSIX-like systems (Unix).
4391 % TODO add some stuff about env var inheriting but not propagating upwards (VZ)
4393 \wxheading{Include files}
4398 \membersection{wxGetenv}\label{wxgetenvmacro}
4400 \func{wxChar *}{wxGetEnv}{\param{const wxString\&}{ var}}
4402 This is a macro defined as {\tt getenv()} or its wide char version in Unicode
4405 Note that under Win32 it may not return correct value for the variables set
4406 with \helpref{wxSetEnv}{wxsetenv}, use \helpref{wxGetEnv}{wxgetenv} function
4410 \membersection{wxGetEnv}\label{wxgetenv}
4412 \func{bool}{wxGetEnv}{\param{const wxString\&}{ var}, \param{wxString *}{value}}
4414 Returns the current value of the environment variable {\it var} in {\it value}.
4415 {\it value} may be {\tt NULL} if you just want to know if the variable exists
4416 and are not interested in its value.
4418 Returns \true if the variable exists, \false otherwise.
4421 \membersection{wxSetEnv}\label{wxsetenv}
4423 \func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxChar *}{value}}
4425 Sets the value of the environment variable {\it var} (adding it if necessary)
4428 Returns \true on success.
4431 \membersection{wxUnsetEnv}\label{wxunsetenv}
4433 \func{bool}{wxUnsetEnv}{\param{const wxString\&}{ var}}
4435 Removes the variable {\it var} from the environment.
4436 \helpref{wxGetEnv}{wxgetenv} will return {\tt NULL} after the call to this
4439 Returns \true on success.