| 1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 2 | %% Name: function.tex |
| 3 | %% Purpose: Functions and macros |
| 4 | %% Author: wxWidgets Team |
| 5 | %% Modified by: |
| 6 | %% Created: |
| 7 | %% RCS-ID: $Id$ |
| 8 | %% Copyright: (c) wxWidgets Team |
| 9 | %% License: wxWindows license |
| 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 11 | |
| 12 | \chapter{Functions}\label{functions} |
| 13 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% |
| 14 | \setfooter{\thepage}{}{}{}{}{\thepage} |
| 15 | |
| 16 | The functions and macros defined in wxWidgets are described here: you can |
| 17 | either look up a function using the alphabetical listing of them or find it in |
| 18 | the corresponding topic. |
| 19 | |
| 20 | \section{Alphabetical functions and macros list}\label{functionsalphabetically} |
| 21 | |
| 22 | \helpref{CLASSINFO}{classinfo}\\ |
| 23 | \helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\ |
| 24 | \helpref{DECLARE\_APP}{declareapp}\\ |
| 25 | \helpref{DECLARE\_CLASS}{declareclass}\\ |
| 26 | \helpref{DECLARE\_DYNAMIC\_CLASS}{declaredynamicclass}\\ |
| 27 | \helpref{IMPLEMENT\_ABSTRACT\_CLASS2}{implementabstractclass2}\\ |
| 28 | \helpref{IMPLEMENT\_ABSTRACT\_CLASS}{implementabstractclass}\\ |
| 29 | \helpref{IMPLEMENT\_APP}{implementapp}\\ |
| 30 | \helpref{IMPLEMENT\_CLASS2}{implementclass2}\\ |
| 31 | \helpref{IMPLEMENT\_CLASS}{implementclass}\\ |
| 32 | \helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\ |
| 33 | \helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\ |
| 34 | \helpref{wxAboutBox}{wxaboutbox}\\ |
| 35 | \helpref{wxASSERT}{wxassert}\\ |
| 36 | \helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\ |
| 37 | \helpref{wxASSERT\_MSG}{wxassertmsg}\\ |
| 38 | \helpref{wxAtomicDec}{wxatomicdec}\\ |
| 39 | \helpref{wxAtomicInc}{wxatomicinc}\\ |
| 40 | \helpref{wxBase64Decode}{wxbase64decode}\\ |
| 41 | \helpref{wxBase64Encode}{wxbase64encode}\\ |
| 42 | \helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\ |
| 43 | \helpref{wxBell}{wxbell}\\ |
| 44 | \helpref{wxBITMAP}{wxbitmapmacro}\\ |
| 45 | \helpref{wxCHANGE\_UMASK}{wxchangeumask}\\ |
| 46 | \helpref{wxCHECK}{wxcheck}\\ |
| 47 | \helpref{wxCHECK2\_MSG}{wxcheck2msg}\\ |
| 48 | \helpref{wxCHECK2}{wxcheck2}\\ |
| 49 | \helpref{wxCHECK\_GCC\_VERSION}{wxcheckgccversion}\\ |
| 50 | \helpref{wxCHECK\_MSG}{wxcheckmsg}\\ |
| 51 | \helpref{wxCHECK\_RET}{wxcheckret}\\ |
| 52 | \helpref{wxCHECK\_SUNCC\_VERSION}{wxchecksunccversion}\\ |
| 53 | \helpref{wxCHECK\_VERSION}{wxcheckversion}\\ |
| 54 | \helpref{wxCHECK\_VERSION\_FULL}{wxcheckversionfull}\\ |
| 55 | \helpref{wxCHECK\_W32API\_VERSION}{wxcheckw32apiversion}\\ |
| 56 | \helpref{wxClientDisplayRect}{wxclientdisplayrect}\\ |
| 57 | \helpref{wxClipboardOpen}{functionwxclipboardopen}\\ |
| 58 | \helpref{wxCloseClipboard}{wxcloseclipboard}\\ |
| 59 | \helpref{wxColourDisplay}{wxcolourdisplay}\\ |
| 60 | \helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\ |
| 61 | \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}\\ |
| 62 | \helpref{wxCONCAT}{wxconcat}\\ |
| 63 | \helpref{wxConcatFiles}{wxconcatfiles}\\ |
| 64 | \helpref{wxConstCast}{wxconstcast}\\ |
| 65 | \helpref{wxCopyFile}{wxcopyfile}\\ |
| 66 | \helpref{wxCreateDynamicObject}{wxcreatedynamicobject}\\ |
| 67 | \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider}\\ |
| 68 | \helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}\\ |
| 69 | \helpref{wxCRIT\_SECT\_DECLARE\_MEMBER}{wxcritsectdeclaremember}\\ |
| 70 | \helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}\\ |
| 71 | \helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro}\\ % wxcs already taken! |
| 72 | \helpref{wxDDECleanUp}{wxddecleanup}\\ |
| 73 | \helpref{wxDDEInitialize}{wxddeinitialize}\\ |
| 74 | \helpref{wxDROP\_ICON}{wxdropicon}\\ |
| 75 | \helpref{wxDebugMsg}{wxdebugmsg}\\ |
| 76 | \helpref{WXDEBUG\_NEW}{debugnew}\\ |
| 77 | \helpref{wxDEPRECATED}{wxdeprecated}\\ |
| 78 | \helpref{wxDEPRECATED\_BUT\_USED\_INTERNALLY}{wxdeprecatedbutusedinternally}\\ |
| 79 | \helpref{wxDEPRECATED\_INLINE}{wxdeprecatedinline}\\ |
| 80 | \helpref{wxDirExists}{functionwxdirexists}\\ |
| 81 | \helpref{wxDirSelector}{wxdirselector}\\ |
| 82 | \helpref{wxDisplayDepth}{wxdisplaydepth}\\ |
| 83 | \helpref{wxDisplaySize}{wxdisplaysize}\\ |
| 84 | \helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\ |
| 85 | \helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\ |
| 86 | \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\ |
| 87 | \helpref{wxDynamicCast}{wxdynamiccast}\\ |
| 88 | \helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}\\ |
| 89 | \helpref{wxEmptyClipboard}{wxemptyclipboard}\\ |
| 90 | \helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\ |
| 91 | \helpref{wxEndBusyCursor}{wxendbusycursor}\\ |
| 92 | \helpref{wxENTER\_CRIT\_SECT}{wxentercritsect}\\ |
| 93 | \helpref{wxEntry}{wxentry}\\ |
| 94 | \helpref{wxEntryStart}{wxentrystart}\\ |
| 95 | \helpref{wxEntryCleanup}{wxentrycleanup}\\ |
| 96 | \helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\ |
| 97 | \helpref{wxError}{wxerror}\\ |
| 98 | \helpref{wxExecute}{wxexecute}\\ |
| 99 | \helpref{wxExit}{wxexit}\\ |
| 100 | \helpref{wxEXPLICIT}{wxexplicit}\\ |
| 101 | \helpref{wxFAIL\_MSG}{wxfailmsg}\\ |
| 102 | \helpref{wxFAIL}{wxfail}\\ |
| 103 | \helpref{wxFatalError}{wxfatalerror}\\ |
| 104 | \helpref{wxFileExists}{functionwxfileexists}\\ |
| 105 | \helpref{wxFileModificationTime}{wxfilemodificationtime}\\ |
| 106 | \helpref{wxFileNameFromPath}{wxfilenamefrompath}\\ |
| 107 | \helpref{wxFileSelector}{wxfileselector}\\ |
| 108 | \helpref{wxFindFirstFile}{wxfindfirstfile}\\ |
| 109 | \helpref{wxFindMenuItemId}{wxfindmenuitemid}\\ |
| 110 | \helpref{wxFindNextFile}{wxfindnextfile}\\ |
| 111 | \helpref{wxFindWindowAtPointer}{wxfindwindowatpointer}\\ |
| 112 | \helpref{wxFindWindowAtPoint}{wxfindwindowatpoint}\\ |
| 113 | \helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\ |
| 114 | \helpref{wxFindWindowByName}{wxfindwindowbyname}\\ |
| 115 | \helpref{wxFinite}{wxfinite}\\ |
| 116 | \helpref{wxGenericAboutBox}{wxgenericaboutbox}\\ |
| 117 | \helpref{wxGetActiveWindow}{wxgetactivewindow}\\ |
| 118 | \helpref{wxGetApp}{wxgetapp}\\ |
| 119 | \helpref{wxGetBatteryState}{wxgetbatterystate}\\ |
| 120 | \helpref{wxGetClipboardData}{wxgetclipboarddata}\\ |
| 121 | \helpref{wxGetClipboardFormatName}{wxgetclipboardformatname}\\ |
| 122 | \helpref{wxGetColourFromUser}{wxgetcolourfromuser}\\ |
| 123 | \helpref{wxGetCwd}{wxgetcwd}\\ |
| 124 | \helpref{wxGetDiskSpace}{wxgetdiskspace}\\ |
| 125 | \helpref{wxGetDisplayName}{wxgetdisplayname}\\ |
| 126 | \helpref{wxGetDisplaySize}{wxdisplaysize}\\ |
| 127 | \helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\ |
| 128 | \helpref{wxGetEmailAddress}{wxgetemailaddress}\\ |
| 129 | \helpref{wxGetEnv}{wxgetenv}\\ |
| 130 | \helpref{wxGetFileKind}{wxgetfilekind}\\ |
| 131 | \helpref{wxGetFontFromUser}{wxgetfontfromuser}\\ |
| 132 | \helpref{wxGetFreeMemory}{wxgetfreememory}\\ |
| 133 | \helpref{wxGetFullHostName}{wxgetfullhostname}\\ |
| 134 | \helpref{wxGetHomeDir}{wxgethomedir}\\ |
| 135 | \helpref{wxGetHostName}{wxgethostname}\\ |
| 136 | \helpref{wxGetKeyState}{wxgetkeystate}\\ |
| 137 | \helpref{wxGetLocalTimeMillis}{wxgetlocaltimemillis}\\ |
| 138 | \helpref{wxGetLocalTime}{wxgetlocaltime}\\ |
| 139 | \helpref{wxGetMousePosition}{wxgetmouseposition}\\ |
| 140 | \helpref{wxGetMouseState}{wxgetmousestate}\\ |
| 141 | \helpref{wxGetMultipleChoices}{wxgetmultiplechoices}\\ |
| 142 | \helpref{wxGetNumberFromUser}{wxgetnumberfromuser}\\ |
| 143 | \helpref{wxGetOSDirectory}{wxgetosdirectory}\\ |
| 144 | \helpref{wxGetOsDescription}{wxgetosdescription}\\ |
| 145 | \helpref{wxGetOsVersion}{wxgetosversion}\\ |
| 146 | \helpref{wxGetPasswordFromUser}{wxgetpasswordfromuser}\\ |
| 147 | \helpref{wxGetPowerType}{wxgetpowertype}\\ |
| 148 | \helpref{wxGetPrinterCommand}{wxgetprintercommand}\\ |
| 149 | \helpref{wxGetPrinterFile}{wxgetprinterfile}\\ |
| 150 | \helpref{wxGetPrinterMode}{wxgetprintermode}\\ |
| 151 | \helpref{wxGetPrinterOptions}{wxgetprinteroptions}\\ |
| 152 | \helpref{wxGetPrinterOrientation}{wxgetprinterorientation}\\ |
| 153 | \helpref{wxGetPrinterPreviewCommand}{wxgetprinterpreviewcommand}\\ |
| 154 | \helpref{wxGetPrinterScaling}{wxgetprinterscaling}\\ |
| 155 | \helpref{wxGetPrinterTranslation}{wxgetprintertranslation}\\ |
| 156 | \helpref{wxGetProcessId}{wxgetprocessid}\\ |
| 157 | \helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\ |
| 158 | \helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\ |
| 159 | \helpref{wxGetSingleChoice}{wxgetsinglechoice}\\ |
| 160 | \helpref{wxGetTempFileName}{wxgettempfilename}\\ |
| 161 | \helpref{wxGetTextFromUser}{wxgettextfromuser}\\ |
| 162 | \helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\ |
| 163 | \helpref{wxGetTranslation}{wxgettranslation}\\ |
| 164 | \helpref{wxGetUTCTime}{wxgetutctime}\\ |
| 165 | \helpref{wxGetUserHome}{wxgetuserhome}\\ |
| 166 | \helpref{wxGetUserId}{wxgetuserid}\\ |
| 167 | \helpref{wxGetUserName}{wxgetusername}\\ |
| 168 | \helpref{wxGetWorkingDirectory}{wxgetworkingdirectory}\\ |
| 169 | \helpref{wxGetenv}{wxgetenvmacro}\\ |
| 170 | \helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\ |
| 171 | \helpref{wxICON}{wxiconmacro}\\ |
| 172 | \helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\ |
| 173 | \helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\ |
| 174 | \helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\ |
| 175 | \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}\\ |
| 176 | \helpref{wxInitialize}{wxinitialize}\\ |
| 177 | \helpref{wxIsAbsolutePath}{wxisabsolutepath}\\ |
| 178 | \helpref{wxIsBusy}{wxisbusy}\\ |
| 179 | \helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\ |
| 180 | \helpref{wxIsDebuggerRunning}{wxisdebuggerrunning}\\ |
| 181 | \helpref{wxIsEmpty}{wxisempty}\\ |
| 182 | \helpref{wxIsMainThread}{wxismainthread}\\ |
| 183 | \helpref{wxIsNaN}{wxisnan}\\ |
| 184 | \helpref{wxIsPlatformLittleEndian}{wxisplatformlittleendian}\\ |
| 185 | \helpref{wxIsPlatform64Bit}{wxisplatform64bit}\\ |
| 186 | \helpref{wxIsWild}{wxiswild}\\ |
| 187 | \helpref{wxJoin}{wxjoin}\\ |
| 188 | \helpref{wxKill}{wxkill}\\ |
| 189 | \helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser}\\ |
| 190 | \helpref{wxLEAVE\_CRIT\_SECT}{wxleavecritsect}\\ |
| 191 | \helpref{wxLoadUserResource}{wxloaduserresource}\\ |
| 192 | \helpref{wxLogDebug}{wxlogdebug}\\ |
| 193 | \helpref{wxLogError}{wxlogerror}\\ |
| 194 | \helpref{wxLogFatalError}{wxlogfatalerror}\\ |
| 195 | \helpref{wxLogMessage}{wxlogmessage}\\ |
| 196 | \helpref{wxLogStatus}{wxlogstatus}\\ |
| 197 | \helpref{wxLogSysError}{wxlogsyserror}\\ |
| 198 | \helpref{wxLogTrace}{wxlogtrace}\\ |
| 199 | \helpref{wxLogVerbose}{wxlogverbose}\\ |
| 200 | \helpref{wxLogWarning}{wxlogwarning}\\ |
| 201 | \helpref{wxLL}{wxll}\\ |
| 202 | \helpref{wxLongLongFmtSpec}{wxlonglongfmtspec}\\ |
| 203 | \helpref{wxMakeMetafilePlaceable}{wxmakemetafileplaceable}\\ |
| 204 | \helpref{wxMatchWild}{wxmatchwild}\\ |
| 205 | \helpref{wxMessageBox}{wxmessagebox}\\ |
| 206 | \helpref{wxMilliSleep}{wxmillisleep}\\ |
| 207 | \helpref{wxMicroSleep}{wxmicrosleep}\\ |
| 208 | \helpref{wxMkdir}{wxmkdir}\\ |
| 209 | \helpref{wxMutexGuiEnter}{wxmutexguienter}\\ |
| 210 | \helpref{wxMutexGuiLeave}{wxmutexguileave}\\ |
| 211 | \helpref{wxNewId}{wxnewid}\\ |
| 212 | \helpref{wxNow}{wxnow}\\ |
| 213 | \helpref{wxOnAssert}{wxonassert}\\ |
| 214 | \helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}\\ |
| 215 | \helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}\\ |
| 216 | \helpref{wxOpenClipboard}{wxopenclipboard}\\ |
| 217 | \helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\ |
| 218 | \helpref{wxPathOnly}{wxpathonly}\\ |
| 219 | \helpref{wxPLURAL}{wxplural}\\ |
| 220 | \helpref{wxPostDelete}{wxpostdelete}\\ |
| 221 | \helpref{wxPostEvent}{wxpostevent}\\ |
| 222 | \helpref{wxRegisterClipboardFormat}{wxregisterclipboardformat}\\ |
| 223 | \helpref{wxRegisterId}{wxregisterid}\\ |
| 224 | \helpref{wxRemoveFile}{wxremovefile}\\ |
| 225 | \helpref{wxRenameFile}{wxrenamefile}\\ |
| 226 | \helpref{wxRmdir}{wxrmdir}\\ |
| 227 | \helpref{wxSafeShowMessage}{wxsafeshowmessage}\\ |
| 228 | \helpref{wxSafeYield}{wxsafeyield}\\ |
| 229 | \helpref{wxSetClipboardData}{wxsetclipboarddata}\\ |
| 230 | \helpref{wxSetCursor}{wxsetcursor}\\ |
| 231 | \helpref{wxSetDisplayName}{wxsetdisplayname}\\ |
| 232 | \helpref{wxSetEnv}{wxsetenv}\\ |
| 233 | \helpref{wxSetPrinterCommand}{wxsetprintercommand}\\ |
| 234 | \helpref{wxSetPrinterFile}{wxsetprinterfile}\\ |
| 235 | \helpref{wxSetPrinterMode}{wxsetprintermode}\\ |
| 236 | \helpref{wxSetPrinterOptions}{wxsetprinteroptions}\\ |
| 237 | \helpref{wxSetPrinterOrientation}{wxsetprinterorientation}\\ |
| 238 | \helpref{wxSetPrinterPreviewCommand}{wxsetprinterpreviewcommand}\\ |
| 239 | \helpref{wxSetPrinterScaling}{wxsetprinterscaling}\\ |
| 240 | \helpref{wxSetPrinterTranslation}{wxsetprintertranslation}\\ |
| 241 | \helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\ |
| 242 | \helpref{wxShell}{wxshell}\\ |
| 243 | \helpref{wxShowTip}{wxshowtip}\\ |
| 244 | \helpref{wxShutdown}{wxshutdown}\\ |
| 245 | \helpref{wxSleep}{wxsleep}\\ |
| 246 | \helpref{wxSnprintf}{wxsnprintf}\\ |
| 247 | \helpref{wxSplit}{wxsplit}\\ |
| 248 | \helpref{wxSplitPath}{wxsplitfunction}\\ |
| 249 | \helpref{wxStaticCast}{wxstaticcast}\\ |
| 250 | \helpref{wxStrcmp}{wxstrcmp}\\ |
| 251 | \helpref{wxStricmp}{wxstricmp}\\ |
| 252 | \helpref{wxStringEq}{wxstringeq}\\ |
| 253 | \helpref{wxStringMatch}{wxstringmatch}\\ |
| 254 | \helpref{wxStringTokenize}{wxstringtokenize}\\ |
| 255 | \helpref{wxStripMenuCodes}{wxstripmenucodes}\\ |
| 256 | \helpref{wxStrlen}{wxstrlen}\\ |
| 257 | \helpref{wxSTRINGIZE}{wxstringize}\\ |
| 258 | \helpref{wxSTRINGIZE\_T}{wxstringizet}\\ |
| 259 | \helpref{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{wxsuppressgccprivatedtorwarning}\\ |
| 260 | \helpref{wxSysErrorCode}{wxsyserrorcode}\\ |
| 261 | \helpref{wxSysErrorMsg}{wxsyserrormsg}\\ |
| 262 | \helpref{wxT}{wxt}\\ |
| 263 | \helpref{wxTrace}{wxtrace}\\ |
| 264 | \helpref{WXTRACE}{trace}\\ |
| 265 | \helpref{wxTraceLevel}{wxtracelevel}\\ |
| 266 | \helpref{WXTRACELEVEL}{tracelevel}\\ |
| 267 | \helpref{wxTransferFileToStream}{wxtransferfiletostream}\\ |
| 268 | \helpref{wxTransferStreamToFile}{wxtransferstreamtofile}\\ |
| 269 | \helpref{wxTrap}{wxtrap}\\ |
| 270 | \helpref{wxULL}{wxull}\\ |
| 271 | \helpref{wxUninitialize}{wxuninitialize}\\ |
| 272 | \helpref{wxUnix2DosFilename}{wxunix2dosfilename}\\ |
| 273 | \helpref{wxUnsetEnv}{wxunsetenv}\\ |
| 274 | \helpref{wxUsleep}{wxusleep}\\ |
| 275 | \helpref{wxVaCopy}{wxvacopy}\\ |
| 276 | \helpref{wxVsnprintf}{wxvsnprintf}\\ |
| 277 | \helpref{wxWakeUpIdle}{wxwakeupidle}\\ |
| 278 | \helpref{wxYield}{wxyield}\\ |
| 279 | \helpref{wx\_const\_cast}{wxconstcastraw}\\ |
| 280 | \helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\ |
| 281 | \helpref{wx\_static\_cast}{wxstaticcastraw}\\ |
| 282 | \helpref{wx\_truncate\_cast}{wxtruncatecast}\\ |
| 283 | \helpref{\_}{underscore}\\ |
| 284 | \helpref{\_T}{underscoret} |
| 285 | \helpref{\_\_WXFUNCTION\_\_}{wxfunction} |
| 286 | |
| 287 | |
| 288 | |
| 289 | \section{Version macros}\label{versionfunctions} |
| 290 | |
| 291 | The following constants are defined in wxWidgets: |
| 292 | |
| 293 | \begin{itemize}\itemsep=0pt |
| 294 | \item {\tt wxMAJOR\_VERSION} is the major version of wxWidgets |
| 295 | \item {\tt wxMINOR\_VERSION} is the minor version of wxWidgets |
| 296 | \item {\tt wxRELEASE\_NUMBER} is the release number |
| 297 | \item {\tt wxSUBRELEASE\_NUMBER} is the subrelease number which is $0$ for all |
| 298 | official releases |
| 299 | \end{itemize} |
| 300 | |
| 301 | For example, the values or these constants for wxWidgets 2.1.15 are 2, 1 and |
| 302 | 15. |
| 303 | |
| 304 | Additionally, {\tt wxVERSION\_STRING} is a user-readable string containing |
| 305 | the full wxWidgets version and {\tt wxVERSION\_NUMBER} is a combination of the |
| 306 | three version numbers above: for 2.1.15, it is 2115 and it is 2200 for |
| 307 | wxWidgets 2.2. |
| 308 | |
| 309 | The subrelease number is only used for the sources in between official releases |
| 310 | and so normally is not useful. |
| 311 | |
| 312 | \wxheading{Include files} |
| 313 | |
| 314 | <wx/version.h> or <wx/defs.h> |
| 315 | |
| 316 | |
| 317 | \membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion} |
| 318 | |
| 319 | \func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor}} |
| 320 | |
| 321 | Returns $1$ if the compiler being used to compile the code is GNU C++ |
| 322 | compiler (g++) version major.minor or greater. Otherwise, and also if |
| 323 | the compiler is not GNU C++ at all, returns $0$. |
| 324 | |
| 325 | |
| 326 | \membersection{wxCHECK\_SUNCC\_VERSION}\label{wxchecksunccversion} |
| 327 | |
| 328 | \func{bool}{wxCHECK\_SUNCC\_VERSION}{\param{}{major, minor}} |
| 329 | |
| 330 | Returns $1$ if the compiler being used to compile the code is Sun CC Pro |
| 331 | compiler and its version is at least \texttt{major.minor}. Otherwise returns |
| 332 | $0$. |
| 333 | |
| 334 | |
| 335 | \membersection{wxCHECK\_VERSION}\label{wxcheckversion} |
| 336 | |
| 337 | \func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}} |
| 338 | |
| 339 | This is a macro which evaluates to true if the current wxWidgets version is at |
| 340 | least major.minor.release. |
| 341 | |
| 342 | For example, to test if the program is compiled with wxWidgets 2.2 or higher, |
| 343 | the following can be done: |
| 344 | |
| 345 | \begin{verbatim} |
| 346 | wxString s; |
| 347 | #if wxCHECK_VERSION(2, 2, 0) |
| 348 | if ( s.StartsWith("foo") ) |
| 349 | #else // replacement code for old version |
| 350 | if ( strncmp(s, "foo", 3) == 0 ) |
| 351 | #endif |
| 352 | { |
| 353 | ... |
| 354 | } |
| 355 | \end{verbatim} |
| 356 | |
| 357 | |
| 358 | \membersection{wxCHECK\_VERSION\_FULL}\label{wxcheckversionfull} |
| 359 | |
| 360 | \func{bool}{wxCHECK\_VERSION\_FULL}{\param{}{major, minor, release, subrel}} |
| 361 | |
| 362 | Same as \helpref{wxCHECK\_VERSION}{wxcheckversion} but also checks that |
| 363 | \texttt{wxSUBRELEASE\_NUMBER} is at least \arg{subrel}. |
| 364 | |
| 365 | |
| 366 | \membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion} |
| 367 | |
| 368 | \func{bool}{wxCHECK\_W32API\_VERSION}{\param{}{major, minor, release}} |
| 369 | |
| 370 | Returns $1$ if the version of w32api headers used is major.minor.release or |
| 371 | greater. Otherwise, and also if we are not compiling with mingw32/cygwin under |
| 372 | Win32 at all, returns $0$. |
| 373 | |
| 374 | |
| 375 | |
| 376 | \section{Application initialization and termination}\label{appinifunctions} |
| 377 | |
| 378 | The functions in this section are used on application startup/shutdown and also |
| 379 | to control the behaviour of the main event loop of the GUI programs. |
| 380 | |
| 381 | |
| 382 | \membersection{::wxEntry}\label{wxentry} |
| 383 | |
| 384 | This initializes wxWidgets in a platform-dependent way. Use this if you are not |
| 385 | using the default wxWidgets entry code (e.g. main or WinMain). For example, you |
| 386 | can initialize wxWidgets from an Microsoft Foundation Classes application using |
| 387 | this function. |
| 388 | |
| 389 | The following overload of wxEntry is available under all platforms: |
| 390 | |
| 391 | \func{int}{wxEntry}{\param{int\&}{ argc}, \param{wxChar **}{argv}} |
| 392 | |
| 393 | Under MS Windows, an additional overload suitable for calling from |
| 394 | \texttt{WinMain} is available: |
| 395 | |
| 396 | \func{int}{wxEntry}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}} |
| 397 | |
| 398 | (notice that under Windows CE platform, and only there, the type of |
| 399 | \arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in |
| 400 | Unicode build). |
| 401 | |
| 402 | \wxheading{See also} |
| 403 | |
| 404 | \helpref{wxEntryStart}{wxentrystart} |
| 405 | |
| 406 | \wxheading{Remarks} |
| 407 | |
| 408 | To clean up wxWidgets, call wxApp::OnExit followed by the static function |
| 409 | wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWidgets: |
| 410 | |
| 411 | \begin{verbatim} |
| 412 | int CTheApp::ExitInstance() |
| 413 | { |
| 414 | // OnExit isn't called by CleanUp so must be called explicitly. |
| 415 | wxTheApp->OnExit(); |
| 416 | wxApp::CleanUp(); |
| 417 | |
| 418 | return CWinApp::ExitInstance(); |
| 419 | } |
| 420 | \end{verbatim} |
| 421 | |
| 422 | \wxheading{Include files} |
| 423 | |
| 424 | <wx/app.h> |
| 425 | |
| 426 | |
| 427 | |
| 428 | \membersection{::wxEntryCleanup}\label{wxentrycleanup} |
| 429 | |
| 430 | \func{void}{wxEntryCleanup}{\void} |
| 431 | |
| 432 | Free resources allocated by a successful call to \helpref{wxEntryStart}{wxentrystart}. |
| 433 | |
| 434 | \wxheading{Include files} |
| 435 | |
| 436 | <wx/init.h> |
| 437 | |
| 438 | |
| 439 | \membersection{::wxEntryStart}\label{wxentrystart} |
| 440 | |
| 441 | \func{bool}{wxEntryStart}{\param{int\&}{ argc}, \param{wxChar **}{argv}} |
| 442 | |
| 443 | This function can be used to perform the initialization of wxWidgets if you |
| 444 | can't use the default initialization code for any reason. |
| 445 | |
| 446 | If the function returns \true, the initialization was successful and the global |
| 447 | \helpref{wxApp}{wxapp} object \texttt{wxTheApp} has been created. Moreover, |
| 448 | \helpref{wxEntryCleanup}{wxentrycleanup} must be called afterwards. If the |
| 449 | function returns \false, a catastrophic initialization error occured and (at |
| 450 | least the GUI part of) the library can't be used at all. |
| 451 | |
| 452 | Notice that parameters \arg{argc} and \arg{argv} may be modified by this |
| 453 | function. |
| 454 | |
| 455 | An additional overload of wxEntryStart() is provided under MSW only: it is |
| 456 | meant to be called with the parameters passed to \texttt{WinMain()}. |
| 457 | |
| 458 | \func{bool}{wxEntryStart}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}} |
| 459 | |
| 460 | (notice that under Windows CE platform, and only there, the type of |
| 461 | \arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in |
| 462 | Unicode build). |
| 463 | |
| 464 | \wxheading{Include files} |
| 465 | |
| 466 | <wx/init.h> |
| 467 | |
| 468 | |
| 469 | \membersection{::wxGetApp}\label{wxgetapp} |
| 470 | |
| 471 | \func{wxAppDerivedClass\&}{wxGetApp}{\void} |
| 472 | |
| 473 | This function doesn't exist in wxWidgets but it is created by using |
| 474 | the \helpref{IMPLEMENT\_APP}{implementapp} macro. Thus, before using it |
| 475 | anywhere but in the same module where this macro is used, you must make it |
| 476 | available using \helpref{DECLARE\_APP}{declareapp}. |
| 477 | |
| 478 | The advantage of using this function compared to directly using the global |
| 479 | wxTheApp pointer is that the latter is of type {\tt wxApp *} and so wouldn't |
| 480 | allow you to access the functions specific to your application class but not |
| 481 | present in wxApp while wxGetApp() returns the object of the right type. |
| 482 | |
| 483 | |
| 484 | \membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions} |
| 485 | |
| 486 | \func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = true}} |
| 487 | |
| 488 | If {\it doIt} is true, the fatal exceptions (also known as general protection |
| 489 | faults under Windows or segmentation violations in the Unix world) will be |
| 490 | caught and passed to \helpref{wxApp::OnFatalException}{wxapponfatalexception}. |
| 491 | By default, i.e. before this function is called, they will be handled in the |
| 492 | normal way which usually just means that the application will be terminated. |
| 493 | Calling wxHandleFatalExceptions() with {\it doIt} equal to false will restore |
| 494 | this default behaviour. |
| 495 | |
| 496 | |
| 497 | \membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers} |
| 498 | |
| 499 | \func{void}{wxInitAllImageHandlers}{\void} |
| 500 | |
| 501 | Initializes all available image handlers. For a list of available handlers, |
| 502 | see \helpref{wxImage}{wximage}. |
| 503 | |
| 504 | \wxheading{See also} |
| 505 | |
| 506 | \helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler} |
| 507 | |
| 508 | \wxheading{Include files} |
| 509 | |
| 510 | <wx/image.h> |
| 511 | |
| 512 | |
| 513 | \membersection{::wxInitialize}\label{wxinitialize} |
| 514 | |
| 515 | \func{bool}{wxInitialize}{\void} |
| 516 | |
| 517 | This function is used in wxBase only and only if you don't create |
| 518 | \helpref{wxApp}{wxapp} object at all. In this case you must call it from your |
| 519 | {\tt main()} function before calling any other wxWidgets functions. |
| 520 | |
| 521 | If the function returns \false the initialization could not be performed, |
| 522 | in this case the library cannot be used and |
| 523 | \helpref{wxUninitialize}{wxuninitialize} shouldn't be called neither. |
| 524 | |
| 525 | This function may be called several times but |
| 526 | \helpref{wxUninitialize}{wxuninitialize} must be called for each successful |
| 527 | call to this function. |
| 528 | |
| 529 | \wxheading{Include files} |
| 530 | |
| 531 | <wx/app.h> |
| 532 | |
| 533 | |
| 534 | \membersection{::wxSafeYield}\label{wxsafeyield} |
| 535 | |
| 536 | \func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}, \param{bool}{ |
| 537 | onlyIfNeeded = false}} |
| 538 | |
| 539 | This function is similar to wxYield, except that it disables the user input to |
| 540 | all program windows before calling wxYield and re-enables it again |
| 541 | afterwards. If {\it win} is not NULL, this window will remain enabled, |
| 542 | allowing the implementation of some limited user interaction. |
| 543 | |
| 544 | Returns the result of the call to \helpref{::wxYield}{wxyield}. |
| 545 | |
| 546 | \wxheading{Include files} |
| 547 | |
| 548 | <wx/utils.h> |
| 549 | |
| 550 | |
| 551 | \membersection{::wxUninitialize}\label{wxuninitialize} |
| 552 | |
| 553 | \func{void}{wxUninitialize}{\void} |
| 554 | |
| 555 | This function is for use in console (wxBase) programs only. It must be called |
| 556 | once for each previous successful call to \helpref{wxInitialize}{wxinitialize}. |
| 557 | |
| 558 | \wxheading{Include files} |
| 559 | |
| 560 | <wx/app.h> |
| 561 | |
| 562 | |
| 563 | \membersection{::wxYield}\label{wxyield} |
| 564 | |
| 565 | \func{bool}{wxYield}{\void} |
| 566 | |
| 567 | Calls \helpref{wxApp::Yield}{wxappyield}. |
| 568 | |
| 569 | This function is kept only for backwards compatibility. Please use |
| 570 | the \helpref{wxApp::Yield}{wxappyield} method instead in any new code. |
| 571 | |
| 572 | \wxheading{Include files} |
| 573 | |
| 574 | <wx/app.h> or <wx/utils.h> |
| 575 | |
| 576 | |
| 577 | \membersection{::wxWakeUpIdle}\label{wxwakeupidle} |
| 578 | |
| 579 | \func{void}{wxWakeUpIdle}{\void} |
| 580 | |
| 581 | This functions wakes up the (internal and platform dependent) idle system, i.e. it |
| 582 | will force the system to send an idle event even if the system currently {\it is} |
| 583 | idle and thus would not send any idle event until after some other event would get |
| 584 | sent. This is also useful for sending events between two threads and is used by |
| 585 | the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and |
| 586 | \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}. |
| 587 | |
| 588 | \wxheading{Include files} |
| 589 | |
| 590 | <wx/app.h> |
| 591 | |
| 592 | |
| 593 | |
| 594 | \section{Process control functions}\label{processfunctions} |
| 595 | |
| 596 | The functions in this section are used to launch or terminate the other |
| 597 | processes. |
| 598 | |
| 599 | |
| 600 | \membersection{::wxExecute}\label{wxexecute} |
| 601 | |
| 602 | \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} |
| 603 | |
| 604 | \perlnote{In wxPerl this function is called \texttt{Wx::ExecuteCommand}} |
| 605 | |
| 606 | \func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} |
| 607 | |
| 608 | \perlnote{In wxPerl this function is called \texttt{Wx::ExecuteArgs}} |
| 609 | |
| 610 | \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{int }{flags = 0}} |
| 611 | |
| 612 | \perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdout} and it |
| 613 | only takes the {\tt command} argument, |
| 614 | and returns a 2-element list {\tt ( status, output )}, where {\tt output} is |
| 615 | an array reference.} |
| 616 | |
| 617 | \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}, \param{int }{flags = 0}} |
| 618 | |
| 619 | \perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdoutStderr} |
| 620 | and it only takes the {\tt command} argument, |
| 621 | and returns a 3-element list {\tt ( status, output, errors )}, where |
| 622 | {\tt output} and {\tt errors} are array references.} |
| 623 | |
| 624 | Executes another program in Unix or Windows. |
| 625 | |
| 626 | The first form takes a command string, such as {\tt "emacs file.txt"}. |
| 627 | |
| 628 | The second form takes an array of values: a command, any number of |
| 629 | arguments, terminated by NULL. |
| 630 | |
| 631 | The semantics of the third and fourth versions is different from the first two |
| 632 | and is described in more details below. |
| 633 | |
| 634 | If {\it flags} parameter contains {\tt wxEXEC\_ASYNC} flag (the default), flow |
| 635 | of control immediately returns. If it contains {\tt wxEXEC\_SYNC}, the current |
| 636 | application waits until the other program has terminated. |
| 637 | |
| 638 | In the case of synchronous execution, the return value is the exit code of |
| 639 | the process (which terminates by the moment the function returns) and will be |
| 640 | $-1$ if the process couldn't be started and typically 0 if the process |
| 641 | terminated successfully. Also, while waiting for the process to |
| 642 | terminate, wxExecute will call \helpref{wxYield}{wxyield}. Because of this, by |
| 643 | default this function disables all application windows to avoid unexpected |
| 644 | reentrancies which could result from the users interaction with the program |
| 645 | while the child process is running. If you are sure that it is safe to not |
| 646 | disable the program windows, you may pass \texttt{wxEXEC\_NODISABLE} flag to |
| 647 | prevent this automatic disabling from happening. |
| 648 | |
| 649 | For asynchronous execution, however, the return value is the process id and |
| 650 | zero value indicates that the command could not be executed. As an added |
| 651 | complication, the return value of $-1$ in this case indicates that we didn't |
| 652 | launch a new process, but connected to the running one (this can only happen in |
| 653 | case of using DDE under Windows for command execution). In particular, in this, |
| 654 | and only this, case the calling code will not get the notification about |
| 655 | process termination. |
| 656 | |
| 657 | If callback isn't NULL and if execution is asynchronous, |
| 658 | \helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when |
| 659 | the process finishes. Specifying this parameter also allows you to redirect the |
| 660 | standard input and/or output of the process being launched by calling |
| 661 | \helpref{Redirect}{wxprocessredirect}. If the child process IO is redirected, |
| 662 | under Windows the process window is not shown by default (this avoids having to |
| 663 | flush an unnecessary console for the processes which don't create any windows |
| 664 | anyhow) but a {\tt wxEXEC\_NOHIDE} flag can be used to prevent this from |
| 665 | happening, i.e. with this flag the child process window will be shown normally. |
| 666 | |
| 667 | Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure |
| 668 | that the new process is a group leader (this will create a new session if |
| 669 | needed). Calling \helpref{wxKill}{wxkill} passing wxKILL\_CHILDREN will |
| 670 | kill this process as well as all of its children (except those which have |
| 671 | started their own session). |
| 672 | |
| 673 | The {\tt wxEXEC\_NOEVENTS} flag prevents processing of any events from taking |
| 674 | place while the child process is running. It should be only used for very |
| 675 | short-lived processes as otherwise the application windows risk becoming |
| 676 | unresponsive from the users point of view. As this flag only makes sense with |
| 677 | {\tt wxEXEC\_SYNC}, {\tt wxEXEC\_BLOCK} equal to the sum of both of these flags |
| 678 | is provided as a convenience. |
| 679 | |
| 680 | Finally, you may use the third overloaded version of this function to execute |
| 681 | a process (always synchronously, the contents of \arg{flags} is or'd with |
| 682 | \texttt{wxEXEC\_SYNC}) and capture its output in the array \arg{output}. The |
| 683 | fourth version adds the possibility to additionally capture the messages from |
| 684 | standard error output in the \arg{errors} array. |
| 685 | |
| 686 | {\bf NB:} Currently wxExecute() can only be used from the main thread, calling |
| 687 | this function from another thread will result in an assert failure in debug |
| 688 | build and won't work. |
| 689 | |
| 690 | \wxheading{See also} |
| 691 | |
| 692 | \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, \helpref{Exec sample}{sampleexec}. |
| 693 | |
| 694 | \wxheading{Parameters} |
| 695 | |
| 696 | \docparam{command}{The command to execute and any parameters to pass to it as a |
| 697 | single string.} |
| 698 | |
| 699 | \docparam{argv}{The command to execute should be the first element of this |
| 700 | array, any additional ones are the command parameters and the array must be |
| 701 | terminated with a NULL pointer.} |
| 702 | |
| 703 | \docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},\rtfsp |
| 704 | {\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}} |
| 705 | |
| 706 | \docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}} |
| 707 | |
| 708 | \wxheading{Include files} |
| 709 | |
| 710 | <wx/utils.h> |
| 711 | |
| 712 | |
| 713 | \membersection{::wxExit}\label{wxexit} |
| 714 | |
| 715 | \func{void}{wxExit}{\void} |
| 716 | |
| 717 | Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}. |
| 718 | Should only be used in an emergency: normally the top-level frame |
| 719 | should be deleted (after deleting all other frames) to terminate the |
| 720 | application. See \helpref{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp}. |
| 721 | |
| 722 | \wxheading{Include files} |
| 723 | |
| 724 | <wx/app.h> |
| 725 | |
| 726 | |
| 727 | \membersection{::wxJoin}\label{wxjoin} |
| 728 | |
| 729 | \func{wxString}{wxJoin}{\param{const wxArrayString\&}{ arr}, \param{const wxChar}{ sep}, \param{const wxChar}{ escape = '$\backslash$'}} |
| 730 | |
| 731 | Concatenate all lines of the given \helpref{wxArrayString}{wxarraystring} object using the separator \arg{sep} and returns |
| 732 | the result as a \helpref{wxString}{wxstring}. |
| 733 | |
| 734 | If the \arg{escape} character is non-\NULL, then it's used as prefix for each occurrence of \arg{sep} |
| 735 | in the strings contained in \arg{arr} before joining them which is necessary |
| 736 | in order to be able to recover the original array contents from the string |
| 737 | later using \helpref{wxSplit}{wxsplit}. |
| 738 | |
| 739 | \wxheading{Include files} |
| 740 | |
| 741 | <wx/arrstr.h> |
| 742 | |
| 743 | |
| 744 | \membersection{::wxKill}\label{wxkill} |
| 745 | |
| 746 | \func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}, \param{int }{flags = 0}} |
| 747 | |
| 748 | Equivalent to the Unix kill function: send the given signal {\it sig} to the |
| 749 | process with PID {\it pid}. The valid signal values are |
| 750 | |
| 751 | \begin{verbatim} |
| 752 | enum wxSignal |
| 753 | { |
| 754 | wxSIGNONE = 0, // verify if the process exists under Unix |
| 755 | wxSIGHUP, |
| 756 | wxSIGINT, |
| 757 | wxSIGQUIT, |
| 758 | wxSIGILL, |
| 759 | wxSIGTRAP, |
| 760 | wxSIGABRT, |
| 761 | wxSIGEMT, |
| 762 | wxSIGFPE, |
| 763 | wxSIGKILL, // forcefully kill, dangerous! |
| 764 | wxSIGBUS, |
| 765 | wxSIGSEGV, |
| 766 | wxSIGSYS, |
| 767 | wxSIGPIPE, |
| 768 | wxSIGALRM, |
| 769 | wxSIGTERM // terminate the process gently |
| 770 | }; |
| 771 | \end{verbatim} |
| 772 | |
| 773 | {\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning |
| 774 | under both Unix and Windows but all the other signals are equivalent to |
| 775 | {\tt wxSIGTERM} under Windows. |
| 776 | |
| 777 | Returns 0 on success, -1 on failure. If {\it rc} parameter is not NULL, it will |
| 778 | be filled with an element of {\tt wxKillError} enum: |
| 779 | |
| 780 | \begin{verbatim} |
| 781 | enum wxKillError |
| 782 | { |
| 783 | wxKILL_OK, // no error |
| 784 | wxKILL_BAD_SIGNAL, // no such signal |
| 785 | wxKILL_ACCESS_DENIED, // permission denied |
| 786 | wxKILL_NO_PROCESS, // no such process |
| 787 | wxKILL_ERROR // another, unspecified error |
| 788 | }; |
| 789 | \end{verbatim} |
| 790 | |
| 791 | The {\it flags} parameter can be wxKILL\_NOCHILDREN (the default), |
| 792 | or wxKILL\_CHILDREN, in which case the child processes of this |
| 793 | process will be killed too. Note that under Unix, for wxKILL\_CHILDREN |
| 794 | to work you should have created the process by passing wxEXEC\_MAKE\_GROUP\_LEADER |
| 795 | to wxExecute. |
| 796 | |
| 797 | \wxheading{See also} |
| 798 | |
| 799 | \helpref{wxProcess::Kill}{wxprocesskill},\rtfsp |
| 800 | \helpref{wxProcess::Exists}{wxprocessexists},\rtfsp |
| 801 | \helpref{Exec sample}{sampleexec} |
| 802 | |
| 803 | \wxheading{Include files} |
| 804 | |
| 805 | <wx/utils.h> |
| 806 | |
| 807 | |
| 808 | \membersection{::wxGetProcessId}\label{wxgetprocessid} |
| 809 | |
| 810 | \func{unsigned long}{wxGetProcessId}{\void} |
| 811 | |
| 812 | Returns the number uniquely identifying the current process in the system. |
| 813 | |
| 814 | If an error occurs, $0$ is returned. |
| 815 | |
| 816 | \wxheading{Include files} |
| 817 | |
| 818 | <wx/utils.h> |
| 819 | |
| 820 | |
| 821 | \membersection{::wxShell}\label{wxshell} |
| 822 | |
| 823 | \func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} |
| 824 | |
| 825 | Executes a command in an interactive shell window. If no command is |
| 826 | specified, then just the shell is spawned. |
| 827 | |
| 828 | See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}. |
| 829 | |
| 830 | \wxheading{Include files} |
| 831 | |
| 832 | <wx/utils.h> |
| 833 | |
| 834 | |
| 835 | \membersection{::wxShutdown}\label{wxshutdown} |
| 836 | |
| 837 | \func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}} |
| 838 | |
| 839 | This function shuts down or reboots the computer depending on the value of the |
| 840 | {\it flags}. Please notice that doing this requires the corresponding access |
| 841 | rights (superuser under Unix, {\tt SE\_SHUTDOWN} privilege under Windows NT) |
| 842 | and that this function is only implemented under Unix and Win32. |
| 843 | |
| 844 | \wxheading{Parameters} |
| 845 | |
| 846 | \docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}} |
| 847 | |
| 848 | \wxheading{Returns} |
| 849 | |
| 850 | \true on success, \false if an error occurred. |
| 851 | |
| 852 | \wxheading{Include files} |
| 853 | |
| 854 | <wx/utils.h> |
| 855 | |
| 856 | |
| 857 | |
| 858 | \section{Thread functions}\label{threadfunctions} |
| 859 | |
| 860 | The functions and macros here mainly exist to make it writing the code which |
| 861 | may be compiled in multi thread build ({\tt wxUSE\_THREADS} $= 1$) as well as |
| 862 | in single thread configuration ({\tt wxUSE\_THREADS} $= 0$). |
| 863 | |
| 864 | For example, a static variable must be protected against simultaneous access by |
| 865 | multiple threads in the former configuration but in the latter the extra |
| 866 | overhead of using the critical section is not needed. To solve this problem, |
| 867 | the \helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro} macro may be used |
| 868 | to create and use the critical section only when needed. |
| 869 | |
| 870 | \wxheading{Include files} |
| 871 | |
| 872 | <wx/thread.h> |
| 873 | |
| 874 | \wxheading{See also} |
| 875 | |
| 876 | \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview} |
| 877 | |
| 878 | |
| 879 | |
| 880 | \membersection{wxCRIT\_SECT\_DECLARE}\label{wxcritsectdeclare} |
| 881 | |
| 882 | \func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} |
| 883 | |
| 884 | This macro declares a (static) critical section object named {\it cs} if |
| 885 | {\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. |
| 886 | |
| 887 | |
| 888 | |
| 889 | \membersection{wxCRIT\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember} |
| 890 | |
| 891 | \func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} |
| 892 | |
| 893 | This macro declares a critical section object named {\it cs} if |
| 894 | {\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. As it doesn't |
| 895 | include the {\tt static} keyword (unlike |
| 896 | \helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}), it can be used to declare |
| 897 | a class or struct member which explains its name. |
| 898 | |
| 899 | |
| 900 | |
| 901 | \membersection{wxCRIT\_SECT\_LOCKER}\label{wxcritsectlocker} |
| 902 | |
| 903 | \func{}{wxCRIT\_SECT\_LOCKER}{\param{}{name}, \param{}{cs}} |
| 904 | |
| 905 | This macro creates a \helpref{critical section lock}{wxcriticalsectionlocker} |
| 906 | object named {\it name} and associated with the critical section {\it cs} if |
| 907 | {\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. |
| 908 | |
| 909 | |
| 910 | |
| 911 | \membersection{wxCRITICAL\_SECTION}\label{wxcriticalsectionmacro} |
| 912 | |
| 913 | \func{}{wxCRITICAL\_SECTION}{\param{}{name}} |
| 914 | |
| 915 | This macro combines \helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare} and |
| 916 | \helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}: it creates a static critical |
| 917 | section object and also the lock object associated with it. Because of this, it |
| 918 | can be only used inside a function, not at global scope. For example: |
| 919 | |
| 920 | \begin{verbatim} |
| 921 | int IncCount() |
| 922 | { |
| 923 | static int s_counter = 0; |
| 924 | |
| 925 | wxCRITICAL_SECTION(counter); |
| 926 | |
| 927 | return ++s_counter; |
| 928 | } |
| 929 | \end{verbatim} |
| 930 | |
| 931 | (note that we suppose that the function is called the first time from the main |
| 932 | thread so that the critical section object is initialized correctly by the time |
| 933 | other threads start calling it, if this is not the case this approach can |
| 934 | {\bf not} be used and the critical section must be made a global instead). |
| 935 | |
| 936 | |
| 937 | |
| 938 | \membersection{wxENTER\_CRIT\_SECT}\label{wxentercritsect} |
| 939 | |
| 940 | \func{}{wxENTER\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} |
| 941 | |
| 942 | This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if |
| 943 | {\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. |
| 944 | |
| 945 | |
| 946 | |
| 947 | \membersection{::wxIsMainThread}\label{wxismainthread} |
| 948 | |
| 949 | \func{bool}{wxIsMainThread}{\void} |
| 950 | |
| 951 | Returns \true if this thread is the main one. Always returns \true if |
| 952 | {\tt wxUSE\_THREADS} is $0$. |
| 953 | |
| 954 | |
| 955 | |
| 956 | \membersection{wxLEAVE\_CRIT\_SECT}\label{wxleavecritsect} |
| 957 | |
| 958 | \func{}{wxLEAVE\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} |
| 959 | |
| 960 | This macro is equivalent to \helpref{cs.Leave()}{wxcriticalsectionleave} if |
| 961 | {\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. |
| 962 | |
| 963 | |
| 964 | |
| 965 | \membersection{::wxMutexGuiEnter}\label{wxmutexguienter} |
| 966 | |
| 967 | \func{void}{wxMutexGuiEnter}{\void} |
| 968 | |
| 969 | This function must be called when any thread other than the main GUI thread |
| 970 | wants to get access to the GUI library. This function will block the execution |
| 971 | of the calling thread until the main thread (or any other thread holding the |
| 972 | main GUI lock) leaves the GUI library and no other thread will enter the GUI |
| 973 | library until the calling thread calls \helpref{::wxMutexGuiLeave()}{wxmutexguileave}. |
| 974 | |
| 975 | Typically, these functions are used like this: |
| 976 | |
| 977 | \begin{verbatim} |
| 978 | void MyThread::Foo(void) |
| 979 | { |
| 980 | // before doing any GUI calls we must ensure that this thread is the only |
| 981 | // one doing it! |
| 982 | |
| 983 | wxMutexGuiEnter(); |
| 984 | |
| 985 | // Call GUI here: |
| 986 | my_window->DrawSomething(); |
| 987 | |
| 988 | wxMutexGuiLeave(); |
| 989 | } |
| 990 | \end{verbatim} |
| 991 | |
| 992 | Note that under GTK, no creation of top-level windows is allowed in any |
| 993 | thread but the main one. |
| 994 | |
| 995 | This function is only defined on platforms which support preemptive |
| 996 | threads. |
| 997 | |
| 998 | |
| 999 | \membersection{::wxMutexGuiLeave}\label{wxmutexguileave} |
| 1000 | |
| 1001 | \func{void}{wxMutexGuiLeave}{\void} |
| 1002 | |
| 1003 | See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}. |
| 1004 | |
| 1005 | This function is only defined on platforms which support preemptive |
| 1006 | threads. |
| 1007 | |
| 1008 | |
| 1009 | |
| 1010 | \section{File functions}\label{filefunctions} |
| 1011 | |
| 1012 | \wxheading{Include files} |
| 1013 | |
| 1014 | <wx/filefn.h> |
| 1015 | |
| 1016 | \wxheading{See also} |
| 1017 | |
| 1018 | \helpref{wxPathList}{wxpathlist}\\ |
| 1019 | \helpref{wxDir}{wxdir}\\ |
| 1020 | \helpref{wxFile}{wxfile}\\ |
| 1021 | \helpref{wxFileName}{wxfilename} |
| 1022 | |
| 1023 | |
| 1024 | \membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename} |
| 1025 | |
| 1026 | \func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}} |
| 1027 | |
| 1028 | Converts a DOS to a Unix filename by replacing backslashes with forward |
| 1029 | slashes. |
| 1030 | |
| 1031 | |
| 1032 | \membersection{::wxFileExists}\label{functionwxfileexists} |
| 1033 | |
| 1034 | \func{bool}{wxFileExists}{\param{const wxString\& }{filename}} |
| 1035 | |
| 1036 | Returns true if the file exists and is a plain file. |
| 1037 | |
| 1038 | |
| 1039 | \membersection{::wxFileModificationTime}\label{wxfilemodificationtime} |
| 1040 | |
| 1041 | \func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}} |
| 1042 | |
| 1043 | Returns time of last modification of given file. |
| 1044 | |
| 1045 | The function returns \texttt{(time\_t)}$-1$ if an error occurred (e.g. file not |
| 1046 | found). |
| 1047 | |
| 1048 | |
| 1049 | \membersection{::wxFileNameFromPath}\label{wxfilenamefrompath} |
| 1050 | |
| 1051 | \func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} |
| 1052 | |
| 1053 | \func{char *}{wxFileNameFromPath}{\param{char *}{path}} |
| 1054 | |
| 1055 | {\bf NB:} This function is obsolete, please use |
| 1056 | \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. |
| 1057 | |
| 1058 | Returns the filename for a full path. The second form returns a pointer to |
| 1059 | temporary storage that should not be deallocated. |
| 1060 | |
| 1061 | |
| 1062 | \membersection{::wxFindFirstFile}\label{wxfindfirstfile} |
| 1063 | |
| 1064 | \func{wxString}{wxFindFirstFile}{\param{const wxString\& }{spec}, \param{int}{ flags = 0}} |
| 1065 | |
| 1066 | This function does directory searching; returns the first file |
| 1067 | that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to |
| 1068 | get the next matching file. Neither will report the current directory "." or the |
| 1069 | parent directory "..". |
| 1070 | |
| 1071 | \wxheading{Warning} |
| 1072 | |
| 1073 | 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. |
| 1074 | |
| 1075 | {\it spec} may contain wildcards. |
| 1076 | |
| 1077 | {\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either. |
| 1078 | |
| 1079 | For example: |
| 1080 | |
| 1081 | \begin{verbatim} |
| 1082 | wxString f = wxFindFirstFile("/home/project/*.*"); |
| 1083 | while ( !f.empty() ) |
| 1084 | { |
| 1085 | ... |
| 1086 | f = wxFindNextFile(); |
| 1087 | } |
| 1088 | \end{verbatim} |
| 1089 | |
| 1090 | |
| 1091 | \membersection{::wxFindNextFile}\label{wxfindnextfile} |
| 1092 | |
| 1093 | \func{wxString}{wxFindNextFile}{\void} |
| 1094 | |
| 1095 | Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. |
| 1096 | |
| 1097 | See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example. |
| 1098 | |
| 1099 | |
| 1100 | \membersection{::wxGetDiskSpace}\label{wxgetdiskspace} |
| 1101 | |
| 1102 | \func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}} |
| 1103 | |
| 1104 | This function returns the total number of bytes and number of free bytes on |
| 1105 | the disk containing the directory {\it path} (it should exist). Both |
| 1106 | {\it total} and {\it free} parameters may be {\tt NULL} if the corresponding |
| 1107 | information is not needed. |
| 1108 | |
| 1109 | \wxheading{Returns} |
| 1110 | |
| 1111 | \true on success, \false if an error occurred (for example, the |
| 1112 | directory doesn't exist). |
| 1113 | |
| 1114 | \wxheading{Portability} |
| 1115 | |
| 1116 | The generic Unix implementation depends on the system having |
| 1117 | the \texttt{statfs()} or \texttt{statvfs()} function. |
| 1118 | |
| 1119 | This function first appeared in wxWidgets 2.3.2. |
| 1120 | |
| 1121 | |
| 1122 | \membersection{::wxGetFileKind}\label{wxgetfilekind} |
| 1123 | |
| 1124 | \func{wxFileKind}{wxGetFileKind}{\param{int }{fd}} |
| 1125 | |
| 1126 | \func{wxFileKind}{wxGetFileKind}{\param{FILE *}{fp}} |
| 1127 | |
| 1128 | Returns the type of an open file. Possible return values are: |
| 1129 | |
| 1130 | \begin{verbatim} |
| 1131 | enum wxFileKind |
| 1132 | { |
| 1133 | wxFILE_KIND_UNKNOWN, |
| 1134 | wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets |
| 1135 | wxFILE_KIND_TERMINAL, // a tty |
| 1136 | wxFILE_KIND_PIPE // a pipe |
| 1137 | }; |
| 1138 | |
| 1139 | \end{verbatim} |
| 1140 | |
| 1141 | \wxheading{Include files} |
| 1142 | |
| 1143 | <wx/filefn.h> |
| 1144 | |
| 1145 | |
| 1146 | \membersection{::wxGetOSDirectory}\label{wxgetosdirectory} |
| 1147 | |
| 1148 | \func{wxString}{wxGetOSDirectory}{\void} |
| 1149 | |
| 1150 | Returns the Windows directory under Windows; on other platforms returns the empty string. |
| 1151 | |
| 1152 | |
| 1153 | \membersection{::wxIsAbsolutePath}\label{wxisabsolutepath} |
| 1154 | |
| 1155 | \func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} |
| 1156 | |
| 1157 | Returns true if the argument is an absolute filename, i.e. with a slash |
| 1158 | or drive name at the beginning. |
| 1159 | |
| 1160 | |
| 1161 | \membersection{::wxDirExists}\label{functionwxdirexists} |
| 1162 | |
| 1163 | \func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} |
| 1164 | |
| 1165 | Returns true if \arg{dirname} exists and is a directory. |
| 1166 | |
| 1167 | |
| 1168 | \membersection{::wxPathOnly}\label{wxpathonly} |
| 1169 | |
| 1170 | \func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} |
| 1171 | |
| 1172 | Returns the directory part of the filename. |
| 1173 | |
| 1174 | |
| 1175 | \membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename} |
| 1176 | |
| 1177 | \func{void}{wxUnix2DosFilename}{\param{wxChar *}{s}} |
| 1178 | |
| 1179 | This function is deprecated, use \helpref{wxFileName}{wxfilename} instead. |
| 1180 | |
| 1181 | Converts a Unix to a DOS filename by replacing forward |
| 1182 | slashes with backslashes. |
| 1183 | |
| 1184 | |
| 1185 | \membersection{wxCHANGE\_UMASK}\label{wxchangeumask} |
| 1186 | |
| 1187 | \func{}{wxCHANGE\_UMASK}{\param{int }{mask}} |
| 1188 | |
| 1189 | Under Unix this macro changes the current process umask to the given value, |
| 1190 | unless it is equal to $-1$ in which case nothing is done, and restores it to |
| 1191 | the original value on scope exit. It works by declaring a variable which sets |
| 1192 | umask to \arg{mask} in its constructor and restores it in its destructor. |
| 1193 | |
| 1194 | Under other platforms this macro expands to nothing. |
| 1195 | |
| 1196 | |
| 1197 | \membersection{::wxConcatFiles}\label{wxconcatfiles} |
| 1198 | |
| 1199 | \func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, |
| 1200 | \param{const wxString\& }{file3}} |
| 1201 | |
| 1202 | Concatenates {\it file1} and {\it file2} to {\it file3}, returning |
| 1203 | true if successful. |
| 1204 | |
| 1205 | |
| 1206 | \membersection{::wxCopyFile}\label{wxcopyfile} |
| 1207 | |
| 1208 | \func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}} |
| 1209 | |
| 1210 | Copies {\it file1} to {\it file2}, returning true if successful. If |
| 1211 | {\it overwrite} parameter is \true (default), the destination file is overwritten |
| 1212 | if it exists, but if {\it overwrite} is \false, the functions fails in this |
| 1213 | case. |
| 1214 | |
| 1215 | This function supports resources forks under Mac OS. |
| 1216 | |
| 1217 | |
| 1218 | \membersection{::wxGetCwd}\label{wxgetcwd} |
| 1219 | |
| 1220 | \func{wxString}{wxGetCwd}{\void} |
| 1221 | |
| 1222 | Returns a string containing the current (or working) directory. |
| 1223 | |
| 1224 | |
| 1225 | \membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory} |
| 1226 | |
| 1227 | \func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}} |
| 1228 | |
| 1229 | {\bf NB:} This function is deprecated: use \helpref{wxGetCwd}{wxgetcwd} instead. |
| 1230 | |
| 1231 | Copies the current working directory into the buffer if supplied, or |
| 1232 | copies the working directory into new storage (which you {\emph must} delete |
| 1233 | yourself) if the buffer is NULL. |
| 1234 | |
| 1235 | {\it sz} is the size of the buffer if supplied. |
| 1236 | |
| 1237 | |
| 1238 | \membersection{::wxGetTempFileName}\label{wxgettempfilename} |
| 1239 | |
| 1240 | \func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}} |
| 1241 | |
| 1242 | \func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}} |
| 1243 | |
| 1244 | %% Makes a temporary filename based on {\it prefix}, opens and closes the file, |
| 1245 | %% and places the name in {\it buf}. If {\it buf} is NULL, new store |
| 1246 | %% is allocated for the temporary filename using {\it new}. |
| 1247 | %% |
| 1248 | %% Under Windows, the filename will include the drive and name of the |
| 1249 | %% directory allocated for temporary files (usually the contents of the |
| 1250 | %% TEMP variable). Under Unix, the {\tt /tmp} directory is used. |
| 1251 | %% |
| 1252 | %% It is the application's responsibility to create and delete the file. |
| 1253 | |
| 1254 | {\bf NB:} These functions are obsolete, please use\rtfsp |
| 1255 | \helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp |
| 1256 | instead. |
| 1257 | |
| 1258 | |
| 1259 | \membersection{::wxIsWild}\label{wxiswild} |
| 1260 | |
| 1261 | \func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} |
| 1262 | |
| 1263 | Returns true if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. |
| 1264 | |
| 1265 | |
| 1266 | \membersection{::wxMatchWild}\label{wxmatchwild} |
| 1267 | |
| 1268 | \func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} |
| 1269 | |
| 1270 | Returns true if the \arg{pattern}\/ matches the {\it text}\/; if {\it |
| 1271 | dot\_special}\/ is true, filenames beginning with a dot are not matched |
| 1272 | with wildcard characters. See \helpref{wxIsWild}{wxiswild}. |
| 1273 | |
| 1274 | |
| 1275 | \membersection{::wxMkdir}\label{wxmkdir} |
| 1276 | |
| 1277 | \func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}} |
| 1278 | |
| 1279 | Makes the directory \arg{dir}, returning true if successful. |
| 1280 | |
| 1281 | {\it perm} is the access mask for the directory for the systems on which it is |
| 1282 | supported (Unix) and doesn't have any effect on the other ones. |
| 1283 | |
| 1284 | |
| 1285 | \membersection{::wxParseCommonDialogsFilter}\label{wxparsecommondialogsfilter} |
| 1286 | |
| 1287 | \func{int}{wxParseCommonDialogsFilter}{\param{const wxString\& }{wildCard}, \param{wxArrayString\& }{descriptions}, \param{wxArrayString\& }{filters}} |
| 1288 | |
| 1289 | Parses the \arg{wildCard}, returning the number of filters. |
| 1290 | Returns 0 if none or if there's a problem. |
| 1291 | The arrays will contain an equal number of items found before the error. |
| 1292 | On platforms where native dialogs handle only one filter per entry, |
| 1293 | entries in arrays are automatically adjusted. |
| 1294 | \arg{wildCard} is in the form: |
| 1295 | \begin{verbatim} |
| 1296 | "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" |
| 1297 | \end{verbatim} |
| 1298 | |
| 1299 | \membersection{::wxRemoveFile}\label{wxremovefile} |
| 1300 | |
| 1301 | \func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} |
| 1302 | |
| 1303 | Removes \arg{file}, returning true if successful. |
| 1304 | |
| 1305 | |
| 1306 | \membersection{::wxRenameFile}\label{wxrenamefile} |
| 1307 | |
| 1308 | \func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}} |
| 1309 | |
| 1310 | Renames \arg{file1} to \arg{file2}, returning true if successful. |
| 1311 | |
| 1312 | If \arg{overwrite} parameter is true (default), the destination file is |
| 1313 | overwritten if it exists, but if \arg{overwrite} is false, the functions fails |
| 1314 | in this case. |
| 1315 | |
| 1316 | |
| 1317 | \membersection{::wxRmdir}\label{wxrmdir} |
| 1318 | |
| 1319 | \func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}} |
| 1320 | |
| 1321 | Removes the directory {\it dir}, returning true if successful. Does not work under VMS. |
| 1322 | |
| 1323 | The {\it flags} parameter is reserved for future use. |
| 1324 | |
| 1325 | Please notice that there is also a wxRmDir() function which simply wraps the |
| 1326 | standard POSIX rmdir() function and so return an integer error code instead of |
| 1327 | a boolean value (but otherwise is currently identical to wxRmdir), don't |
| 1328 | confuse these two functions. |
| 1329 | |
| 1330 | |
| 1331 | \membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory} |
| 1332 | |
| 1333 | \func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}} |
| 1334 | |
| 1335 | Sets the current working directory, returning true if the operation succeeded. |
| 1336 | Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification. |
| 1337 | |
| 1338 | |
| 1339 | \membersection{::wxSplit}\label{wxsplit} |
| 1340 | |
| 1341 | \func{wxArrayString}{wxSplit}{\param{const wxString\&}{ str}, \param{const wxChar}{ sep}, \param{const wxChar}{ escape = '\\'}} |
| 1342 | |
| 1343 | Splits the given \helpref{wxString}{wxstring} object using the separator \arg{sep} and returns the |
| 1344 | result as a \helpref{wxArrayString}{wxarraystring}. |
| 1345 | |
| 1346 | If the \arg{escape} character is non-\NULL, then the occurrences of \arg{sep} immediately prefixed |
| 1347 | with \arg{escape} are not considered as separators. |
| 1348 | |
| 1349 | Note that empty tokens will be generated if there are two or more adjacent separators. |
| 1350 | |
| 1351 | \wxheading{See also} |
| 1352 | |
| 1353 | \helpref{wxJoin}{wxjoin} |
| 1354 | |
| 1355 | \wxheading{Include files} |
| 1356 | |
| 1357 | <wx/arrstr.h> |
| 1358 | |
| 1359 | |
| 1360 | \membersection{::wxSplitPath}\label{wxsplitfunction} |
| 1361 | |
| 1362 | \func{void}{wxSplitPath}{\param{const wxString\&}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}} |
| 1363 | |
| 1364 | {\bf NB:} This function is obsolete, please use |
| 1365 | \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. |
| 1366 | |
| 1367 | This function splits a full file name into components: the path (including possible disk/drive |
| 1368 | specification under Windows), the base name and the extension. Any of the output parameters |
| 1369 | ({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of |
| 1370 | a particular component. |
| 1371 | |
| 1372 | wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under |
| 1373 | Windows, however it will not consider backslashes as path separators under Unix (where backslash |
| 1374 | is a valid character in a filename). |
| 1375 | |
| 1376 | On entry, {\it fullname} should be non-NULL (it may be empty though). |
| 1377 | |
| 1378 | On return, {\it path} contains the file path (without the trailing separator), {\it name} |
| 1379 | contains the file name and {\it ext} contains the file extension without leading dot. All |
| 1380 | three of them may be empty if the corresponding component is. The old contents of the |
| 1381 | strings pointed to by these parameters will be overwritten in any case (if the pointers |
| 1382 | are not NULL). |
| 1383 | |
| 1384 | |
| 1385 | \membersection{::wxTransferFileToStream}\label{wxtransferfiletostream} |
| 1386 | |
| 1387 | \func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}} |
| 1388 | |
| 1389 | Copies the given file to {\it stream}. Useful when converting an old application to |
| 1390 | use streams (within the document/view framework, for example). |
| 1391 | |
| 1392 | \wxheading{Include files} |
| 1393 | |
| 1394 | <wx/docview.h> |
| 1395 | |
| 1396 | |
| 1397 | \membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile} |
| 1398 | |
| 1399 | \func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}} |
| 1400 | |
| 1401 | Copies the given stream to the file {\it filename}. Useful when converting an old application to |
| 1402 | use streams (within the document/view framework, for example). |
| 1403 | |
| 1404 | \wxheading{Include files} |
| 1405 | |
| 1406 | <wx/docview.h> |
| 1407 | |
| 1408 | |
| 1409 | |
| 1410 | \section{Network, user and OS functions}\label{networkfunctions} |
| 1411 | |
| 1412 | The functions in this section are used to retrieve information about the |
| 1413 | current computer and/or user characteristics. |
| 1414 | |
| 1415 | |
| 1416 | \membersection{::wxGetEmailAddress}\label{wxgetemailaddress} |
| 1417 | |
| 1418 | \func{wxString}{wxGetEmailAddress}{\void} |
| 1419 | |
| 1420 | \func{bool}{wxGetEmailAddress}{\param{char * }{buf}, \param{int }{sz}} |
| 1421 | |
| 1422 | Copies the user's email address into the supplied buffer, by |
| 1423 | concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp |
| 1424 | and \helpref{wxGetUserId}{wxgetuserid}. |
| 1425 | |
| 1426 | Returns true if successful, false otherwise. |
| 1427 | |
| 1428 | \wxheading{Include files} |
| 1429 | |
| 1430 | <wx/utils.h> |
| 1431 | |
| 1432 | |
| 1433 | \membersection{::wxGetFreeMemory}\label{wxgetfreememory} |
| 1434 | |
| 1435 | \func{wxMemorySize}{wxGetFreeMemory}{\void} |
| 1436 | |
| 1437 | Returns the amount of free memory in bytes under environments which |
| 1438 | support it, and -1 if not supported or failed to perform measurement. |
| 1439 | |
| 1440 | \wxheading{Include files} |
| 1441 | |
| 1442 | <wx/utils.h> |
| 1443 | |
| 1444 | |
| 1445 | \membersection{::wxGetFullHostName}\label{wxgetfullhostname} |
| 1446 | |
| 1447 | \func{wxString}{wxGetFullHostName}{\void} |
| 1448 | |
| 1449 | Returns the FQDN (fully qualified domain host name) or an empty string on |
| 1450 | error. |
| 1451 | |
| 1452 | \wxheading{See also} |
| 1453 | |
| 1454 | \helpref{wxGetHostName}{wxgethostname} |
| 1455 | |
| 1456 | \wxheading{Include files} |
| 1457 | |
| 1458 | <wx/utils.h> |
| 1459 | |
| 1460 | |
| 1461 | \membersection{::wxGetHomeDir}\label{wxgethomedir} |
| 1462 | |
| 1463 | \func{wxString}{wxGetHomeDir}{\void} |
| 1464 | |
| 1465 | Return the (current) user's home directory. |
| 1466 | |
| 1467 | \wxheading{See also} |
| 1468 | |
| 1469 | \helpref{wxGetUserHome}{wxgetuserhome}\\ |
| 1470 | \helpref{wxStandardPaths}{wxstandardpaths} |
| 1471 | |
| 1472 | \wxheading{Include files} |
| 1473 | |
| 1474 | <wx/utils.h> |
| 1475 | |
| 1476 | |
| 1477 | \membersection{::wxGetHostName}\label{wxgethostname} |
| 1478 | |
| 1479 | \func{wxString}{wxGetHostName}{\void} |
| 1480 | |
| 1481 | \func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}} |
| 1482 | |
| 1483 | Copies the current host machine's name into the supplied buffer. Please note |
| 1484 | that the returned name is {\it not} fully qualified, i.e. it does not include |
| 1485 | the domain name. |
| 1486 | |
| 1487 | Under Windows or NT, this function first looks in the environment |
| 1488 | variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp |
| 1489 | in the {\bf wxWidgets} section of the WIN.INI file is tried. |
| 1490 | |
| 1491 | The first variant of this function returns the hostname if successful or an |
| 1492 | empty string otherwise. The second (deprecated) function returns true |
| 1493 | if successful, false otherwise. |
| 1494 | |
| 1495 | \wxheading{See also} |
| 1496 | |
| 1497 | \helpref{wxGetFullHostName}{wxgetfullhostname} |
| 1498 | |
| 1499 | \wxheading{Include files} |
| 1500 | |
| 1501 | <wx/utils.h> |
| 1502 | |
| 1503 | |
| 1504 | \membersection{::wxGetOsDescription}\label{wxgetosdescription} |
| 1505 | |
| 1506 | \func{wxString}{wxGetOsDescription}{\void} |
| 1507 | |
| 1508 | Returns the string containing the description of the current platform in a |
| 1509 | user-readable form. For example, this function may return strings like |
| 1510 | {\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}. |
| 1511 | |
| 1512 | \wxheading{See also} |
| 1513 | |
| 1514 | \helpref{::wxGetOsVersion}{wxgetosversion} |
| 1515 | |
| 1516 | \wxheading{Include files} |
| 1517 | |
| 1518 | <wx/utils.h> |
| 1519 | |
| 1520 | |
| 1521 | \membersection{::wxGetOsVersion}\label{wxgetosversion} |
| 1522 | |
| 1523 | \func{wxOperatingSystemId}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} |
| 1524 | |
| 1525 | Gets the version and the operating system ID for currently running OS. |
| 1526 | See \helpref{wxPlatformInfo}{wxplatforminfo} for more details about wxOperatingSystemId. |
| 1527 | |
| 1528 | \wxheading{See also} |
| 1529 | |
| 1530 | \helpref{::wxGetOsDescription}{wxgetosdescription}, |
| 1531 | \helpref{wxPlatformInfo}{wxplatforminfo} |
| 1532 | |
| 1533 | \wxheading{Include files} |
| 1534 | |
| 1535 | <wx/utils.h> |
| 1536 | |
| 1537 | |
| 1538 | \membersection{::wxIsPlatformLittleEndian}\label{wxisplatformlittleendian} |
| 1539 | |
| 1540 | \func{bool}{wxIsPlatformLittleEndian}{\void} |
| 1541 | |
| 1542 | Returns \true if the current platform is little endian (instead of big endian). |
| 1543 | The check is performed at run-time. |
| 1544 | |
| 1545 | \wxheading{See also} |
| 1546 | |
| 1547 | \helpref{Byte order macros}{byteordermacros} |
| 1548 | |
| 1549 | \wxheading{Include files} |
| 1550 | |
| 1551 | <wx/utils.h> |
| 1552 | |
| 1553 | |
| 1554 | \membersection{::wxIsPlatform64Bit}\label{wxisplatform64bit} |
| 1555 | |
| 1556 | \func{bool}{wxIsPlatform64Bit}{\void} |
| 1557 | |
| 1558 | Returns \true if the operating system the program is running under is 64 bit. |
| 1559 | The check is performed at run-time and may differ from the value available at |
| 1560 | compile-time (at compile-time you can just check if {\tt sizeof(void*)==8}) |
| 1561 | since the program could be running in emulation mode or in a mixed 32/64 bit system |
| 1562 | (bi-architecture operating system). |
| 1563 | |
| 1564 | Very important: this function is not 100\% reliable on some systems given the fact |
| 1565 | that there isn't always a standard way to do a reliable check on the OS architecture. |
| 1566 | |
| 1567 | \wxheading{Include files} |
| 1568 | |
| 1569 | <wx/utils.h> |
| 1570 | |
| 1571 | |
| 1572 | \membersection{::wxGetUserHome}\label{wxgetuserhome} |
| 1573 | |
| 1574 | \func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}} |
| 1575 | |
| 1576 | Returns the home directory for the given user. If the username is empty |
| 1577 | (default value), this function behaves like |
| 1578 | \helpref{wxGetHomeDir}{wxgethomedir}. |
| 1579 | |
| 1580 | \wxheading{Include files} |
| 1581 | |
| 1582 | <wx/utils.h> |
| 1583 | |
| 1584 | |
| 1585 | \membersection{::wxGetUserId}\label{wxgetuserid} |
| 1586 | |
| 1587 | \func{wxString}{wxGetUserId}{\void} |
| 1588 | |
| 1589 | \func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}} |
| 1590 | |
| 1591 | This function returns the "user id" also known as "login name" under Unix i.e. |
| 1592 | something like "jsmith". It uniquely identifies the current user (on this system). |
| 1593 | |
| 1594 | Under Windows or NT, this function first looks in the environment |
| 1595 | variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp |
| 1596 | in the {\bf wxWidgets} section of the WIN.INI file is tried. |
| 1597 | |
| 1598 | The first variant of this function returns the login name if successful or an |
| 1599 | empty string otherwise. The second (deprecated) function returns true |
| 1600 | if successful, false otherwise. |
| 1601 | |
| 1602 | \wxheading{See also} |
| 1603 | |
| 1604 | \helpref{wxGetUserName}{wxgetusername} |
| 1605 | |
| 1606 | \wxheading{Include files} |
| 1607 | |
| 1608 | <wx/utils.h> |
| 1609 | |
| 1610 | |
| 1611 | \membersection{::wxGetUserName}\label{wxgetusername} |
| 1612 | |
| 1613 | \func{wxString}{wxGetUserName}{\void} |
| 1614 | |
| 1615 | \func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}} |
| 1616 | |
| 1617 | This function returns the full user name (something like "Mr. John Smith"). |
| 1618 | |
| 1619 | Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp |
| 1620 | in the {\bf wxWidgets} section of the WIN.INI file. If PenWindows |
| 1621 | is running, the entry {\bf Current} in the section {\bf User} of |
| 1622 | the PENWIN.INI file is used. |
| 1623 | |
| 1624 | The first variant of this function returns the user name if successful or an |
| 1625 | empty string otherwise. The second (deprecated) function returns \true |
| 1626 | if successful, \false otherwise. |
| 1627 | |
| 1628 | \wxheading{See also} |
| 1629 | |
| 1630 | \helpref{wxGetUserId}{wxgetuserid} |
| 1631 | |
| 1632 | \wxheading{Include files} |
| 1633 | |
| 1634 | <wx/utils.h> |
| 1635 | |
| 1636 | |
| 1637 | |
| 1638 | \section{String functions}\label{stringfunctions} |
| 1639 | |
| 1640 | \membersection{::wxGetTranslation}\label{wxgettranslation} |
| 1641 | |
| 1642 | \func{const wxString\& }{wxGetTranslation}{\param{const wxString\& }{str}, |
| 1643 | \param{const wxString\& }{domain = wxEmptyString}} |
| 1644 | |
| 1645 | \func{const wxString\& }{wxGetTranslation}{\param{const wxString\& }{str}, \param{const wxString\& }{strPlural}, \param{size\_t }{n}, |
| 1646 | \param{const wxString\& }{domain = wxEmptyString}} |
| 1647 | |
| 1648 | This function returns the translation of string {\it str} in the current |
| 1649 | \helpref{locale}{wxlocale}. If the string is not found in any of the loaded |
| 1650 | message catalogs (see \helpref{internationalization overview}{internationalization}), the |
| 1651 | original string is returned. In debug build, an error message is logged -- this |
| 1652 | should help to find the strings which were not yet translated. If |
| 1653 | {\it domain} is specified then only that domain/catalog is searched |
| 1654 | for a matching string. As this function |
| 1655 | is used very often, an alternative (and also common in Unix world) syntax is |
| 1656 | provided: the \helpref{\_()}{underscore} macro is defined to do the same thing |
| 1657 | as wxGetTranslation. |
| 1658 | |
| 1659 | The second form is used when retrieving translation of string that has |
| 1660 | different singular and plural form in English or different plural forms in some |
| 1661 | other language. It takes two extra arguments: as above, \arg{str} |
| 1662 | parameter must contain the singular form of the string to be converted and |
| 1663 | is used as the key for the search in the catalog. The \arg{strPlural} parameter |
| 1664 | is the plural form (in English). The parameter \arg{n} is used to determine the |
| 1665 | plural form. If no message catalog is found \arg{str} is returned if `n == 1', |
| 1666 | otherwise \arg{strPlural}. |
| 1667 | |
| 1668 | See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} |
| 1669 | for additional information on plural forms handling. For a shorter alternative |
| 1670 | see the \helpref{wxPLURAL()}{wxplural} macro. |
| 1671 | |
| 1672 | Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}. |
| 1673 | |
| 1674 | Note that this function is not suitable for literal strings in Unicode |
| 1675 | builds, since the literal strings must be enclosed into |
| 1676 | \helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them |
| 1677 | unrecognised by \texttt{xgettext}, and so they are not extracted to the message |
| 1678 | catalog. Instead, use the \helpref{\_()}{underscore} and |
| 1679 | \helpref{wxPLURAL}{wxplural} macro for all literal strings. |
| 1680 | |
| 1681 | |
| 1682 | \membersection{::wxIsEmpty}\label{wxisempty} |
| 1683 | |
| 1684 | \func{bool}{wxIsEmpty}{\param{const char *}{ p}} |
| 1685 | |
| 1686 | Returns \true if the pointer is either {\tt NULL} or points to an empty |
| 1687 | string, \false otherwise. |
| 1688 | |
| 1689 | |
| 1690 | \membersection{::wxStrcmp}\label{wxstrcmp} |
| 1691 | |
| 1692 | \func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}} |
| 1693 | |
| 1694 | Returns a negative value, 0, or positive value if {\it p1} is less than, equal |
| 1695 | to or greater than {\it p2}. The comparison is case-sensitive. |
| 1696 | |
| 1697 | This function complements the standard C function {\it stricmp()} which performs |
| 1698 | case-insensitive comparison. |
| 1699 | |
| 1700 | |
| 1701 | \membersection{::wxStricmp}\label{wxstricmp} |
| 1702 | |
| 1703 | \func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}} |
| 1704 | |
| 1705 | Returns a negative value, 0, or positive value if {\it p1} is less than, equal |
| 1706 | to or greater than {\it p2}. The comparison is case-insensitive. |
| 1707 | |
| 1708 | This function complements the standard C function {\it strcmp()} which performs |
| 1709 | case-sensitive comparison. |
| 1710 | |
| 1711 | |
| 1712 | \membersection{::wxStringEq}\label{wxstringeq} |
| 1713 | |
| 1714 | \func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} |
| 1715 | |
| 1716 | {\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead. |
| 1717 | |
| 1718 | A macro defined as: |
| 1719 | |
| 1720 | \begin{verbatim} |
| 1721 | #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) |
| 1722 | \end{verbatim} |
| 1723 | |
| 1724 | |
| 1725 | \membersection{::wxStringMatch}\label{wxstringmatch} |
| 1726 | |
| 1727 | \func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\ |
| 1728 | \param{bool}{ subString = true}, \param{bool}{ exact = false}} |
| 1729 | |
| 1730 | {\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead. |
| 1731 | |
| 1732 | Returns \true if the substring {\it s1} is found within {\it s2}, |
| 1733 | ignoring case if {\it exact} is false. If {\it subString} is \false, |
| 1734 | no substring matching is done. |
| 1735 | |
| 1736 | |
| 1737 | \membersection{::wxStringTokenize}\label{wxstringtokenize} |
| 1738 | |
| 1739 | \func{wxArrayString}{wxStringTokenize}{\param{const wxString\& }{str},\\ |
| 1740 | \param{const wxString\& }{delims = wxDEFAULT\_DELIMITERS},\\ |
| 1741 | \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}} |
| 1742 | |
| 1743 | This is a convenience function wrapping |
| 1744 | \helpref{wxStringTokenizer}{wxstringtokenizer} which simply returns all tokens |
| 1745 | found in the given \arg{str} in an array. |
| 1746 | |
| 1747 | Please see |
| 1748 | \helpref{wxStringTokenizer::wxStringTokenizer}{wxstringtokenizerwxstringtokenizer} |
| 1749 | for the description of the other parameters. |
| 1750 | |
| 1751 | |
| 1752 | \membersection{::wxStrlen}\label{wxstrlen} |
| 1753 | |
| 1754 | \func{size\_t}{wxStrlen}{\param{const char *}{ p}} |
| 1755 | |
| 1756 | This is a safe version of standard function {\it strlen()}: it does exactly the |
| 1757 | same thing (i.e. returns the length of the string) except that it returns 0 if |
| 1758 | {\it p} is the {\tt NULL} pointer. |
| 1759 | |
| 1760 | |
| 1761 | \membersection{::wxSnprintf}\label{wxsnprintf} |
| 1762 | |
| 1763 | \func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}} |
| 1764 | |
| 1765 | This function replaces the dangerous standard function {\tt sprintf()} and is |
| 1766 | like {\tt snprintf()} available on some platforms. The only difference with |
| 1767 | sprintf() is that an additional argument - buffer size - is taken and the |
| 1768 | buffer is never overflowed. |
| 1769 | |
| 1770 | Returns the number of characters copied to the buffer or -1 if there is not |
| 1771 | enough space. |
| 1772 | |
| 1773 | \wxheading{See also} |
| 1774 | |
| 1775 | \helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf} |
| 1776 | |
| 1777 | |
| 1778 | \membersection{wxT}\label{wxt} |
| 1779 | |
| 1780 | \func{wxChar}{wxT}{\param{char }{ch}} |
| 1781 | |
| 1782 | \func{const wxChar *}{wxT}{\param{const char *}{s}} |
| 1783 | |
| 1784 | wxT() is a macro which can be used with character and string literals (in other |
| 1785 | words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in |
| 1786 | Unicode build configuration. Please see the |
| 1787 | \helpref{Unicode overview}{unicode} for more information. |
| 1788 | |
| 1789 | This macro is simply returns the value passed to it without changes in ASCII |
| 1790 | build. In fact, its definition is: |
| 1791 | \begin{verbatim} |
| 1792 | #ifdef UNICODE |
| 1793 | #define wxT(x) L ## x |
| 1794 | #else // !Unicode |
| 1795 | #define wxT(x) x |
| 1796 | #endif |
| 1797 | \end{verbatim} |
| 1798 | |
| 1799 | |
| 1800 | \membersection{wxTRANSLATE}\label{wxtranslate} |
| 1801 | |
| 1802 | \func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}} |
| 1803 | |
| 1804 | This macro doesn't do anything in the program code -- it simply expands to the |
| 1805 | value of its argument. |
| 1806 | |
| 1807 | However it does have a purpose which is to mark the literal strings for the |
| 1808 | extraction into the message catalog created by {\tt xgettext} program. Usually |
| 1809 | this is achieved using \helpref{\_()}{underscore} but that macro not only marks |
| 1810 | the string for extraction but also expands into a |
| 1811 | \helpref{wxGetTranslation}{wxgettranslation} function call which means that it |
| 1812 | cannot be used in some situations, notably for static array |
| 1813 | initialization. |
| 1814 | |
| 1815 | Here is an example which should make it more clear: suppose that you have a |
| 1816 | static array of strings containing the weekday names and which have to be |
| 1817 | translated (note that it is a bad example, really, as |
| 1818 | \helpref{wxDateTime}{wxdatetime} already can be used to get the localized week |
| 1819 | day names already). If you write |
| 1820 | |
| 1821 | \begin{verbatim} |
| 1822 | static const char * const weekdays[] = { _("Mon"), ..., _("Sun") }; |
| 1823 | ... |
| 1824 | // use weekdays[n] as usual |
| 1825 | \end{verbatim} |
| 1826 | |
| 1827 | the code wouldn't compile because the function calls are forbidden in the array |
| 1828 | initializer. So instead you should do |
| 1829 | |
| 1830 | \begin{verbatim} |
| 1831 | static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") }; |
| 1832 | ... |
| 1833 | // use wxGetTranslation(weekdays[n]) |
| 1834 | \end{verbatim} |
| 1835 | |
| 1836 | here. |
| 1837 | |
| 1838 | Note that although the code {\bf would} compile if you simply omit |
| 1839 | wxTRANSLATE() in the above, it wouldn't work as expected because there would be |
| 1840 | no translations for the weekday names in the program message catalog and |
| 1841 | wxGetTranslation wouldn't find them. |
| 1842 | |
| 1843 | |
| 1844 | \membersection{::wxVsnprintf}\label{wxvsnprintf} |
| 1845 | |
| 1846 | \func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}} |
| 1847 | |
| 1848 | The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list } |
| 1849 | argument instead of arbitrary number of parameters. |
| 1850 | |
| 1851 | Note that if \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is set to 1, then this function supports |
| 1852 | positional arguments (see \helpref{wxString::Printf}{wxstringprintf} for more information). |
| 1853 | However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, wxVfprintf, |
| 1854 | wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional parameters |
| 1855 | even when \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is 1. |
| 1856 | |
| 1857 | \wxheading{See also} |
| 1858 | |
| 1859 | \helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv} |
| 1860 | |
| 1861 | |
| 1862 | |
| 1863 | \membersection{\_}\label{underscore} |
| 1864 | |
| 1865 | \func{const wxString\&}{\_}{\param{const wxString\&}{s}} |
| 1866 | |
| 1867 | This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation} |
| 1868 | function, so it marks the message for the extraction by {\tt xgettext} just as |
| 1869 | \helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of |
| 1870 | the string for the current locale during execution. |
| 1871 | |
| 1872 | Don't confuse this macro with \helpref{\_T()}{underscoret}! |
| 1873 | |
| 1874 | |
| 1875 | \membersection{wxPLURAL}\label{wxplural} |
| 1876 | |
| 1877 | \func{const wxString\&}{wxPLURAL}{\param{const wxString\&}{sing}, \param{const wxString\&}{plur}, \param{size\_t}{n}} |
| 1878 | |
| 1879 | This macro is identical to \helpref{\_()}{underscore} but for the plural variant |
| 1880 | of \helpref{wxGetTranslation}{wxgettranslation}. |
| 1881 | |
| 1882 | |
| 1883 | \membersection{\_T}\label{underscoret} |
| 1884 | |
| 1885 | \func{wxChar}{\_T}{\param{char }{ch}} |
| 1886 | |
| 1887 | \func{const wxChar *}{\_T}{\param{const wxChar }{ch}} |
| 1888 | |
| 1889 | This macro is exactly the same as \helpref{wxT}{wxt} and is defined in |
| 1890 | wxWidgets simply because it may be more intuitive for Windows programmers as |
| 1891 | the standard Win32 headers also define it (as well as yet another name for the |
| 1892 | same macro which is {\tt \_TEXT()}). |
| 1893 | |
| 1894 | Don't confuse this macro with \helpref{\_()}{underscore}! |
| 1895 | |
| 1896 | |
| 1897 | |
| 1898 | \section{Dialog functions}\label{dialogfunctions} |
| 1899 | |
| 1900 | Below are a number of convenience functions for getting input from the |
| 1901 | user or displaying messages. Note that in these functions the last three |
| 1902 | parameters are optional. However, it is recommended to pass a parent frame |
| 1903 | parameter, or (in MS Windows or Motif) the wrong window frame may be brought to |
| 1904 | the front when the dialog box is popped up. |
| 1905 | |
| 1906 | |
| 1907 | \membersection{::wxAboutBox}\label{wxaboutbox} |
| 1908 | |
| 1909 | \func{void}{wxAboutBox}{\param{const wxAboutDialogInfo\& }{info}} |
| 1910 | |
| 1911 | This function shows the standard about dialog containing the information |
| 1912 | specified in \arg{info}. If the current platform has a native about dialog |
| 1913 | which is capable of showing all the fields in \arg{info}, the native dialog is |
| 1914 | used, otherwise the function falls back to the generic wxWidgets version of the |
| 1915 | dialog, i.e. does the same thing as \helpref{wxGenericAboutBox()}{wxgenericaboutbox}. |
| 1916 | |
| 1917 | Here is an example of how this function may be used: |
| 1918 | \begin{verbatim} |
| 1919 | void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event)) |
| 1920 | { |
| 1921 | wxAboutDialogInfo info; |
| 1922 | info.SetName(_("My Program")); |
| 1923 | info.SetVersion(_("1.2.3 Beta")); |
| 1924 | info.SetDescription(_("This program does something great.")); |
| 1925 | info.SetCopyright(_T("(C) 2007 Me <my@email.addre.ss>")); |
| 1926 | |
| 1927 | wxAboutBox(info); |
| 1928 | } |
| 1929 | \end{verbatim} |
| 1930 | |
| 1931 | Please see the \helpref{dialogs sample}{sampledialogs} for more examples of |
| 1932 | using this function and \helpref{wxAboutDialogInfo}{wxaboutdialoginfo} for the |
| 1933 | description of the information which can be shown in the about dialog. |
| 1934 | |
| 1935 | \wxheading{Include files} |
| 1936 | |
| 1937 | <wx/aboutdlg.h> |
| 1938 | |
| 1939 | |
| 1940 | \membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} |
| 1941 | |
| 1942 | \func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}} |
| 1943 | |
| 1944 | Changes the cursor to the given cursor for all windows in the application. |
| 1945 | Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back |
| 1946 | to its previous state. These two calls can be nested, and a counter |
| 1947 | ensures that only the outer calls take effect. |
| 1948 | |
| 1949 | See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. |
| 1950 | |
| 1951 | \wxheading{Include files} |
| 1952 | |
| 1953 | <wx/utils.h> |
| 1954 | |
| 1955 | |
| 1956 | \membersection{::wxBell}\label{wxbell} |
| 1957 | |
| 1958 | \func{void}{wxBell}{\void} |
| 1959 | |
| 1960 | Ring the system bell. |
| 1961 | |
| 1962 | \wxheading{Include files} |
| 1963 | |
| 1964 | <wx/utils.h> |
| 1965 | |
| 1966 | |
| 1967 | \membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider} |
| 1968 | |
| 1969 | \func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename}, |
| 1970 | \param{size\_t }{currentTip}} |
| 1971 | |
| 1972 | This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be |
| 1973 | used with \helpref{wxShowTip}{wxshowtip}. |
| 1974 | |
| 1975 | \docparam{filename}{The name of the file containing the tips, one per line} |
| 1976 | \docparam{currentTip}{The index of the first tip to show - normally this index |
| 1977 | is remembered between the 2 program runs.} |
| 1978 | |
| 1979 | \wxheading{See also} |
| 1980 | |
| 1981 | \helpref{Tips overview}{tipsoverview} |
| 1982 | |
| 1983 | \wxheading{Include files} |
| 1984 | |
| 1985 | <wx/tipdlg.h> |
| 1986 | |
| 1987 | |
| 1988 | \membersection{::wxDirSelector}\label{wxdirselector} |
| 1989 | |
| 1990 | \func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\ |
| 1991 | \param{const wxString\& }{default\_path = ""},\\ |
| 1992 | \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\ |
| 1993 | \param{wxWindow *}{parent = NULL}} |
| 1994 | |
| 1995 | Pops up a directory selector dialog. The arguments have the same meaning as |
| 1996 | those of wxDirDialog::wxDirDialog(). The message is displayed at the top, |
| 1997 | and the default\_path, if specified, is set as the initial selection. |
| 1998 | |
| 1999 | The application must check for an empty return value (if the user pressed |
| 2000 | Cancel). For example: |
| 2001 | |
| 2002 | \begin{verbatim} |
| 2003 | const wxString& dir = wxDirSelector("Choose a folder"); |
| 2004 | if ( !dir.empty() ) |
| 2005 | { |
| 2006 | ... |
| 2007 | } |
| 2008 | \end{verbatim} |
| 2009 | |
| 2010 | \wxheading{Include files} |
| 2011 | |
| 2012 | <wx/dirdlg.h> |
| 2013 | |
| 2014 | |
| 2015 | \membersection{::wxFileSelector}\label{wxfileselector} |
| 2016 | |
| 2017 | \func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\ |
| 2018 | \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\ |
| 2019 | \param{const wxString\& }{wildcard = "*.*"}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\ |
| 2020 | \param{int}{ x = -1}, \param{int}{ y = -1}} |
| 2021 | |
| 2022 | Pops up a file selector box. In Windows, this is the common file selector |
| 2023 | dialog. In X, this is a file selector box with the same functionality. |
| 2024 | The path and filename are distinct elements of a full file pathname. |
| 2025 | If path is empty, the current directory will be used. If filename is empty, |
| 2026 | no default filename will be supplied. The wildcard determines what files |
| 2027 | are displayed in the file selector, and file extension supplies a type |
| 2028 | extension for the required filename. Flags may be a combination of wxFD\_OPEN, |
| 2029 | wxFD\_SAVE, wxFD\_OVERWRITE\_PROMPT or wxFD\_FILE\_MUST\_EXIST. Note that wxFD\_MULTIPLE |
| 2030 | can only be used with \helpref{wxFileDialog}{wxfiledialog} and not here as this |
| 2031 | function only returns a single file name. |
| 2032 | |
| 2033 | Both the Unix and Windows versions implement a wildcard filter. Typing a |
| 2034 | filename containing wildcards (*, ?) in the filename text item, and |
| 2035 | clicking on Ok, will result in only those files matching the pattern being |
| 2036 | displayed. |
| 2037 | |
| 2038 | The wildcard may be a specification for multiple types of file |
| 2039 | with a description for each, such as: |
| 2040 | |
| 2041 | \begin{verbatim} |
| 2042 | "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" |
| 2043 | \end{verbatim} |
| 2044 | |
| 2045 | The application must check for an empty return value (the user pressed |
| 2046 | Cancel). For example: |
| 2047 | |
| 2048 | \begin{verbatim} |
| 2049 | wxString filename = wxFileSelector("Choose a file to open"); |
| 2050 | if ( !filename.empty() ) |
| 2051 | { |
| 2052 | // work with the file |
| 2053 | ... |
| 2054 | } |
| 2055 | //else: cancelled by user |
| 2056 | \end{verbatim} |
| 2057 | |
| 2058 | \wxheading{Include files} |
| 2059 | |
| 2060 | <wx/filedlg.h> |
| 2061 | |
| 2062 | |
| 2063 | \membersection{::wxEndBusyCursor}\label{wxendbusycursor} |
| 2064 | |
| 2065 | \func{void}{wxEndBusyCursor}{\void} |
| 2066 | |
| 2067 | Changes the cursor back to the original cursor, for all windows in the application. |
| 2068 | Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}. |
| 2069 | |
| 2070 | See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. |
| 2071 | |
| 2072 | \wxheading{Include files} |
| 2073 | |
| 2074 | <wx/utils.h> |
| 2075 | |
| 2076 | |
| 2077 | \membersection{::wxGenericAboutBox}\label{wxgenericaboutbox} |
| 2078 | |
| 2079 | \func{void}{wxGenericAboutBox}{\param{const wxAboutDialogInfo\& }{info}} |
| 2080 | |
| 2081 | This function does the same thing as \helpref{wxAboutBox}{wxaboutbox} except |
| 2082 | that it always uses the generic wxWidgets version of the dialog instead of the |
| 2083 | native one. This is mainly useful if you need to customize the dialog by e.g. |
| 2084 | adding custom controls to it (customizing the native dialog is not currently |
| 2085 | supported). |
| 2086 | |
| 2087 | See the \helpref{dialogs sample}{sampledialogs} for an example of about dialog |
| 2088 | customization. |
| 2089 | |
| 2090 | \wxheading{See also} |
| 2091 | |
| 2092 | \helpref{wxAboutDialogInfo}{wxaboutdialoginfo} |
| 2093 | |
| 2094 | \wxheading{Include files} |
| 2095 | |
| 2096 | <wx/aboutdlg.h>\\ |
| 2097 | <wx/generic/aboutdlgg.h> |
| 2098 | |
| 2099 | |
| 2100 | \membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser} |
| 2101 | |
| 2102 | \func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}} |
| 2103 | |
| 2104 | Shows the colour selection dialog and returns the colour selected by user or |
| 2105 | invalid colour (use \helpref{wxColour:IsOk}{wxcolourisok} to test whether a colour |
| 2106 | is valid) if the dialog was cancelled. |
| 2107 | |
| 2108 | \wxheading{Parameters} |
| 2109 | |
| 2110 | \docparam{parent}{The parent window for the colour selection dialog} |
| 2111 | |
| 2112 | \docparam{colInit}{If given, this will be the colour initially selected in the dialog.} |
| 2113 | |
| 2114 | \docparam{caption}{If given, this will be used for the dialog caption.} |
| 2115 | |
| 2116 | \wxheading{Include files} |
| 2117 | |
| 2118 | <wx/colordlg.h> |
| 2119 | |
| 2120 | |
| 2121 | \membersection{::wxGetFontFromUser}\label{wxgetfontfromuser} |
| 2122 | |
| 2123 | \func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}, \param{const wxString\& }{caption = wxEmptyString}} |
| 2124 | |
| 2125 | Shows the font selection dialog and returns the font selected by user or |
| 2126 | invalid font (use \helpref{wxFont:IsOk}{wxfontisok} to test whether a font |
| 2127 | is valid) if the dialog was cancelled. |
| 2128 | |
| 2129 | \wxheading{Parameters} |
| 2130 | |
| 2131 | \docparam{parent}{The parent window for the font selection dialog} |
| 2132 | |
| 2133 | \docparam{fontInit}{If given, this will be the font initially selected in the dialog.} |
| 2134 | |
| 2135 | \docparam{caption}{If given, this will be used for the dialog caption.} |
| 2136 | |
| 2137 | \wxheading{Include files} |
| 2138 | |
| 2139 | <wx/fontdlg.h> |
| 2140 | |
| 2141 | |
| 2142 | |
| 2143 | \membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices} |
| 2144 | |
| 2145 | \func{size\_t}{wxGetMultipleChoices}{\\ |
| 2146 | \param{wxArrayInt\& }{selections},\\ |
| 2147 | \param{const wxString\& }{message},\\ |
| 2148 | \param{const wxString\& }{caption},\\ |
| 2149 | \param{const wxArrayString\& }{aChoices},\\ |
| 2150 | \param{wxWindow *}{parent = NULL},\\ |
| 2151 | \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2152 | \param{bool}{ centre = true},\\ |
| 2153 | \param{int }{width=150}, \param{int }{height=200}} |
| 2154 | |
| 2155 | \func{size\_t}{wxGetMultipleChoices}{\\ |
| 2156 | \param{wxArrayInt\& }{selections},\\ |
| 2157 | \param{const wxString\& }{message},\\ |
| 2158 | \param{const wxString\& }{caption},\\ |
| 2159 | \param{int}{ n}, \param{const wxString\& }{choices[]},\\ |
| 2160 | \param{wxWindow *}{parent = NULL},\\ |
| 2161 | \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2162 | \param{bool}{ centre = true},\\ |
| 2163 | \param{int }{width=150}, \param{int }{height=200}} |
| 2164 | |
| 2165 | Pops up a dialog box containing a message, OK/Cancel buttons and a |
| 2166 | multiple-selection listbox. The user may choose an arbitrary (including 0) |
| 2167 | number of items in the listbox whose indices will be returned in |
| 2168 | {\it selection} array. The initial contents of this array will be used to |
| 2169 | select the items when the dialog is shown. |
| 2170 | |
| 2171 | You may pass the list of strings to choose from either using {\it choices} |
| 2172 | which is an array of {\it n} strings for the listbox or by using a single |
| 2173 | {\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}. |
| 2174 | |
| 2175 | If {\it centre} is true, the message text (which may include new line |
| 2176 | characters) is centred; if false, the message is left-justified. |
| 2177 | |
| 2178 | \wxheading{Include files} |
| 2179 | |
| 2180 | <wx/choicdlg.h> |
| 2181 | |
| 2182 | \perlnote{In wxPerl there is just an array reference in place of {\tt n} |
| 2183 | and {\tt choices}, and no {\tt selections} parameter; the function |
| 2184 | returns an array containing the user selections.} |
| 2185 | |
| 2186 | |
| 2187 | \membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser} |
| 2188 | |
| 2189 | \func{long}{wxGetNumberFromUser}{ |
| 2190 | \param{const wxString\& }{message}, |
| 2191 | \param{const wxString\& }{prompt}, |
| 2192 | \param{const wxString\& }{caption}, |
| 2193 | \param{long }{value}, |
| 2194 | \param{long }{min = 0}, |
| 2195 | \param{long }{max = 100}, |
| 2196 | \param{wxWindow *}{parent = NULL}, |
| 2197 | \param{const wxPoint\& }{pos = wxDefaultPosition}} |
| 2198 | |
| 2199 | Shows a dialog asking the user for numeric input. The dialogs title is set to |
| 2200 | {\it caption}, it contains a (possibly) multiline {\it message} above the |
| 2201 | single line {\it prompt} and the zone for entering the number. |
| 2202 | |
| 2203 | The number entered must be in the range {\it min}..{\it max} (both of which |
| 2204 | should be positive) and {\it value} is the initial value of it. If the user |
| 2205 | enters an invalid value or cancels the dialog, the function will return -1. |
| 2206 | |
| 2207 | Dialog is centered on its {\it parent} unless an explicit position is given in |
| 2208 | {\it pos}. |
| 2209 | |
| 2210 | \wxheading{Include files} |
| 2211 | |
| 2212 | <wx/numdlg.h> |
| 2213 | |
| 2214 | |
| 2215 | \membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser} |
| 2216 | |
| 2217 | \func{wxString}{wxGetPasswordFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ |
| 2218 | \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ |
| 2219 | \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}} |
| 2220 | |
| 2221 | Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered |
| 2222 | in the dialog is not shown on screen but replaced with stars. This is intended |
| 2223 | to be used for entering passwords as the function name implies. |
| 2224 | |
| 2225 | \wxheading{Include files} |
| 2226 | |
| 2227 | <wx/textdlg.h> |
| 2228 | |
| 2229 | |
| 2230 | \membersection{::wxGetTextFromUser}\label{wxgettextfromuser} |
| 2231 | |
| 2232 | \func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ |
| 2233 | \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ |
| 2234 | \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}} |
| 2235 | |
| 2236 | Pop up a dialog box with title set to {\it caption}, {\it message}, and a |
| 2237 | \rtfsp{\it default\_value}. The user may type in text and press OK to return this text, |
| 2238 | or press Cancel to return the empty string. |
| 2239 | |
| 2240 | If {\it centre} is true, the message text (which may include new line characters) |
| 2241 | is centred; if false, the message is left-justified. |
| 2242 | |
| 2243 | \wxheading{Include files} |
| 2244 | |
| 2245 | <wx/textdlg.h> |
| 2246 | |
| 2247 | |
| 2248 | \membersection{::wxGetSingleChoice}\label{wxgetsinglechoice} |
| 2249 | |
| 2250 | \func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\ |
| 2251 | \param{const wxString\& }{caption},\\ |
| 2252 | \param{const wxArrayString\& }{aChoices},\\ |
| 2253 | \param{wxWindow *}{parent = NULL},\\ |
| 2254 | \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2255 | \param{bool}{ centre = true},\\ |
| 2256 | \param{int }{width=150}, \param{int }{height=200}} |
| 2257 | |
| 2258 | \func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\ |
| 2259 | \param{const wxString\& }{caption},\\ |
| 2260 | \param{int}{ n}, \param{const wxString\& }{choices[]},\\ |
| 2261 | \param{wxWindow *}{parent = NULL},\\ |
| 2262 | \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2263 | \param{bool}{ centre = true},\\ |
| 2264 | \param{int }{width=150}, \param{int }{height=200}} |
| 2265 | |
| 2266 | Pops up a dialog box containing a message, OK/Cancel buttons and a |
| 2267 | single-selection listbox. The user may choose an item and press OK to return a |
| 2268 | string or Cancel to return the empty string. Use |
| 2269 | \helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex} if empty string is a |
| 2270 | valid choice and if you want to be able to detect pressing Cancel reliably. |
| 2271 | |
| 2272 | You may pass the list of strings to choose from either using {\it choices} |
| 2273 | which is an array of {\it n} strings for the listbox or by using a single |
| 2274 | {\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}. |
| 2275 | |
| 2276 | If {\it centre} is true, the message text (which may include new line |
| 2277 | characters) is centred; if false, the message is left-justified. |
| 2278 | |
| 2279 | \wxheading{Include files} |
| 2280 | |
| 2281 | <wx/choicdlg.h> |
| 2282 | |
| 2283 | \perlnote{In wxPerl there is just an array reference in place of {\tt n} |
| 2284 | and {\tt choices}.} |
| 2285 | |
| 2286 | |
| 2287 | \membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex} |
| 2288 | |
| 2289 | \func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\ |
| 2290 | \param{const wxString\& }{caption},\\ |
| 2291 | \param{const wxArrayString\& }{aChoices},\\ |
| 2292 | \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2293 | \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} |
| 2294 | |
| 2295 | \func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\ |
| 2296 | \param{const wxString\& }{caption},\\ |
| 2297 | \param{int}{ n}, \param{const wxString\& }{choices[]},\\ |
| 2298 | \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2299 | \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} |
| 2300 | |
| 2301 | As {\bf wxGetSingleChoice} but returns the index representing the selected |
| 2302 | string. If the user pressed cancel, -1 is returned. |
| 2303 | |
| 2304 | \wxheading{Include files} |
| 2305 | |
| 2306 | <wx/choicdlg.h> |
| 2307 | |
| 2308 | \perlnote{In wxPerl there is just an array reference in place of {\tt n} |
| 2309 | and {\tt choices}.} |
| 2310 | |
| 2311 | |
| 2312 | \membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata} |
| 2313 | |
| 2314 | \func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\ |
| 2315 | \param{const wxString\& }{caption},\\ |
| 2316 | \param{const wxArrayString\& }{aChoices},\\ |
| 2317 | \param{const wxString\& }{client\_data[]},\\ |
| 2318 | \param{wxWindow *}{parent = NULL},\\ |
| 2319 | \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2320 | \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} |
| 2321 | |
| 2322 | \func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\ |
| 2323 | \param{const wxString\& }{caption},\\ |
| 2324 | \param{int}{ n}, \param{const wxString\& }{choices[]},\\ |
| 2325 | \param{const wxString\& }{client\_data[]},\\ |
| 2326 | \param{wxWindow *}{parent = NULL},\\ |
| 2327 | \param{int}{ x = -1}, \param{int}{ y = -1},\\ |
| 2328 | \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} |
| 2329 | |
| 2330 | As {\bf wxGetSingleChoice} but takes an array of client data pointers |
| 2331 | corresponding to the strings, and returns one of these pointers or NULL if |
| 2332 | Cancel was pressed. The {\it client\_data} array must have the same number of |
| 2333 | elements as {\it choices} or {\it aChoices}! |
| 2334 | |
| 2335 | \wxheading{Include files} |
| 2336 | |
| 2337 | <wx/choicdlg.h> |
| 2338 | |
| 2339 | \perlnote{In wxPerl there is just an array reference in place of {\tt n} |
| 2340 | and {\tt choices}, and the client data array must have the |
| 2341 | same length as the choices array.} |
| 2342 | |
| 2343 | |
| 2344 | \membersection{::wxIsBusy}\label{wxisbusy} |
| 2345 | |
| 2346 | \func{bool}{wxIsBusy}{\void} |
| 2347 | |
| 2348 | Returns true if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp |
| 2349 | \helpref{wxEndBusyCursor}{wxendbusycursor} calls. |
| 2350 | |
| 2351 | See also \helpref{wxBusyCursor}{wxbusycursor}. |
| 2352 | |
| 2353 | \wxheading{Include files} |
| 2354 | |
| 2355 | <wx/utils.h> |
| 2356 | |
| 2357 | |
| 2358 | \membersection{::wxMessageBox}\label{wxmessagebox} |
| 2359 | |
| 2360 | \func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK},\\ |
| 2361 | \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}} |
| 2362 | |
| 2363 | General purpose message dialog. {\it style} may be a bit list of the |
| 2364 | following identifiers: |
| 2365 | |
| 2366 | \begin{twocollist}\itemsep=0pt |
| 2367 | \twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with |
| 2368 | wxCANCEL.} |
| 2369 | \twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May only be combined with |
| 2370 | wxYES\_NO or wxOK.} |
| 2371 | \twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.} |
| 2372 | \twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.} |
| 2373 | \twocolitem{wxICON\_HAND}{Displays an error symbol.} |
| 2374 | \twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.} |
| 2375 | \twocolitem{wxICON\_QUESTION}{Displays a question mark symbol.} |
| 2376 | \twocolitem{wxICON\_INFORMATION}{Displays an information symbol.} |
| 2377 | \end{twocollist} |
| 2378 | |
| 2379 | The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. |
| 2380 | |
| 2381 | For example: |
| 2382 | |
| 2383 | \begin{verbatim} |
| 2384 | ... |
| 2385 | int answer = wxMessageBox("Quit program?", "Confirm", |
| 2386 | wxYES_NO | wxCANCEL, main_frame); |
| 2387 | if (answer == wxYES) |
| 2388 | main_frame->Close(); |
| 2389 | ... |
| 2390 | \end{verbatim} |
| 2391 | |
| 2392 | {\it message} may contain newline characters, in which case the |
| 2393 | message will be split into separate lines, to cater for large messages. |
| 2394 | |
| 2395 | \wxheading{Include files} |
| 2396 | |
| 2397 | <wx/msgdlg.h> |
| 2398 | |
| 2399 | |
| 2400 | \membersection{::wxShowTip}\label{wxshowtip} |
| 2401 | |
| 2402 | \func{bool}{wxShowTip}{\param{wxWindow *}{parent}, |
| 2403 | \param{wxTipProvider *}{tipProvider}, |
| 2404 | \param{bool }{showAtStartup = true}} |
| 2405 | |
| 2406 | This function shows a "startup tip" to the user. The return value is the |
| 2407 | state of the `Show tips at startup' checkbox. |
| 2408 | |
| 2409 | \docparam{parent}{The parent window for the modal dialog} |
| 2410 | |
| 2411 | \docparam{tipProvider}{An object which is used to get the text of the tips. |
| 2412 | It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.} |
| 2413 | |
| 2414 | \docparam{showAtStartup}{Should be true if startup tips are shown, false |
| 2415 | otherwise. This is used as the initial value for "Show tips at startup" |
| 2416 | checkbox which is shown in the tips dialog.} |
| 2417 | |
| 2418 | \wxheading{See also} |
| 2419 | |
| 2420 | \helpref{Tips overview}{tipsoverview} |
| 2421 | |
| 2422 | \wxheading{Include files} |
| 2423 | |
| 2424 | <wx/tipdlg.h> |
| 2425 | |
| 2426 | |
| 2427 | |
| 2428 | |
| 2429 | \section{Math functions}\label{mathfunctions} |
| 2430 | |
| 2431 | \wxheading{Include files} |
| 2432 | |
| 2433 | <wx/math.h> |
| 2434 | |
| 2435 | |
| 2436 | \membersection{wxFinite}\label{wxfinite} |
| 2437 | |
| 2438 | \func{int}{wxFinite}{\param{double }{x}} |
| 2439 | |
| 2440 | Returns a non-zero value if {\it x} is neither infinite nor NaN (not a number), |
| 2441 | returns 0 otherwise. |
| 2442 | |
| 2443 | |
| 2444 | \membersection{wxIsNaN}\label{wxisnan} |
| 2445 | |
| 2446 | \func{bool}{wxIsNaN}{\param{double }{x}} |
| 2447 | |
| 2448 | Returns a non-zero value if {\it x} is NaN (not a number), returns 0 |
| 2449 | otherwise. |
| 2450 | |
| 2451 | |
| 2452 | |
| 2453 | |
| 2454 | \section{GDI functions}\label{gdifunctions} |
| 2455 | |
| 2456 | The following are relevant to the GDI (Graphics Device Interface). |
| 2457 | |
| 2458 | \wxheading{Include files} |
| 2459 | |
| 2460 | <wx/gdicmn.h> |
| 2461 | |
| 2462 | |
| 2463 | \membersection{wxBITMAP}\label{wxbitmapmacro} |
| 2464 | |
| 2465 | \func{}{wxBITMAP}{bitmapName} |
| 2466 | |
| 2467 | This macro loads a bitmap from either application resources (on the platforms |
| 2468 | for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to |
| 2469 | avoid using {\tt \#ifdef}s when creating bitmaps. |
| 2470 | |
| 2471 | \wxheading{See also} |
| 2472 | |
| 2473 | \helpref{Bitmaps and icons overview}{wxbitmapoverview}, |
| 2474 | \helpref{wxICON}{wxiconmacro} |
| 2475 | |
| 2476 | \wxheading{Include files} |
| 2477 | |
| 2478 | <wx/gdicmn.h> |
| 2479 | |
| 2480 | |
| 2481 | \membersection{::wxClientDisplayRect}\label{wxclientdisplayrect} |
| 2482 | |
| 2483 | \func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y}, |
| 2484 | \param{int *}{width}, \param{int *}{height}} |
| 2485 | |
| 2486 | \func{wxRect}{wxGetClientDisplayRect}{\void} |
| 2487 | |
| 2488 | Returns the dimensions of the work area on the display. On Windows |
| 2489 | this means the area not covered by the taskbar, etc. Other platforms |
| 2490 | are currently defaulting to the whole display until a way is found to |
| 2491 | provide this info for all window managers, etc. |
| 2492 | |
| 2493 | |
| 2494 | \membersection{::wxColourDisplay}\label{wxcolourdisplay} |
| 2495 | |
| 2496 | \func{bool}{wxColourDisplay}{\void} |
| 2497 | |
| 2498 | Returns true if the display is colour, false otherwise. |
| 2499 | |
| 2500 | |
| 2501 | \membersection{::wxDisplayDepth}\label{wxdisplaydepth} |
| 2502 | |
| 2503 | \func{int}{wxDisplayDepth}{\void} |
| 2504 | |
| 2505 | Returns the depth of the display (a value of 1 denotes a monochrome display). |
| 2506 | |
| 2507 | |
| 2508 | \membersection{::wxDisplaySize}\label{wxdisplaysize} |
| 2509 | |
| 2510 | \func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} |
| 2511 | |
| 2512 | \func{wxSize}{wxGetDisplaySize}{\void} |
| 2513 | |
| 2514 | Returns the display size in pixels. |
| 2515 | |
| 2516 | |
| 2517 | \membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm} |
| 2518 | |
| 2519 | \func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}} |
| 2520 | |
| 2521 | \func{wxSize}{wxGetDisplaySizeMM}{\void} |
| 2522 | |
| 2523 | Returns the display size in millimeters. |
| 2524 | |
| 2525 | |
| 2526 | \membersection{::wxDROP\_ICON}\label{wxdropicon} |
| 2527 | |
| 2528 | \func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}} |
| 2529 | |
| 2530 | This macro creates either a cursor (MSW) or an icon (elsewhere) with the given |
| 2531 | name. Under MSW, the cursor is loaded from the resource file and the icon is |
| 2532 | loaded from XPM file under other platforms. |
| 2533 | |
| 2534 | This macro should be used with |
| 2535 | \helpref{wxDropSource constructor}{wxdropsourcewxdropsource}. |
| 2536 | |
| 2537 | \wxheading{Include files} |
| 2538 | |
| 2539 | <wx/dnd.h> |
| 2540 | |
| 2541 | |
| 2542 | \membersection{wxICON}\label{wxiconmacro} |
| 2543 | |
| 2544 | \func{}{wxICON}{iconName} |
| 2545 | |
| 2546 | This macro loads an icon from either application resources (on the platforms |
| 2547 | for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to |
| 2548 | avoid using {\tt \#ifdef}s when creating icons. |
| 2549 | |
| 2550 | \wxheading{See also} |
| 2551 | |
| 2552 | \helpref{Bitmaps and icons overview}{wxbitmapoverview}, |
| 2553 | \helpref{wxBITMAP}{wxbitmapmacro} |
| 2554 | |
| 2555 | \wxheading{Include files} |
| 2556 | |
| 2557 | <wx/gdicmn.h> |
| 2558 | |
| 2559 | |
| 2560 | \membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable} |
| 2561 | |
| 2562 | \func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY}, |
| 2563 | \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}} |
| 2564 | |
| 2565 | Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc}) |
| 2566 | makes it into a placeable metafile by prepending a header containing the given |
| 2567 | bounding box. The bounding box may be obtained from a device context after drawing |
| 2568 | into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. |
| 2569 | |
| 2570 | In addition to adding the placeable metafile header, this function adds |
| 2571 | the equivalent of the following code to the start of the metafile data: |
| 2572 | |
| 2573 | \begin{verbatim} |
| 2574 | SetMapMode(dc, MM_ANISOTROPIC); |
| 2575 | SetWindowOrg(dc, minX, minY); |
| 2576 | SetWindowExt(dc, maxX - minX, maxY - minY); |
| 2577 | \end{verbatim} |
| 2578 | |
| 2579 | This simulates the wxMM\_TEXT mapping mode, which wxWidgets assumes. |
| 2580 | |
| 2581 | Placeable metafiles may be imported by many Windows applications, and can be |
| 2582 | used in RTF (Rich Text Format) files. |
| 2583 | |
| 2584 | {\it scale} allows the specification of scale for the metafile. |
| 2585 | |
| 2586 | This function is only available under Windows. |
| 2587 | |
| 2588 | |
| 2589 | \membersection{::wxSetCursor}\label{wxsetcursor} |
| 2590 | |
| 2591 | \func{void}{wxSetCursor}{\param{wxCursor *}{cursor}} |
| 2592 | |
| 2593 | Globally sets the cursor; only has an effect in Windows and GTK. |
| 2594 | See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. |
| 2595 | |
| 2596 | |
| 2597 | |
| 2598 | \section{Printer settings}\label{printersettings} |
| 2599 | |
| 2600 | {\bf NB:} These routines are obsolete and should no longer be used! |
| 2601 | |
| 2602 | The following functions are used to control PostScript printing. Under |
| 2603 | Windows, PostScript output can only be sent to a file. |
| 2604 | |
| 2605 | \wxheading{Include files} |
| 2606 | |
| 2607 | <wx/dcps.h> |
| 2608 | |
| 2609 | |
| 2610 | \membersection{::wxGetPrinterCommand}\label{wxgetprintercommand} |
| 2611 | |
| 2612 | \func{wxString}{wxGetPrinterCommand}{\void} |
| 2613 | |
| 2614 | Gets the printer command used to print a file. The default is {\tt lpr}. |
| 2615 | |
| 2616 | |
| 2617 | \membersection{::wxGetPrinterFile}\label{wxgetprinterfile} |
| 2618 | |
| 2619 | \func{wxString}{wxGetPrinterFile}{\void} |
| 2620 | |
| 2621 | Gets the PostScript output filename. |
| 2622 | |
| 2623 | |
| 2624 | \membersection{::wxGetPrinterMode}\label{wxgetprintermode} |
| 2625 | |
| 2626 | \func{int}{wxGetPrinterMode}{\void} |
| 2627 | |
| 2628 | Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). |
| 2629 | The default is PS\_PREVIEW. |
| 2630 | |
| 2631 | |
| 2632 | \membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions} |
| 2633 | |
| 2634 | \func{wxString}{wxGetPrinterOptions}{\void} |
| 2635 | |
| 2636 | Gets the additional options for the print command (e.g. specific printer). The default is nothing. |
| 2637 | |
| 2638 | |
| 2639 | \membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation} |
| 2640 | |
| 2641 | \func{int}{wxGetPrinterOrientation}{\void} |
| 2642 | |
| 2643 | Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. |
| 2644 | |
| 2645 | |
| 2646 | \membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand} |
| 2647 | |
| 2648 | \func{wxString}{wxGetPrinterPreviewCommand}{\void} |
| 2649 | |
| 2650 | Gets the command used to view a PostScript file. The default depends on the platform. |
| 2651 | |
| 2652 | |
| 2653 | \membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling} |
| 2654 | |
| 2655 | \func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}} |
| 2656 | |
| 2657 | Gets the scaling factor for PostScript output. The default is 1.0, 1.0. |
| 2658 | |
| 2659 | |
| 2660 | \membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation} |
| 2661 | |
| 2662 | \func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}} |
| 2663 | |
| 2664 | Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. |
| 2665 | |
| 2666 | |
| 2667 | \membersection{::wxSetPrinterCommand}\label{wxsetprintercommand} |
| 2668 | |
| 2669 | \func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}} |
| 2670 | |
| 2671 | Sets the printer command used to print a file. The default is {\tt lpr}. |
| 2672 | |
| 2673 | |
| 2674 | \membersection{::wxSetPrinterFile}\label{wxsetprinterfile} |
| 2675 | |
| 2676 | \func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}} |
| 2677 | |
| 2678 | Sets the PostScript output filename. |
| 2679 | |
| 2680 | |
| 2681 | \membersection{::wxSetPrinterMode}\label{wxsetprintermode} |
| 2682 | |
| 2683 | \func{void}{wxSetPrinterMode}{\param{int }{mode}} |
| 2684 | |
| 2685 | Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). |
| 2686 | The default is PS\_PREVIEW. |
| 2687 | |
| 2688 | |
| 2689 | \membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions} |
| 2690 | |
| 2691 | \func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}} |
| 2692 | |
| 2693 | Sets the additional options for the print command (e.g. specific printer). The default is nothing. |
| 2694 | |
| 2695 | |
| 2696 | \membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation} |
| 2697 | |
| 2698 | \func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}} |
| 2699 | |
| 2700 | Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. |
| 2701 | |
| 2702 | |
| 2703 | \membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand} |
| 2704 | |
| 2705 | \func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}} |
| 2706 | |
| 2707 | Sets the command used to view a PostScript file. The default depends on the platform. |
| 2708 | |
| 2709 | |
| 2710 | \membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling} |
| 2711 | |
| 2712 | \func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}} |
| 2713 | |
| 2714 | Sets the scaling factor for PostScript output. The default is 1.0, 1.0. |
| 2715 | |
| 2716 | |
| 2717 | \membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation} |
| 2718 | |
| 2719 | \func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}} |
| 2720 | |
| 2721 | Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. |
| 2722 | |
| 2723 | |
| 2724 | |
| 2725 | \section{Clipboard functions}\label{clipsboard} |
| 2726 | |
| 2727 | These clipboard functions are implemented for Windows only. The use of these functions |
| 2728 | is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard} |
| 2729 | class instead. |
| 2730 | |
| 2731 | \wxheading{Include files} |
| 2732 | |
| 2733 | <wx/clipbrd.h> |
| 2734 | |
| 2735 | |
| 2736 | \membersection{::wxClipboardOpen}\label{functionwxclipboardopen} |
| 2737 | |
| 2738 | \func{bool}{wxClipboardOpen}{\void} |
| 2739 | |
| 2740 | Returns true if this application has already opened the clipboard. |
| 2741 | |
| 2742 | |
| 2743 | \membersection{::wxCloseClipboard}\label{wxcloseclipboard} |
| 2744 | |
| 2745 | \func{bool}{wxCloseClipboard}{\void} |
| 2746 | |
| 2747 | Closes the clipboard to allow other applications to use it. |
| 2748 | |
| 2749 | |
| 2750 | \membersection{::wxEmptyClipboard}\label{wxemptyclipboard} |
| 2751 | |
| 2752 | \func{bool}{wxEmptyClipboard}{\void} |
| 2753 | |
| 2754 | Empties the clipboard. |
| 2755 | |
| 2756 | |
| 2757 | \membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats} |
| 2758 | |
| 2759 | \func{int}{wxEnumClipboardFormats}{\param{int}{ dataFormat}} |
| 2760 | |
| 2761 | Enumerates the formats found in a list of available formats that belong |
| 2762 | to the clipboard. Each call to this function specifies a known |
| 2763 | available format; the function returns the format that appears next in |
| 2764 | the list. |
| 2765 | |
| 2766 | {\it dataFormat} specifies a known format. If this parameter is zero, |
| 2767 | the function returns the first format in the list. |
| 2768 | |
| 2769 | The return value specifies the next known clipboard data format if the |
| 2770 | function is successful. It is zero if the {\it dataFormat} parameter specifies |
| 2771 | the last format in the list of available formats, or if the clipboard |
| 2772 | is not open. |
| 2773 | |
| 2774 | Before it enumerates the formats function, an application must open the clipboard by using the |
| 2775 | wxOpenClipboard function. |
| 2776 | |
| 2777 | |
| 2778 | \membersection{::wxGetClipboardData}\label{wxgetclipboarddata} |
| 2779 | |
| 2780 | \func{wxObject *}{wxGetClipboardData}{\param{int}{ dataFormat}} |
| 2781 | |
| 2782 | Gets data from the clipboard. |
| 2783 | |
| 2784 | {\it dataFormat} may be one of: |
| 2785 | |
| 2786 | \begin{itemize}\itemsep=0pt |
| 2787 | \item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string. |
| 2788 | \item wxCF\_BITMAP: returns a new wxBitmap. |
| 2789 | \end{itemize} |
| 2790 | |
| 2791 | The clipboard must have previously been opened for this call to succeed. |
| 2792 | |
| 2793 | |
| 2794 | \membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname} |
| 2795 | |
| 2796 | \func{bool}{wxGetClipboardFormatName}{\param{int}{ dataFormat}, \param{const wxString\& }{formatName}, \param{int}{ maxCount}} |
| 2797 | |
| 2798 | Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum |
| 2799 | length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format. |
| 2800 | |
| 2801 | |
| 2802 | \membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable} |
| 2803 | |
| 2804 | \func{bool}{wxIsClipboardFormatAvailable}{\param{int}{ dataFormat}} |
| 2805 | |
| 2806 | Returns true if the given data format is available on the clipboard. |
| 2807 | |
| 2808 | |
| 2809 | \membersection{::wxOpenClipboard}\label{wxopenclipboard} |
| 2810 | |
| 2811 | \func{bool}{wxOpenClipboard}{\void} |
| 2812 | |
| 2813 | Opens the clipboard for passing data to it or getting data from it. |
| 2814 | |
| 2815 | |
| 2816 | \membersection{::wxRegisterClipboardFormat}\label{wxregisterclipboardformat} |
| 2817 | |
| 2818 | \func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}} |
| 2819 | |
| 2820 | Registers the clipboard data format name and returns an identifier. |
| 2821 | |
| 2822 | |
| 2823 | \membersection{::wxSetClipboardData}\label{wxsetclipboarddata} |
| 2824 | |
| 2825 | \func{bool}{wxSetClipboardData}{\param{int}{ dataFormat}, \param{wxObject*}{ data}, \param{int}{ width}, \param{int}{ height}} |
| 2826 | |
| 2827 | Passes data to the clipboard. |
| 2828 | |
| 2829 | {\it dataFormat} may be one of: |
| 2830 | |
| 2831 | \begin{itemize}\itemsep=0pt |
| 2832 | \item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string. |
| 2833 | \item wxCF\_BITMAP: {\it data} is a wxBitmap. |
| 2834 | \item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap). |
| 2835 | \item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions. |
| 2836 | \end{itemize} |
| 2837 | |
| 2838 | The clipboard must have previously been opened for this call to succeed. |
| 2839 | |
| 2840 | |
| 2841 | \section{Miscellaneous functions}\label{miscellany} |
| 2842 | |
| 2843 | |
| 2844 | \membersection{wxBase64Decode}\label{wxbase64decode} |
| 2845 | |
| 2846 | \func{size\_t}{wxBase64Decode}{\param{void *}{dst}, \param{size\_t }{dstLen}, |
| 2847 | \param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN}, |
| 2848 | \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict}, |
| 2849 | \param{size\_t }{*posErr = \NULL}} |
| 2850 | |
| 2851 | \func{wxMemoryBuffer}{wxBase64Decode}{\\ |
| 2852 | \param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN},\\ |
| 2853 | \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\ |
| 2854 | \param{size\_t }{*posErr = \NULL}} |
| 2855 | |
| 2856 | These function decode a Base64-encoded string. The first version is a raw |
| 2857 | decoding function and decodes the data into the provided buffer \arg{dst} of |
| 2858 | the given size \arg{dstLen}. An error is returned if the buffer is not large |
| 2859 | enough -- that is not at least \helpref{wxBase64DecodedSize(srcLen)}{wxbase64decodedsize} |
| 2860 | bytes. The second version allocates memory internally and returns it as |
| 2861 | \helpref{wxMemoryBuffer}{wxmemorybuffer} and is recommended for normal use. |
| 2862 | |
| 2863 | The first version returns the number of bytes written to the buffer or the |
| 2864 | necessary buffer size if \arg{dst} was \NULL or \texttt{wxCONV\_FAILED} on |
| 2865 | error, e.g. if the output buffer is too small or invalid characters were |
| 2866 | encountered in the input string. The second version returns a buffer with the |
| 2867 | base64 decoded binary equivalent of the input string. In neither case is the |
| 2868 | buffer NUL-terminated. |
| 2869 | |
| 2870 | \wxheading{Parameters} |
| 2871 | |
| 2872 | \docparam{dst}{Pointer to output buffer, may be \NULL to just compute the |
| 2873 | necessary buffer size.} |
| 2874 | |
| 2875 | \docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is |
| 2876 | \NULL.} |
| 2877 | |
| 2878 | \docparam{src}{The input string, must not be \NULL.} |
| 2879 | |
| 2880 | \docparam{srcLen}{The length of the input string or special value |
| 2881 | \texttt{wxNO\_LEN} if the string is \NUL-terminated and the length should be |
| 2882 | computed by this function itself.} |
| 2883 | |
| 2884 | \docparam{mode}{This parameter specifies the function behaviour when invalid |
| 2885 | characters are encountered in input. By default, any such character stops the |
| 2886 | decoding with error. If the mode is wxBase64DecodeMode\_SkipWS, then the white |
| 2887 | space characters are silently skipped instead. And if it is |
| 2888 | wxBase64DecodeMode\_Relaxed, then all invalid characters are skipped.} |
| 2889 | |
| 2890 | \docparam{posErr}{If this pointer is non-\NULL and an error occurs during |
| 2891 | decoding, it is filled with the index of the invalid character.} |
| 2892 | |
| 2893 | \wxheading{Include files} |
| 2894 | |
| 2895 | <wx/base64.h> |
| 2896 | |
| 2897 | |
| 2898 | \membersection{wxBase64DecodedSize}\label{wxbase64decodedsize} |
| 2899 | |
| 2900 | \func{size\_t}{wxBase64DecodedSize}{\param{size\_t }{srcLen}} |
| 2901 | |
| 2902 | Returns the size of the buffer necessary to contain the data encoded in a |
| 2903 | base64 string of length \arg{srcLen}. This can be useful for allocating a |
| 2904 | buffer to be passed to \helpref{wxBase64Decode}{wxbase64decode}. |
| 2905 | |
| 2906 | |
| 2907 | \membersection{wxBase64Encode}\label{wxbase64encode} |
| 2908 | |
| 2909 | \func{size\_t}{wxBase64Encode}{\param{char *}{dst}, \param{size\_t }{dstLen}, |
| 2910 | \param{const void *}{src}, \param{size\_t }{srcLen}} |
| 2911 | |
| 2912 | \func{wxString}{wxBase64Encode}{\param{const void *}{src}, \param{size\_t }{srcLen}} |
| 2913 | |
| 2914 | \func{wxString}{wxBase64Encode}{\param{const wxMemoryBuffer\& }{buf}} |
| 2915 | |
| 2916 | These functions encode the given data using base64. The first of them is the |
| 2917 | raw encoding function writing the output string into provided buffer while the |
| 2918 | other ones return the output as wxString. There is no error return for these |
| 2919 | functions except for the first one which returns \texttt{wxCONV\_FAILED} if the |
| 2920 | output buffer is too small. To allocate the buffer of the correct size, use |
| 2921 | \helpref{wxBase64EncodedSize}{wxbase64encodedsize} or call this function with |
| 2922 | \arg{dst} set to \NULL -- it will then return the necessary buffer size. |
| 2923 | |
| 2924 | \wxheading{Parameters} |
| 2925 | |
| 2926 | \docparam{dst}{The output buffer, may be \NULL to retrieve the needed buffer |
| 2927 | size.} |
| 2928 | |
| 2929 | \docparam{dstLen}{The output buffer size, ignored if \arg{dst} is \NULL.} |
| 2930 | |
| 2931 | \docparam{src}{The input buffer, must not be \NULL.} |
| 2932 | |
| 2933 | \docparam{srcLen}{The length of the input data.} |
| 2934 | |
| 2935 | \wxheading{Include files} |
| 2936 | |
| 2937 | <wx/base64.h> |
| 2938 | |
| 2939 | |
| 2940 | \membersection{wxBase64EncodedSize}\label{wxbase64encodedsize} |
| 2941 | |
| 2942 | \func{size\_t}{wxBase64EncodedSize}{\param{size\_t }{len}} |
| 2943 | |
| 2944 | Returns the length of the string with base64 representation of a buffer of |
| 2945 | specified size \arg{len}. This can be useful for allocating the buffer passed |
| 2946 | to \helpref{wxBase64Encode}{wxbase64encode}. |
| 2947 | |
| 2948 | |
| 2949 | \membersection{wxCONCAT}\label{wxconcat} |
| 2950 | |
| 2951 | \func{}{wxCONCAT}{\param{}{x}, \param{}{y}} |
| 2952 | |
| 2953 | This macro returns the concatenation of two tokens \arg{x} and \arg{y}. |
| 2954 | |
| 2955 | |
| 2956 | \membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction} |
| 2957 | |
| 2958 | \func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}} |
| 2959 | |
| 2960 | When loading a function from a DLL you always have to cast the returned |
| 2961 | {\tt void *} pointer to the correct type and, even more annoyingly, you have to |
| 2962 | repeat this type twice if you want to declare and define a function pointer all |
| 2963 | in one line |
| 2964 | |
| 2965 | This macro makes this slightly less painful by allowing you to specify the |
| 2966 | type only once, as the first parameter, and creating a variable of this type |
| 2967 | named after the function but with {\tt pfn} prefix and initialized with the |
| 2968 | function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary} |
| 2969 | \arg{dynlib}. |
| 2970 | |
| 2971 | \wxheading{Parameters} |
| 2972 | |
| 2973 | \docparam{type}{the type of the function} |
| 2974 | |
| 2975 | \docparam{name}{the name of the function to load, not a string (without quotes, |
| 2976 | it is quoted automatically by the macro)} |
| 2977 | |
| 2978 | \docparam{dynlib}{the library to load the function from} |
| 2979 | |
| 2980 | |
| 2981 | |
| 2982 | \membersection{wxDEPRECATED}\label{wxdeprecated} |
| 2983 | |
| 2984 | This macro can be used around a function declaration to generate warnings |
| 2985 | indicating that this function is deprecated (i.e. obsolete and planned to be |
| 2986 | removed in the future) when it is used. Only Visual C++ 7 and higher and g++ |
| 2987 | compilers currently support this functionality. |
| 2988 | |
| 2989 | Example of use: |
| 2990 | \begin{verbatim} |
| 2991 | // old function, use wxString version instead |
| 2992 | wxDEPRECATED( void wxGetSomething(char *buf, size_t len) ); |
| 2993 | |
| 2994 | // ... |
| 2995 | wxString wxGetSomething(); |
| 2996 | \end{verbatim} |
| 2997 | |
| 2998 | |
| 2999 | \membersection{wxDEPRECATED\_BUT\_USED\_INTERNALLY}\label{wxdeprecatedbutusedinternally} |
| 3000 | |
| 3001 | This is a special version of \helpref{wxDEPRECATED}{wxdeprecated} macro which |
| 3002 | only does something when the deprecated function is used from the code outside |
| 3003 | wxWidgets itself but doesn't generate warnings when it is used from wxWidgets. |
| 3004 | It is used with the virtual functions which are called by the library itself -- |
| 3005 | even if such function is deprecated the library still has to call it to ensure |
| 3006 | that the existing code overriding it continues to work, but the use of this |
| 3007 | macro ensures that a deprecation warning will be generated if this function is |
| 3008 | used from the user code or, in case of Visual C++, even when it is simply |
| 3009 | overridden. |
| 3010 | |
| 3011 | |
| 3012 | \membersection{wxDEPRECATED\_INLINE}\label{wxdeprecatedinline} |
| 3013 | |
| 3014 | \func{}{wxDEPRECATED\_INLINE}{\param{}{func}, \param{}{body}} |
| 3015 | |
| 3016 | This macro is similar to \helpref{wxDEPRECATED}{wxdeprecated} but can be used |
| 3017 | to not only declare the function \arg{func} as deprecated but to also provide |
| 3018 | its (inline) implementation \arg{body}. |
| 3019 | |
| 3020 | It can be used as following: |
| 3021 | \begin{verbatim} |
| 3022 | class wxFoo |
| 3023 | { |
| 3024 | public: |
| 3025 | // OldMethod() is deprecated, use NewMethod() instead |
| 3026 | void NewMethod(); |
| 3027 | wxDEPRECATED_INLINE( void OldMethod(), NewMethod() ); |
| 3028 | }; |
| 3029 | \end{verbatim} |
| 3030 | |
| 3031 | \membersection{wxEXPLICIT}\label{wxexplicit} |
| 3032 | |
| 3033 | {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if |
| 3034 | the compiler supports it or nothing otherwise. Thus, it can be used even in the |
| 3035 | code which might have to be compiled with an old compiler without support for |
| 3036 | this language feature but still take advantage of it when it is available. |
| 3037 | |
| 3038 | |
| 3039 | |
| 3040 | \membersection{::wxGetKeyState}\label{wxgetkeystate} |
| 3041 | |
| 3042 | \func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}} |
| 3043 | |
| 3044 | For normal keys, returns \true if the specified key is currently down. |
| 3045 | |
| 3046 | For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns |
| 3047 | \true if the key is toggled such that its LED indicator is lit. There is |
| 3048 | currently no way to test whether togglable keys are up or down. |
| 3049 | |
| 3050 | Even though there are virtual key codes defined for mouse buttons, they |
| 3051 | cannot be used with this function currently. |
| 3052 | |
| 3053 | \wxheading{Include files} |
| 3054 | |
| 3055 | <wx/utils.h> |
| 3056 | |
| 3057 | |
| 3058 | \membersection{wxLL}\label{wxll} |
| 3059 | |
| 3060 | \func{wxLongLong\_t}{wxLL}{\param{}{number}} |
| 3061 | |
| 3062 | This macro is defined for the platforms with a native 64 bit integer type and |
| 3063 | allows to define 64 bit compile time constants: |
| 3064 | |
| 3065 | \begin{verbatim} |
| 3066 | #ifdef wxLongLong_t |
| 3067 | wxLongLong_t ll = wxLL(0x1234567890abcdef); |
| 3068 | #endif |
| 3069 | \end{verbatim} |
| 3070 | |
| 3071 | \wxheading{Include files} |
| 3072 | |
| 3073 | <wx/longlong.h> |
| 3074 | |
| 3075 | \wxheading{See also} |
| 3076 | |
| 3077 | \helpref{wxULL}{wxull}, \helpref{wxLongLong}{wxlonglong} |
| 3078 | |
| 3079 | |
| 3080 | \membersection{wxLongLongFmtSpec}\label{wxlonglongfmtspec} |
| 3081 | |
| 3082 | This macro is defined to contain the {\tt printf()} format specifier using |
| 3083 | which 64 bit integer numbers (i.e. those of type {\tt wxLongLong\_t}) can be |
| 3084 | printed. Example of using it: |
| 3085 | |
| 3086 | \begin{verbatim} |
| 3087 | #ifdef wxLongLong_t |
| 3088 | wxLongLong_t ll = wxLL(0x1234567890abcdef); |
| 3089 | printf("Long long = %" wxLongLongFmtSpec "x\n", ll); |
| 3090 | #endif |
| 3091 | \end{verbatim} |
| 3092 | |
| 3093 | \wxheading{See also} |
| 3094 | |
| 3095 | \helpref{wxLL}{wxll} |
| 3096 | |
| 3097 | \wxheading{Include files} |
| 3098 | |
| 3099 | <wx/longlong.h> |
| 3100 | |
| 3101 | |
| 3102 | \membersection{::wxNewId}\label{wxnewid} |
| 3103 | |
| 3104 | \func{long}{wxNewId}{\void} |
| 3105 | |
| 3106 | This function is deprecated as the ids generated by it can conflict with the |
| 3107 | ids defined by the user code, use \texttt{wxID\_ANY} to assign ids which are |
| 3108 | guaranteed to not conflict with the user-defined ids for the controls and menu |
| 3109 | items you create instead of using this function. |
| 3110 | |
| 3111 | |
| 3112 | Generates an integer identifier unique to this run of the program. |
| 3113 | |
| 3114 | \wxheading{Include files} |
| 3115 | |
| 3116 | <wx/utils.h> |
| 3117 | |
| 3118 | |
| 3119 | \membersection{wxON\_BLOCK\_EXIT}\label{wxonblockexit} |
| 3120 | |
| 3121 | \func{}{wxON\_BLOCK\_EXIT0}{\param{}{func}} |
| 3122 | |
| 3123 | \func{}{wxON\_BLOCK\_EXIT1}{\param{}{func}, \param{}{p1}} |
| 3124 | |
| 3125 | \func{}{wxON\_BLOCK\_EXIT2}{\param{}{func}, \param{}{p1}, \param{}{p2}} |
| 3126 | |
| 3127 | This family of macros allows to ensure that the global function \arg{func} |
| 3128 | with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is |
| 3129 | executed on scope exit, whether due to a normal function return or because an |
| 3130 | exception has been thrown. A typical example of its usage: |
| 3131 | \begin{verbatim} |
| 3132 | void *buf = malloc(size); |
| 3133 | wxON_BLOCK_EXIT1(free, buf); |
| 3134 | \end{verbatim} |
| 3135 | |
| 3136 | Please see the original article by Andrei Alexandrescu and Petru Marginean |
| 3137 | published in December 2000 issue of \emph{C/C++ Users Journal} for more |
| 3138 | details. |
| 3139 | |
| 3140 | \wxheading{Include files} |
| 3141 | |
| 3142 | <wx/scopeguard.h> |
| 3143 | |
| 3144 | \wxheading{See also} |
| 3145 | |
| 3146 | \helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj} |
| 3147 | |
| 3148 | |
| 3149 | \membersection{wxON\_BLOCK\_EXIT\_OBJ}\label{wxonblockexitobj} |
| 3150 | |
| 3151 | \func{}{wxON\_BLOCK\_EXIT\_OBJ0}{\param{}{obj}, \param{}{method}} |
| 3152 | |
| 3153 | \func{}{wxON\_BLOCK\_EXIT\_OBJ1}{\param{}{obj}, \param{}{method}, \param{}{p1}} |
| 3154 | |
| 3155 | \func{}{wxON\_BLOCK\_EXIT\_OBJ2}{\param{}{obj}, \param{}{method}, \param{}{p1}, \param{}{p2}} |
| 3156 | |
| 3157 | This family of macros is similar to \helpref{wxON\_BLOCK\_EXIT}{wxonblockexit} |
| 3158 | but calls a method of the given object instead of a free function. |
| 3159 | |
| 3160 | \wxheading{Include files} |
| 3161 | |
| 3162 | <wx/scopeguard.h> |
| 3163 | |
| 3164 | |
| 3165 | \membersection{::wxRegisterId}\label{wxregisterid} |
| 3166 | |
| 3167 | \func{void}{wxRegisterId}{\param{long}{ id}} |
| 3168 | |
| 3169 | Ensures that ids subsequently generated by {\bf NewId} do not clash with |
| 3170 | the given {\bf id}. |
| 3171 | |
| 3172 | \wxheading{Include files} |
| 3173 | |
| 3174 | <wx/utils.h> |
| 3175 | |
| 3176 | |
| 3177 | \membersection{::wxDDECleanUp}\label{wxddecleanup} |
| 3178 | |
| 3179 | \func{void}{wxDDECleanUp}{\void} |
| 3180 | |
| 3181 | Called when wxWidgets exits, to clean up the DDE system. This no longer needs to be |
| 3182 | called by the application. |
| 3183 | |
| 3184 | See also \helpref{wxDDEInitialize}{wxddeinitialize}. |
| 3185 | |
| 3186 | \wxheading{Include files} |
| 3187 | |
| 3188 | <wx/dde.h> |
| 3189 | |
| 3190 | |
| 3191 | \membersection{::wxDDEInitialize}\label{wxddeinitialize} |
| 3192 | |
| 3193 | \func{void}{wxDDEInitialize}{\void} |
| 3194 | |
| 3195 | Initializes the DDE system. May be called multiple times without harm. |
| 3196 | |
| 3197 | This no longer needs to be called by the application: it will be called |
| 3198 | by wxWidgets if necessary. |
| 3199 | |
| 3200 | See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},\rtfsp |
| 3201 | \helpref{wxDDECleanUp}{wxddecleanup}. |
| 3202 | |
| 3203 | \wxheading{Include files} |
| 3204 | |
| 3205 | <wx/dde.h> |
| 3206 | |
| 3207 | |
| 3208 | \membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows} |
| 3209 | |
| 3210 | \func{void}{wxEnableTopLevelWindows}{\param{bool}{ enable = true}} |
| 3211 | |
| 3212 | This function enables or disables all top level windows. It is used by |
| 3213 | \helpref{::wxSafeYield}{wxsafeyield}. |
| 3214 | |
| 3215 | \wxheading{Include files} |
| 3216 | |
| 3217 | <wx/utils.h> |
| 3218 | |
| 3219 | |
| 3220 | \membersection{::wxFindMenuItemId}\label{wxfindmenuitemid} |
| 3221 | |
| 3222 | \func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}} |
| 3223 | |
| 3224 | Find a menu item identifier associated with the given frame's menu bar. |
| 3225 | |
| 3226 | \wxheading{Include files} |
| 3227 | |
| 3228 | <wx/utils.h> |
| 3229 | |
| 3230 | |
| 3231 | \membersection{::wxFindWindowByLabel}\label{wxfindwindowbylabel} |
| 3232 | |
| 3233 | \func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}} |
| 3234 | |
| 3235 | {\bf NB:} This function is obsolete, please use |
| 3236 | \helpref{wxWindow::FindWindowByLabel}{wxwindowfindwindowbylabel} instead. |
| 3237 | |
| 3238 | Find a window by its label. Depending on the type of window, the label may be a window title |
| 3239 | or panel item label. If {\it parent} is NULL, the search will start from all top-level |
| 3240 | frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. |
| 3241 | The search is recursive in both cases. |
| 3242 | |
| 3243 | \wxheading{Include files} |
| 3244 | |
| 3245 | <wx/utils.h> |
| 3246 | |
| 3247 | |
| 3248 | \membersection{::wxFindWindowByName}\label{wxfindwindowbyname} |
| 3249 | |
| 3250 | \func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}} |
| 3251 | |
| 3252 | {\bf NB:} This function is obsolete, please use |
| 3253 | \helpref{wxWindow::FindWindowByName}{wxwindowfindwindowbyname} instead. |
| 3254 | |
| 3255 | Find a window by its name (as given in a window constructor or {\bf Create} function call). |
| 3256 | If {\it parent} is NULL, the search will start from all top-level |
| 3257 | frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. |
| 3258 | The search is recursive in both cases. |
| 3259 | |
| 3260 | If no such named window is found, {\bf wxFindWindowByLabel} is called. |
| 3261 | |
| 3262 | \wxheading{Include files} |
| 3263 | |
| 3264 | <wx/utils.h> |
| 3265 | |
| 3266 | |
| 3267 | \membersection{::wxFindWindowAtPoint}\label{wxfindwindowatpoint} |
| 3268 | |
| 3269 | \func{wxWindow *}{wxFindWindowAtPoint}{\param{const wxPoint\& }{pt}} |
| 3270 | |
| 3271 | Find the deepest window at the given mouse position in screen coordinates, |
| 3272 | returning the window if found, or NULL if not. |
| 3273 | |
| 3274 | |
| 3275 | \membersection{::wxFindWindowAtPointer}\label{wxfindwindowatpointer} |
| 3276 | |
| 3277 | \func{wxWindow *}{wxFindWindowAtPointer}{\param{wxPoint\& }{pt}} |
| 3278 | |
| 3279 | Find the deepest window at the mouse pointer position, returning the window |
| 3280 | and current pointer position in screen coordinates. |
| 3281 | |
| 3282 | |
| 3283 | \membersection{wxFromString}\label{wxfromstring} |
| 3284 | |
| 3285 | \func{bool}{wxFromString}{\param{const wxString\& }{str}, |
| 3286 | \param{wxColour* }{col}} |
| 3287 | |
| 3288 | \func{bool}{wxFromString}{\param{const wxString\& }{str}, |
| 3289 | \param{wxFont* }{col}} |
| 3290 | |
| 3291 | Converts string to the type of the second argument. Returns \true on success. |
| 3292 | See also: \helpref{wxToString}{wxtostring}. |
| 3293 | |
| 3294 | |
| 3295 | \membersection{::wxGetActiveWindow}\label{wxgetactivewindow} |
| 3296 | |
| 3297 | \func{wxWindow *}{wxGetActiveWindow}{\void} |
| 3298 | |
| 3299 | Gets the currently active window (implemented for MSW and GTK only currently, |
| 3300 | always returns \NULL in the other ports). |
| 3301 | |
| 3302 | \wxheading{Include files} |
| 3303 | |
| 3304 | <wx/window.h> |
| 3305 | |
| 3306 | |
| 3307 | \membersection{::wxGetBatteryState}\label{wxgetbatterystate} |
| 3308 | |
| 3309 | \func{wxBatteryState}{wxGetBatteryState}{\void} |
| 3310 | |
| 3311 | Returns battery state as one of \texttt{wxBATTERY\_NORMAL\_STATE}, |
| 3312 | \texttt{wxBATTERY\_LOW\_STATE}, \texttt{wxBATTERY\_CRITICAL\_STATE}, |
| 3313 | \texttt{wxBATTERY\_SHUTDOWN\_STATE} or \texttt{wxBATTERY\_UNKNOWN\_STATE}. |
| 3314 | \texttt{wxBATTERY\_UNKNOWN\_STATE} is also the default on platforms where |
| 3315 | this feature is not implemented (currently everywhere but MS Windows). |
| 3316 | |
| 3317 | \wxheading{Include files} |
| 3318 | |
| 3319 | <wx/utils.h> |
| 3320 | |
| 3321 | |
| 3322 | \membersection{::wxGetDisplayName}\label{wxgetdisplayname} |
| 3323 | |
| 3324 | \func{wxString}{wxGetDisplayName}{\void} |
| 3325 | |
| 3326 | Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}. |
| 3327 | |
| 3328 | \wxheading{Include files} |
| 3329 | |
| 3330 | <wx/utils.h> |
| 3331 | |
| 3332 | |
| 3333 | \membersection{::wxGetPowerType}\label{wxgetpowertype} |
| 3334 | |
| 3335 | \func{wxPowerType}{wxGetPowerType}{\void} |
| 3336 | |
| 3337 | Returns the type of power source as one of \texttt{wxPOWER\_SOCKET}, |
| 3338 | \texttt{wxPOWER\_BATTERY} or \texttt{wxPOWER\_UNKNOWN}. |
| 3339 | \texttt{wxPOWER\_UNKNOWN} is also the default on platforms where this |
| 3340 | feature is not implemented (currently everywhere but MS Windows). |
| 3341 | |
| 3342 | \wxheading{Include files} |
| 3343 | |
| 3344 | <wx/utils.h> |
| 3345 | |
| 3346 | |
| 3347 | \membersection{::wxGetMousePosition}\label{wxgetmouseposition} |
| 3348 | |
| 3349 | \func{wxPoint}{wxGetMousePosition}{\void} |
| 3350 | |
| 3351 | Returns the mouse position in screen coordinates. |
| 3352 | |
| 3353 | \wxheading{Include files} |
| 3354 | |
| 3355 | <wx/utils.h> |
| 3356 | |
| 3357 | |
| 3358 | \membersection{::wxGetMouseState}\label{wxgetmousestate} |
| 3359 | |
| 3360 | \func{wxMouseState}{wxGetMouseState}{\void} |
| 3361 | |
| 3362 | Returns the current state of the mouse. Returns a wxMouseState |
| 3363 | instance that contains the current position of the mouse pointer in |
| 3364 | screen coordinants, as well as boolean values indicating the up/down |
| 3365 | status of the mouse buttons and the modifier keys. |
| 3366 | |
| 3367 | \wxheading{Include files} |
| 3368 | |
| 3369 | <wx/utils.h> |
| 3370 | |
| 3371 | wxMouseState has the following interface: |
| 3372 | |
| 3373 | \begin{verbatim} |
| 3374 | class wxMouseState |
| 3375 | { |
| 3376 | public: |
| 3377 | wxMouseState(); |
| 3378 | |
| 3379 | wxCoord GetX(); |
| 3380 | wxCoord GetY(); |
| 3381 | |
| 3382 | bool LeftDown(); |
| 3383 | bool MiddleDown(); |
| 3384 | bool RightDown(); |
| 3385 | |
| 3386 | bool ControlDown(); |
| 3387 | bool ShiftDown(); |
| 3388 | bool AltDown(); |
| 3389 | bool MetaDown(); |
| 3390 | bool CmdDown(); |
| 3391 | |
| 3392 | void SetX(wxCoord x); |
| 3393 | void SetY(wxCoord y); |
| 3394 | |
| 3395 | void SetLeftDown(bool down); |
| 3396 | void SetMiddleDown(bool down); |
| 3397 | void SetRightDown(bool down); |
| 3398 | |
| 3399 | void SetControlDown(bool down); |
| 3400 | void SetShiftDown(bool down); |
| 3401 | void SetAltDown(bool down); |
| 3402 | void SetMetaDown(bool down); |
| 3403 | }; |
| 3404 | \end{verbatim} |
| 3405 | |
| 3406 | |
| 3407 | |
| 3408 | \membersection{::wxGetStockLabel}\label{wxgetstocklabel} |
| 3409 | |
| 3410 | \func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{const wxString\& }{accelerator = wxEmptyString}} |
| 3411 | |
| 3412 | Returns label that should be used for given {\it id} element. |
| 3413 | |
| 3414 | \wxheading{Parameters} |
| 3415 | |
| 3416 | \docparam{id}{given id of the \helpref{wxMenuItem}{wxmenuitem}, \helpref{wxButton}{wxbutton}, \helpref{wxToolBar}{wxtoolbar} tool, etc.} |
| 3417 | |
| 3418 | \docparam{withCodes}{if false then strip accelerator code from the label; |
| 3419 | usefull for getting labels without accelerator char code like for toolbar tooltip or |
| 3420 | under platforms without traditional keyboard like smartphones} |
| 3421 | |
| 3422 | \docparam{accelerator}{optional accelerator string automatically added to label; useful |
| 3423 | for building labels for \helpref{wxMenuItem}{wxmenuitem}} |
| 3424 | |
| 3425 | \wxheading{Include files} |
| 3426 | |
| 3427 | <wx/stockitem.h> |
| 3428 | |
| 3429 | |
| 3430 | \membersection{::wxGetTopLevelParent}\label{wxgettoplevelparent} |
| 3431 | |
| 3432 | \func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}} |
| 3433 | |
| 3434 | Returns the first top level parent of the given window, or in other words, the |
| 3435 | frame or dialog containing it, or {\tt NULL}. |
| 3436 | |
| 3437 | \wxheading{Include files} |
| 3438 | |
| 3439 | <wx/window.h> |
| 3440 | |
| 3441 | |
| 3442 | \membersection{::wxLaunchDefaultBrowser}\label{wxlaunchdefaultbrowser} |
| 3443 | |
| 3444 | \func{bool}{wxLaunchDefaultBrowser}{\param{const wxString\& }{url}, \param{int }{flags = $0$}} |
| 3445 | |
| 3446 | Open the \arg{url} in user's default browser. If \arg{flags} parameter contains |
| 3447 | \texttt{wxBROWSER\_NEW\_WINDOW} flag, a new window is opened for the URL |
| 3448 | (currently this is only supported under Windows). The \arg{url} may also be a |
| 3449 | local file path (with or without \texttt{file://} prefix), if it doesn't |
| 3450 | correspond to an existing file and the URL has no scheme \texttt{http://} is |
| 3451 | prepended to it by default. |
| 3452 | |
| 3453 | Returns \true if the application was successfully launched. |
| 3454 | |
| 3455 | Note that for some configurations of the running user, the application which |
| 3456 | is launched to open the given URL may be URL-dependent (e.g. a browser may be used for |
| 3457 | local URLs while another one may be used for remote URLs). |
| 3458 | |
| 3459 | \wxheading{Include files} |
| 3460 | |
| 3461 | <wx/utils.h> |
| 3462 | |
| 3463 | |
| 3464 | \membersection{::wxLoadUserResource}\label{wxloaduserresource} |
| 3465 | |
| 3466 | \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} |
| 3467 | |
| 3468 | Loads a user-defined Windows resource as a string. If the resource is found, the function creates |
| 3469 | a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned. |
| 3470 | |
| 3471 | The resource must be defined in the {\tt .rc} file using the following syntax: |
| 3472 | |
| 3473 | \begin{verbatim} |
| 3474 | myResource TEXT file.ext |
| 3475 | \end{verbatim} |
| 3476 | |
| 3477 | where {\tt file.ext} is a file that the resource compiler can find. |
| 3478 | |
| 3479 | This function is available under Windows only. |
| 3480 | |
| 3481 | \wxheading{Include files} |
| 3482 | |
| 3483 | <wx/utils.h> |
| 3484 | |
| 3485 | |
| 3486 | \membersection{::wxPostDelete}\label{wxpostdelete} |
| 3487 | |
| 3488 | \func{void}{wxPostDelete}{\param{wxObject *}{object}} |
| 3489 | |
| 3490 | Tells the system to delete the specified object when |
| 3491 | all other events have been processed. In some environments, it is |
| 3492 | necessary to use this instead of deleting a frame directly with the |
| 3493 | delete operator, because some GUIs will still send events to a deleted window. |
| 3494 | |
| 3495 | Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead. |
| 3496 | |
| 3497 | \wxheading{Include files} |
| 3498 | |
| 3499 | <wx/utils.h> |
| 3500 | |
| 3501 | |
| 3502 | \membersection{::wxPostEvent}\label{wxpostevent} |
| 3503 | |
| 3504 | \func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}} |
| 3505 | |
| 3506 | In a GUI application, this function posts {\it event} to the specified {\it dest} |
| 3507 | object using \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}. |
| 3508 | Otherwise, it dispatches {\it event} immediately using |
| 3509 | \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}. |
| 3510 | See the respective documentation for details (and caveats). |
| 3511 | |
| 3512 | \wxheading{Include files} |
| 3513 | |
| 3514 | <wx/app.h> |
| 3515 | |
| 3516 | |
| 3517 | \membersection{::wxSetDisplayName}\label{wxsetdisplayname} |
| 3518 | |
| 3519 | \func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}} |
| 3520 | |
| 3521 | Under X only, sets the current display name. This is the X host and display name such |
| 3522 | as ``colonsay:0.0", and the function indicates which display should be used for creating |
| 3523 | windows from this point on. Setting the display within an application allows multiple |
| 3524 | displays to be used. |
| 3525 | |
| 3526 | See also \helpref{wxGetDisplayName}{wxgetdisplayname}. |
| 3527 | |
| 3528 | \wxheading{Include files} |
| 3529 | |
| 3530 | <wx/utils.h> |
| 3531 | |
| 3532 | |
| 3533 | \membersection{::wxStripMenuCodes}\label{wxstripmenucodes} |
| 3534 | |
| 3535 | \func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{str}, \param{int }{flags = wxStrip\_All}} |
| 3536 | |
| 3537 | Strips any menu codes from \arg{str} and returns the result. |
| 3538 | |
| 3539 | By default, the functions strips both the mnemonics character (\texttt{'\&'}) |
| 3540 | which is used to indicate a keyboard shortkey, and the accelerators, which are |
| 3541 | used only in the menu items and are separated from the main text by the |
| 3542 | \texttt{$\backslash$t} (TAB) character. By using \arg{flags} of |
| 3543 | \texttt{wxStrip\_Mnemonics} or \texttt{wxStrip\_Accel} to strip only the former |
| 3544 | or the latter part, respectively. |
| 3545 | |
| 3546 | Notice that in most cases |
| 3547 | \helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} or |
| 3548 | \helpref{wxControl::GetLabelText}{wxcontrolgetlabeltext} can be used instead. |
| 3549 | |
| 3550 | \wxheading{Include files} |
| 3551 | |
| 3552 | <wx/utils.h> |
| 3553 | |
| 3554 | |
| 3555 | \membersection{wxSTRINGIZE}\label{wxstringize} |
| 3556 | |
| 3557 | \func{}{wxSTRINGIZE}{\param{}{x}} |
| 3558 | |
| 3559 | Returns the string representation of the given symbol which can be either a |
| 3560 | literal or a macro (hence the advantage of using this macro instead of the |
| 3561 | standard preprocessor \texttt{\#} operator which doesn't work with macros). |
| 3562 | |
| 3563 | Notice that this macro always produces a \texttt{char} string, use |
| 3564 | \helpref{wxSTRINGIZE\_T}{wxstringizet} to build a wide string Unicode build. |
| 3565 | |
| 3566 | \wxheading{See also} |
| 3567 | |
| 3568 | \helpref{wxCONCAT}{wxconcat} |
| 3569 | |
| 3570 | |
| 3571 | \membersection{wxSTRINGIZE\_T}\label{wxstringizet} |
| 3572 | |
| 3573 | \func{}{wxSTRINGIZE\_T}{\param{}{x}} |
| 3574 | |
| 3575 | Returns the string representation of the given symbol as either an ASCII or |
| 3576 | Unicode string, depending on the current build. This is the Unicode-friendly |
| 3577 | equivalent of \helpref{wxSTRINGIZE}{wxstringize}. |
| 3578 | |
| 3579 | |
| 3580 | \membersection{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}\label{wxsuppressgccprivatedtorwarning} |
| 3581 | |
| 3582 | \func{}{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{\param{}{name}} |
| 3583 | |
| 3584 | GNU C++ compiler gives a warning for any class whose destructor is private |
| 3585 | unless it has a friend. This warning may sometimes be useful but it doesn't |
| 3586 | make sense for reference counted class which always delete themselves (hence |
| 3587 | destructor should be private) but don't necessarily have any friends, so this |
| 3588 | macro is provided to disable the warning in such case. The \arg{name} parameter |
| 3589 | should be the name of the class but is only used to construct a unique friend |
| 3590 | class name internally. Example of using the macro: |
| 3591 | |
| 3592 | \begin{verbatim} |
| 3593 | class RefCounted |
| 3594 | { |
| 3595 | public: |
| 3596 | RefCounted() { m_nRef = 1; } |
| 3597 | void IncRef() { m_nRef++ ; } |
| 3598 | void DecRef() { if ( !--m_nRef ) delete this; } |
| 3599 | |
| 3600 | private: |
| 3601 | ~RefCounted() { } |
| 3602 | |
| 3603 | wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted) |
| 3604 | }; |
| 3605 | \end{verbatim} |
| 3606 | |
| 3607 | Notice that there should be no semicolon after this macro. |
| 3608 | |
| 3609 | |
| 3610 | \membersection{wxToString}\label{wxtostring} |
| 3611 | |
| 3612 | \func{wxString}{wxToString}{\param{const wxColour\& }{col}} |
| 3613 | |
| 3614 | \func{wxString}{wxToString}{\param{const wxFont\& }{col}} |
| 3615 | |
| 3616 | Converts its argument to string. |
| 3617 | See also: \helpref{wxFromString}{wxfromstring}. |
| 3618 | |
| 3619 | |
| 3620 | \membersection{wxULL}\label{wxull} |
| 3621 | |
| 3622 | \func{wxLongLong\_t}{wxULL}{\param{}{number}} |
| 3623 | |
| 3624 | This macro is defined for the platforms with a native 64 bit integer type and |
| 3625 | allows to define unsigned 64 bit compile time constants: |
| 3626 | |
| 3627 | \begin{verbatim} |
| 3628 | #ifdef wxLongLong_t |
| 3629 | unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef); |
| 3630 | #endif |
| 3631 | \end{verbatim} |
| 3632 | |
| 3633 | \wxheading{Include files} |
| 3634 | |
| 3635 | <wx/longlong.h> |
| 3636 | |
| 3637 | \wxheading{See also} |
| 3638 | |
| 3639 | \helpref{wxLL}{wxll}, \helpref{wxLongLong}{wxlonglong} |
| 3640 | |
| 3641 | |
| 3642 | \membersection{wxVaCopy}\label{wxvacopy} |
| 3643 | |
| 3644 | \func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{ argptrSrc}} |
| 3645 | |
| 3646 | This macro is the same as the standard C99 \texttt{va\_copy} for the compilers |
| 3647 | which support it or its replacement for those that don't. It must be used to |
| 3648 | preserve the value of a \texttt{va\_list} object if you need to use it after |
| 3649 | passing it to another function because it can be modified by the latter. |
| 3650 | |
| 3651 | As with \texttt{va\_start}, each call to \texttt{wxVaCopy} must have a matching |
| 3652 | \texttt{va\_end}. |
| 3653 | |
| 3654 | |
| 3655 | |
| 3656 | \membersection{\_\_WXFUNCTION\_\_}\label{wxfunction} |
| 3657 | |
| 3658 | \func{}{\_\_WXFUNCTION\_\_}{\void} |
| 3659 | |
| 3660 | This macro expands to the name of the current function if the compiler supports |
| 3661 | any of \texttt{\_\_FUNCTION\_\_}, \texttt{\_\_func\_\_} or equivalent variables |
| 3662 | or macros or to \NULL if none of them is available. |
| 3663 | |
| 3664 | |
| 3665 | |
| 3666 | \section{Byte order macros}\label{byteordermacros} |
| 3667 | |
| 3668 | The endian-ness issues (that is the difference between big-endian and |
| 3669 | little-endian architectures) are important for the portable programs working |
| 3670 | with the external binary data (for example, data files or data coming from |
| 3671 | network) which is usually in some fixed, platform-independent format. The |
| 3672 | macros are helpful for transforming the data to the correct format. |
| 3673 | |
| 3674 | |
| 3675 | \membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways} |
| 3676 | |
| 3677 | \func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}} |
| 3678 | |
| 3679 | \func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}} |
| 3680 | |
| 3681 | \func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}} |
| 3682 | |
| 3683 | \func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}} |
| 3684 | |
| 3685 | These macros will swap the bytes of the {\it value} variable from little |
| 3686 | endian to big endian or vice versa unconditionally, i.e. independently of the |
| 3687 | current platform. |
| 3688 | |
| 3689 | |
| 3690 | \membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe} |
| 3691 | |
| 3692 | \func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}} |
| 3693 | |
| 3694 | \func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}} |
| 3695 | |
| 3696 | \func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}} |
| 3697 | |
| 3698 | \func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}} |
| 3699 | |
| 3700 | This macro will swap the bytes of the {\it value} variable from little |
| 3701 | endian to big endian or vice versa if the program is compiled on a |
| 3702 | big-endian architecture (such as Sun work stations). If the program has |
| 3703 | been compiled on a little-endian architecture, the value will be unchanged. |
| 3704 | |
| 3705 | Use these macros to read data from and write data to a file that stores |
| 3706 | data in little-endian (for example Intel i386) format. |
| 3707 | |
| 3708 | |
| 3709 | \membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle} |
| 3710 | |
| 3711 | \func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}} |
| 3712 | |
| 3713 | \func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}} |
| 3714 | |
| 3715 | \func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}} |
| 3716 | |
| 3717 | \func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}} |
| 3718 | |
| 3719 | This macro will swap the bytes of the {\it value} variable from little |
| 3720 | endian to big endian or vice versa if the program is compiled on a |
| 3721 | little-endian architecture (such as Intel PCs). If the program has |
| 3722 | been compiled on a big-endian architecture, the value will be unchanged. |
| 3723 | |
| 3724 | Use these macros to read data from and write data to a file that stores |
| 3725 | data in big-endian format. |
| 3726 | |
| 3727 | |
| 3728 | |
| 3729 | \section{RTTI functions}\label{rttimacros} |
| 3730 | |
| 3731 | wxWidgets uses its own RTTI ("run-time type identification") system which |
| 3732 | predates the current standard C++ RTTI and so is kept for backwards |
| 3733 | compatibility reasons but also because it allows some things which the |
| 3734 | standard RTTI doesn't directly support (such as creating a class from its |
| 3735 | name). |
| 3736 | |
| 3737 | The standard C++ RTTI can be used in the user code without any problems and in |
| 3738 | general you shouldn't need to use the functions and the macros in this section |
| 3739 | unless you are thinking of modifying or adding any wxWidgets classes. |
| 3740 | |
| 3741 | \wxheading{See also} |
| 3742 | |
| 3743 | \helpref{RTTI overview}{runtimeclassoverview} |
| 3744 | |
| 3745 | |
| 3746 | \membersection{CLASSINFO}\label{classinfo} |
| 3747 | |
| 3748 | \func{wxClassInfo *}{CLASSINFO}{className} |
| 3749 | |
| 3750 | Returns a pointer to the wxClassInfo object associated with this class. |
| 3751 | |
| 3752 | \wxheading{Include files} |
| 3753 | |
| 3754 | <wx/object.h> |
| 3755 | |
| 3756 | |
| 3757 | \membersection{DECLARE\_ABSTRACT\_CLASS}\label{declareabstractclass} |
| 3758 | |
| 3759 | \func{}{DECLARE\_ABSTRACT\_CLASS}{className} |
| 3760 | |
| 3761 | Used inside a class declaration to declare that the class should be |
| 3762 | made known to the class hierarchy, but objects of this class cannot be created |
| 3763 | dynamically. The same as DECLARE\_CLASS. |
| 3764 | |
| 3765 | Example: |
| 3766 | |
| 3767 | \begin{verbatim} |
| 3768 | class wxCommand: public wxObject |
| 3769 | { |
| 3770 | DECLARE_ABSTRACT_CLASS(wxCommand) |
| 3771 | |
| 3772 | private: |
| 3773 | ... |
| 3774 | public: |
| 3775 | ... |
| 3776 | }; |
| 3777 | \end{verbatim} |
| 3778 | |
| 3779 | \wxheading{Include files} |
| 3780 | |
| 3781 | <wx/object.h> |
| 3782 | |
| 3783 | |
| 3784 | \membersection{DECLARE\_APP}\label{declareapp} |
| 3785 | |
| 3786 | \func{}{DECLARE\_APP}{className} |
| 3787 | |
| 3788 | This is used in headers to create a forward declaration of the |
| 3789 | \helpref{wxGetApp}{wxgetapp} function implemented by |
| 3790 | \helpref{IMPLEMENT\_APP}{implementapp}. It creates the declaration |
| 3791 | {\tt className\& wxGetApp(void)}. |
| 3792 | |
| 3793 | Example: |
| 3794 | |
| 3795 | \begin{verbatim} |
| 3796 | DECLARE_APP(MyApp) |
| 3797 | \end{verbatim} |
| 3798 | |
| 3799 | \wxheading{Include files} |
| 3800 | |
| 3801 | <wx/app.h> |
| 3802 | |
| 3803 | |
| 3804 | \membersection{DECLARE\_CLASS}\label{declareclass} |
| 3805 | |
| 3806 | \func{}{DECLARE\_CLASS}{className} |
| 3807 | |
| 3808 | Used inside a class declaration to declare that the class should be |
| 3809 | made known to the class hierarchy, but objects of this class cannot be created |
| 3810 | dynamically. The same as DECLARE\_ABSTRACT\_CLASS. |
| 3811 | |
| 3812 | \wxheading{Include files} |
| 3813 | |
| 3814 | <wx/object.h> |
| 3815 | |
| 3816 | |
| 3817 | \membersection{DECLARE\_DYNAMIC\_CLASS}\label{declaredynamicclass} |
| 3818 | |
| 3819 | \func{}{DECLARE\_DYNAMIC\_CLASS}{className} |
| 3820 | |
| 3821 | Used inside a class declaration to make the class known to wxWidgets RTTI |
| 3822 | system and also declare that the objects of this class should be dynamically |
| 3823 | creatable from run-time type information. Notice that this implies that the |
| 3824 | class should have a default constructor, if this is not the case consider using |
| 3825 | \helpref{DECLARE\_CLASS}{declareclass}. |
| 3826 | |
| 3827 | Example: |
| 3828 | |
| 3829 | \begin{verbatim} |
| 3830 | class wxFrame: public wxWindow |
| 3831 | { |
| 3832 | DECLARE_DYNAMIC_CLASS(wxFrame) |
| 3833 | |
| 3834 | private: |
| 3835 | const wxString& frameTitle; |
| 3836 | public: |
| 3837 | ... |
| 3838 | }; |
| 3839 | \end{verbatim} |
| 3840 | |
| 3841 | \wxheading{Include files} |
| 3842 | |
| 3843 | <wx/object.h> |
| 3844 | |
| 3845 | |
| 3846 | \membersection{IMPLEMENT\_ABSTRACT\_CLASS}\label{implementabstractclass} |
| 3847 | |
| 3848 | \func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName} |
| 3849 | |
| 3850 | Used in a C++ implementation file to complete the declaration of |
| 3851 | a class that has run-time type information. The same as IMPLEMENT\_CLASS. |
| 3852 | |
| 3853 | Example: |
| 3854 | |
| 3855 | \begin{verbatim} |
| 3856 | IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) |
| 3857 | |
| 3858 | wxCommand::wxCommand(void) |
| 3859 | { |
| 3860 | ... |
| 3861 | } |
| 3862 | \end{verbatim} |
| 3863 | |
| 3864 | \wxheading{Include files} |
| 3865 | |
| 3866 | <wx/object.h> |
| 3867 | |
| 3868 | |
| 3869 | \membersection{IMPLEMENT\_ABSTRACT\_CLASS2}\label{implementabstractclass2} |
| 3870 | |
| 3871 | \func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2} |
| 3872 | |
| 3873 | Used in a C++ implementation file to complete the declaration of |
| 3874 | a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2. |
| 3875 | |
| 3876 | \wxheading{Include files} |
| 3877 | |
| 3878 | <wx/object.h> |
| 3879 | |
| 3880 | |
| 3881 | \membersection{IMPLEMENT\_APP}\label{implementapp} |
| 3882 | |
| 3883 | \func{}{IMPLEMENT\_APP}{className} |
| 3884 | |
| 3885 | This is used in the application class implementation file to make the application class known to |
| 3886 | wxWidgets for dynamic construction. You use this instead of |
| 3887 | |
| 3888 | Old form: |
| 3889 | |
| 3890 | \begin{verbatim} |
| 3891 | MyApp myApp; |
| 3892 | \end{verbatim} |
| 3893 | |
| 3894 | New form: |
| 3895 | |
| 3896 | \begin{verbatim} |
| 3897 | IMPLEMENT_APP(MyApp) |
| 3898 | \end{verbatim} |
| 3899 | |
| 3900 | See also \helpref{DECLARE\_APP}{declareapp}. |
| 3901 | |
| 3902 | \wxheading{Include files} |
| 3903 | |
| 3904 | <wx/app.h> |
| 3905 | |
| 3906 | |
| 3907 | \membersection{IMPLEMENT\_CLASS}\label{implementclass} |
| 3908 | |
| 3909 | \func{}{IMPLEMENT\_CLASS}{className, baseClassName} |
| 3910 | |
| 3911 | Used in a C++ implementation file to complete the declaration of |
| 3912 | a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS. |
| 3913 | |
| 3914 | \wxheading{Include files} |
| 3915 | |
| 3916 | <wx/object.h> |
| 3917 | |
| 3918 | |
| 3919 | \membersection{IMPLEMENT\_CLASS2}\label{implementclass2} |
| 3920 | |
| 3921 | \func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2} |
| 3922 | |
| 3923 | Used in a C++ implementation file to complete the declaration of a |
| 3924 | class that has run-time type information and two base classes. The |
| 3925 | same as IMPLEMENT\_ABSTRACT\_CLASS2. |
| 3926 | |
| 3927 | \wxheading{Include files} |
| 3928 | |
| 3929 | <wx/object.h> |
| 3930 | |
| 3931 | |
| 3932 | \membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass} |
| 3933 | |
| 3934 | \func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName} |
| 3935 | |
| 3936 | Used in a C++ implementation file to complete the declaration of |
| 3937 | a class that has run-time type information, and whose instances |
| 3938 | can be created dynamically. |
| 3939 | |
| 3940 | Example: |
| 3941 | |
| 3942 | \begin{verbatim} |
| 3943 | IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) |
| 3944 | |
| 3945 | wxFrame::wxFrame(void) |
| 3946 | { |
| 3947 | ... |
| 3948 | } |
| 3949 | \end{verbatim} |
| 3950 | |
| 3951 | \wxheading{Include files} |
| 3952 | |
| 3953 | <wx/object.h> |
| 3954 | |
| 3955 | |
| 3956 | \membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2} |
| 3957 | |
| 3958 | \func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2} |
| 3959 | |
| 3960 | Used in a C++ implementation file to complete the declaration of |
| 3961 | a class that has run-time type information, and whose instances |
| 3962 | can be created dynamically. Use this for classes derived from two |
| 3963 | base classes. |
| 3964 | |
| 3965 | \wxheading{Include files} |
| 3966 | |
| 3967 | <wx/object.h> |
| 3968 | |
| 3969 | |
| 3970 | \membersection{wxConstCast}\label{wxconstcast} |
| 3971 | |
| 3972 | \func{classname *}{wxConstCast}{ptr, classname} |
| 3973 | |
| 3974 | This macro expands into {\tt const\_cast<classname *>(ptr)} if the compiler |
| 3975 | supports {\it const\_cast} or into an old, C-style cast, otherwise. |
| 3976 | |
| 3977 | \wxheading{See also} |
| 3978 | |
| 3979 | \helpref{wx\_const\_cast}{wxconstcastraw}\\ |
| 3980 | \helpref{wxDynamicCast}{wxdynamiccast}\\ |
| 3981 | \helpref{wxStaticCast}{wxstaticcast} |
| 3982 | |
| 3983 | |
| 3984 | \membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject} |
| 3985 | |
| 3986 | \func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}} |
| 3987 | |
| 3988 | Creates and returns an object of the given class, if the class has been |
| 3989 | registered with the dynamic class system using DECLARE... and IMPLEMENT... macros. |
| 3990 | |
| 3991 | |
| 3992 | \membersection{WXDEBUG\_NEW}\label{debugnew} |
| 3993 | |
| 3994 | \func{}{WXDEBUG\_NEW}{arg} |
| 3995 | |
| 3996 | This is defined in debug mode to be call the redefined new operator |
| 3997 | with filename and line number arguments. The definition is: |
| 3998 | |
| 3999 | \begin{verbatim} |
| 4000 | #define WXDEBUG_NEW new(__FILE__,__LINE__) |
| 4001 | \end{verbatim} |
| 4002 | |
| 4003 | In non-debug mode, this is defined as the normal new operator. |
| 4004 | |
| 4005 | \wxheading{Include files} |
| 4006 | |
| 4007 | <wx/object.h> |
| 4008 | |
| 4009 | |
| 4010 | \membersection{wxDynamicCast}\label{wxdynamiccast} |
| 4011 | |
| 4012 | \func{classname *}{wxDynamicCast}{ptr, classname} |
| 4013 | |
| 4014 | This macro returns the pointer {\it ptr} cast to the type {\it classname *} if |
| 4015 | the pointer is of this type (the check is done during the run-time) or |
| 4016 | {\tt NULL} otherwise. Usage of this macro is preferred over obsoleted |
| 4017 | wxObject::IsKindOf() function. |
| 4018 | |
| 4019 | The {\it ptr} argument may be {\tt NULL}, in which case {\tt NULL} will be |
| 4020 | returned. |
| 4021 | |
| 4022 | Example: |
| 4023 | |
| 4024 | \begin{verbatim} |
| 4025 | wxWindow *win = wxWindow::FindFocus(); |
| 4026 | wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); |
| 4027 | if ( text ) |
| 4028 | { |
| 4029 | // a text control has the focus... |
| 4030 | } |
| 4031 | else |
| 4032 | { |
| 4033 | // no window has the focus or it is not a text control |
| 4034 | } |
| 4035 | \end{verbatim} |
| 4036 | |
| 4037 | \wxheading{See also} |
| 4038 | |
| 4039 | \helpref{RTTI overview}{runtimeclassoverview}\\ |
| 4040 | \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\ |
| 4041 | \helpref{wxConstCast}{wxconstcast}\\ |
| 4042 | \helpref{wxStaticCast}{wxstaticcast} |
| 4043 | |
| 4044 | |
| 4045 | \membersection{wxDynamicCastThis}\label{wxdynamiccastthis} |
| 4046 | |
| 4047 | \func{classname *}{wxDynamicCastThis}{classname} |
| 4048 | |
| 4049 | This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the |
| 4050 | latter provokes spurious compilation warnings from some compilers (because it |
| 4051 | tests whether {\tt this} pointer is non-{\tt NULL} which is always true), so |
| 4052 | this macro should be used to avoid them. |
| 4053 | |
| 4054 | \wxheading{See also} |
| 4055 | |
| 4056 | \helpref{wxDynamicCast}{wxdynamiccast} |
| 4057 | |
| 4058 | |
| 4059 | \membersection{wxStaticCast}\label{wxstaticcast} |
| 4060 | |
| 4061 | \func{classname *}{wxStaticCast}{ptr, classname} |
| 4062 | |
| 4063 | This macro checks that the cast is valid in debug mode (an assert failure will |
| 4064 | result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the |
| 4065 | result of executing an equivalent of {\tt static\_cast<classname *>(ptr)}. |
| 4066 | |
| 4067 | \wxheading{See also} |
| 4068 | |
| 4069 | \helpref{wx\_static\_cast}{wxstaticcastraw}\\ |
| 4070 | \helpref{wxDynamicCast}{wxdynamiccast}\\ |
| 4071 | \helpref{wxConstCast}{wxconstcast} |
| 4072 | |
| 4073 | |
| 4074 | \membersection{wx\_const\_cast}\label{wxconstcastraw} |
| 4075 | |
| 4076 | \func{T}{wx\_const\_cast}{T, x} |
| 4077 | |
| 4078 | Same as \texttt{const\_cast<T>(x)} if the compiler supports const cast or |
| 4079 | \texttt{(T)x} for old compilers. Unlike \helpref{wxConstCast}{wxconstcast}, |
| 4080 | the cast it to the type \arg{T} and not to \texttt{T *} and also the order of |
| 4081 | arguments is the same as for the standard cast. |
| 4082 | |
| 4083 | \wxheading{See also} |
| 4084 | |
| 4085 | \helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ |
| 4086 | \helpref{wx\_static\_cast}{wxstaticcastraw} |
| 4087 | |
| 4088 | |
| 4089 | \membersection{wx\_reinterpret\_cast}\label{wxreinterpretcastraw} |
| 4090 | |
| 4091 | \func{T}{wx\_reinterpret\_cast}{T, x} |
| 4092 | |
| 4093 | Same as \texttt{reinterpret\_cast<T>(x)} if the compiler supports reinterpret cast or |
| 4094 | \texttt{(T)x} for old compilers. |
| 4095 | |
| 4096 | \wxheading{See also} |
| 4097 | |
| 4098 | \helpref{wx\_const\_cast}{wxconstcastraw},\\ |
| 4099 | \helpref{wx\_static\_cast}{wxstaticcastraw} |
| 4100 | |
| 4101 | |
| 4102 | \membersection{wx\_static\_cast}\label{wxstaticcastraw} |
| 4103 | |
| 4104 | \func{T}{wx\_static\_cast}{T, x} |
| 4105 | |
| 4106 | Same as \texttt{static\_cast<T>(x)} if the compiler supports static cast or |
| 4107 | \texttt{(T)x} for old compilers. Unlike \helpref{wxStaticCast}{wxstaticcast}, |
| 4108 | there are no checks being done and the meaning of the macro arguments is exactly |
| 4109 | the same as for the standard static cast, i.e. \arg{T} is the full type name and |
| 4110 | star is not appended to it. |
| 4111 | |
| 4112 | \wxheading{See also} |
| 4113 | |
| 4114 | \helpref{wx\_const\_cast}{wxconstcastraw},\\ |
| 4115 | \helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ |
| 4116 | \helpref{wx\_truncate\_cast}{wxtruncatecast} |
| 4117 | |
| 4118 | |
| 4119 | \membersection{wx\_truncate\_cast}\label{wxtruncatecast} |
| 4120 | |
| 4121 | \func{T}{wx\_truncate\_cast}{T, x} |
| 4122 | |
| 4123 | This case doesn't correspond to any standard cast but exists solely to make |
| 4124 | casts which possibly result in a truncation of an integer value more readable. |
| 4125 | |
| 4126 | \wxheading{See also} |
| 4127 | |
| 4128 | \helpref{wx\_static\_cast}{wxstaticcastraw} |
| 4129 | |
| 4130 | |
| 4131 | \section{Log functions}\label{logfunctions} |
| 4132 | |
| 4133 | These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for |
| 4134 | further information. The functions use (implicitly) the currently active log |
| 4135 | target, so their descriptions here may not apply if the log target is not the |
| 4136 | standard one (installed by wxWidgets in the beginning of the program). |
| 4137 | |
| 4138 | \wxheading{Include files} |
| 4139 | |
| 4140 | <wx/log.h> |
| 4141 | |
| 4142 | |
| 4143 | \membersection{::wxDebugMsg}\label{wxdebugmsg} |
| 4144 | |
| 4145 | \func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}} |
| 4146 | |
| 4147 | {\bf NB:} This function is now obsolete, replaced by \helpref{Log |
| 4148 | functions}{logfunctions} and \helpref{wxLogDebug}{wxlogdebug} in particular. |
| 4149 | |
| 4150 | Display a debugging message; under Windows, this will appear on the |
| 4151 | debugger command window, and under Unix, it will be written to standard |
| 4152 | error. |
| 4153 | |
| 4154 | The syntax is identical to {\bf printf}: pass a format string and a |
| 4155 | variable list of arguments. |
| 4156 | |
| 4157 | {\bf Tip:} under Windows, if your application crashes before the |
| 4158 | message appears in the debugging window, put a wxYield call after |
| 4159 | each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s |
| 4160 | (at least for Watcom C++): preformat your messages and use OutputDebugString |
| 4161 | instead. |
| 4162 | |
| 4163 | \wxheading{Include files} |
| 4164 | |
| 4165 | <wx/utils.h> |
| 4166 | |
| 4167 | |
| 4168 | \membersection{::wxError}\label{wxerror} |
| 4169 | |
| 4170 | \func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Internal Error"}} |
| 4171 | |
| 4172 | {\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror} |
| 4173 | instead. |
| 4174 | |
| 4175 | Displays {\it msg} and continues. This writes to standard error under |
| 4176 | Unix, and pops up a message box under Windows. Used for internal |
| 4177 | wxWidgets errors. See also \helpref{wxFatalError}{wxfatalerror}. |
| 4178 | |
| 4179 | \wxheading{Include files} |
| 4180 | |
| 4181 | <wx/utils.h> |
| 4182 | |
| 4183 | |
| 4184 | \membersection{::wxFatalError}\label{wxfatalerror} |
| 4185 | |
| 4186 | \func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Fatal Error"}} |
| 4187 | |
| 4188 | {\bf NB:} This function is now obsolete, please use |
| 4189 | \helpref{wxLogFatalError}{wxlogfatalerror} instead. |
| 4190 | |
| 4191 | Displays {\it msg} and exits. This writes to standard error under Unix, |
| 4192 | and pops up a message box under Windows. Used for fatal internal |
| 4193 | wxWidgets errors. See also \helpref{wxError}{wxerror}. |
| 4194 | |
| 4195 | \wxheading{Include files} |
| 4196 | |
| 4197 | <wx/utils.h> |
| 4198 | |
| 4199 | |
| 4200 | \membersection{::wxLogError}\label{wxlogerror} |
| 4201 | |
| 4202 | \func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}} |
| 4203 | |
| 4204 | \func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4205 | |
| 4206 | The functions to use for error messages, i.e. the messages that must be shown |
| 4207 | to the user. The default processing is to pop up a message box to inform the |
| 4208 | user about it. |
| 4209 | |
| 4210 | |
| 4211 | \membersection{::wxLogFatalError}\label{wxlogfatalerror} |
| 4212 | |
| 4213 | \func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}} |
| 4214 | |
| 4215 | \func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4216 | |
| 4217 | Like \helpref{wxLogError}{wxlogerror}, but also |
| 4218 | terminates the program with the exit code 3. Using {\it abort()} standard |
| 4219 | function also terminates the program with this exit code. |
| 4220 | |
| 4221 | |
| 4222 | \membersection{::wxLogWarning}\label{wxlogwarning} |
| 4223 | |
| 4224 | \func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}} |
| 4225 | |
| 4226 | \func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4227 | |
| 4228 | For warnings - they are also normally shown to the user, but don't interrupt |
| 4229 | the program work. |
| 4230 | |
| 4231 | |
| 4232 | \membersection{::wxLogMessage}\label{wxlogmessage} |
| 4233 | |
| 4234 | \func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}} |
| 4235 | |
| 4236 | \func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4237 | |
| 4238 | For all normal, informational messages. They also appear in a message box by |
| 4239 | default (but it can be changed). |
| 4240 | |
| 4241 | \membersection{::wxLogVerbose}\label{wxlogverbose} |
| 4242 | |
| 4243 | \func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}} |
| 4244 | |
| 4245 | \func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4246 | |
| 4247 | For verbose output. Normally, it is suppressed, but |
| 4248 | might be activated if the user wishes to know more details about the program |
| 4249 | progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}). |
| 4250 | |
| 4251 | |
| 4252 | \membersection{::wxLogStatus}\label{wxlogstatus} |
| 4253 | |
| 4254 | \func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}} |
| 4255 | |
| 4256 | \func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4257 | |
| 4258 | \func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}} |
| 4259 | |
| 4260 | \func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4261 | |
| 4262 | Messages logged by these functions will appear in the statusbar of the {\it |
| 4263 | frame} or of the top level application window by default (i.e. when using |
| 4264 | the second version of the functions). |
| 4265 | |
| 4266 | If the target frame doesn't have a statusbar, the message will be lost. |
| 4267 | |
| 4268 | |
| 4269 | \membersection{::wxLogSysError}\label{wxlogsyserror} |
| 4270 | |
| 4271 | \func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}} |
| 4272 | |
| 4273 | \func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4274 | |
| 4275 | Mostly used by wxWidgets itself, but might be handy for logging errors after |
| 4276 | system call (API function) failure. It logs the specified message text as well |
| 4277 | as the last system error code ({\it errno} or {\it ::GetLastError()} depending |
| 4278 | on the platform) and the corresponding error message. The second form |
| 4279 | of this function takes the error code explicitly as the first argument. |
| 4280 | |
| 4281 | \wxheading{See also} |
| 4282 | |
| 4283 | \helpref{wxSysErrorCode}{wxsyserrorcode}, |
| 4284 | \helpref{wxSysErrorMsg}{wxsyserrormsg} |
| 4285 | |
| 4286 | |
| 4287 | \membersection{::wxLogDebug}\label{wxlogdebug} |
| 4288 | |
| 4289 | \func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}} |
| 4290 | |
| 4291 | \func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4292 | |
| 4293 | The right functions for debug output. They only do something in debug |
| 4294 | mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) and expand to |
| 4295 | nothing in release mode (otherwise). |
| 4296 | |
| 4297 | |
| 4298 | \membersection{::wxLogTrace}\label{wxlogtrace} |
| 4299 | |
| 4300 | \func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}} |
| 4301 | |
| 4302 | \func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4303 | |
| 4304 | \func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}} |
| 4305 | |
| 4306 | \func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4307 | |
| 4308 | \func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}} |
| 4309 | |
| 4310 | \func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} |
| 4311 | |
| 4312 | As {\bf wxLogDebug}, trace functions only do something in debug build and |
| 4313 | expand to nothing in the release one. The reason for making |
| 4314 | it a separate function from it is that usually there are a lot of trace |
| 4315 | messages, so it might make sense to separate them from other debug messages. |
| 4316 | |
| 4317 | The trace messages also usually can be separated into different categories and |
| 4318 | the second and third versions of this function only log the message if the |
| 4319 | {\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This |
| 4320 | allows to selectively trace only some operations and not others by changing |
| 4321 | the value of the trace mask (possible during the run-time). |
| 4322 | |
| 4323 | For the second function (taking a string mask), the message is logged only if |
| 4324 | the mask has been previously enabled by the call to |
| 4325 | \helpref{AddTraceMask}{wxlogaddtracemask} or by setting |
| 4326 | \helpref{{\tt WXTRACE} environment variable}{envvars}. |
| 4327 | The predefined string trace masks |
| 4328 | used by wxWidgets are: |
| 4329 | |
| 4330 | \begin{itemize}\itemsep=0pt |
| 4331 | \item wxTRACE\_MemAlloc: trace memory allocation (new/delete) |
| 4332 | \item wxTRACE\_Messages: trace window messages/X callbacks |
| 4333 | \item wxTRACE\_ResAlloc: trace GDI resource allocation |
| 4334 | \item wxTRACE\_RefCount: trace various ref counting operations |
| 4335 | \item wxTRACE\_OleCalls: trace OLE method calls (Win32 only) |
| 4336 | \end{itemize} |
| 4337 | |
| 4338 | {\bf Caveats:} since both the mask and the format string are strings, |
| 4339 | this might lead to function signature confusion in some cases: |
| 4340 | if you intend to call the format string only version of wxLogTrace, |
| 4341 | 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. |
| 4342 | In this case you'll unfortunately have to avoid having two leading |
| 4343 | string parameters, e.g. by adding a bogus integer (with its \%d format string). |
| 4344 | |
| 4345 | The third version of the function only logs the message if all the bits |
| 4346 | corresponding to the {\it mask} are set in the wxLog trace mask which can be |
| 4347 | set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less |
| 4348 | flexible than the previous one because it doesn't allow defining the user |
| 4349 | trace masks easily - this is why it is deprecated in favour of using string |
| 4350 | trace masks. |
| 4351 | |
| 4352 | \begin{itemize}\itemsep=0pt |
| 4353 | \item wxTraceMemAlloc: trace memory allocation (new/delete) |
| 4354 | \item wxTraceMessages: trace window messages/X callbacks |
| 4355 | \item wxTraceResAlloc: trace GDI resource allocation |
| 4356 | \item wxTraceRefCount: trace various ref counting operations |
| 4357 | \item wxTraceOleCalls: trace OLE method calls (Win32 only) |
| 4358 | \end{itemize} |
| 4359 | |
| 4360 | |
| 4361 | \membersection{::wxSafeShowMessage}\label{wxsafeshowmessage} |
| 4362 | |
| 4363 | \func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}} |
| 4364 | |
| 4365 | This function shows a message to the user in a safe way and should be safe to |
| 4366 | call even before the application has been initialized or if it is currently in |
| 4367 | some other strange state (for example, about to crash). Under Windows this |
| 4368 | function shows a message box using a native dialog instead of |
| 4369 | \helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere |
| 4370 | it simply prints the message to the standard output using the title as prefix. |
| 4371 | |
| 4372 | \wxheading{Parameters} |
| 4373 | |
| 4374 | \docparam{title}{The title of the message box shown to the user or the prefix |
| 4375 | of the message string} |
| 4376 | |
| 4377 | \docparam{text}{The text to show to the user} |
| 4378 | |
| 4379 | \wxheading{See also} |
| 4380 | |
| 4381 | \helpref{wxLogFatalError}{wxlogfatalerror} |
| 4382 | |
| 4383 | \wxheading{Include files} |
| 4384 | |
| 4385 | <wx/log.h> |
| 4386 | |
| 4387 | |
| 4388 | \membersection{::wxSysErrorCode}\label{wxsyserrorcode} |
| 4389 | |
| 4390 | \func{unsigned long}{wxSysErrorCode}{\void} |
| 4391 | |
| 4392 | Returns the error code from the last system call. This function uses |
| 4393 | {\tt errno} on Unix platforms and {\tt GetLastError} under Win32. |
| 4394 | |
| 4395 | \wxheading{See also} |
| 4396 | |
| 4397 | \helpref{wxSysErrorMsg}{wxsyserrormsg}, |
| 4398 | \helpref{wxLogSysError}{wxlogsyserror} |
| 4399 | |
| 4400 | |
| 4401 | \membersection{::wxSysErrorMsg}\label{wxsyserrormsg} |
| 4402 | |
| 4403 | \func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}} |
| 4404 | |
| 4405 | Returns the error message corresponding to the given system error code. If |
| 4406 | {\it errCode} is $0$ (default), the last error code (as returned by |
| 4407 | \helpref{wxSysErrorCode}{wxsyserrorcode}) is used. |
| 4408 | |
| 4409 | \wxheading{See also} |
| 4410 | |
| 4411 | \helpref{wxSysErrorCode}{wxsyserrorcode}, |
| 4412 | \helpref{wxLogSysError}{wxlogsyserror} |
| 4413 | |
| 4414 | |
| 4415 | \membersection{WXTRACE}\label{trace} |
| 4416 | |
| 4417 | \wxheading{Include files} |
| 4418 | |
| 4419 | <wx/object.h> |
| 4420 | |
| 4421 | \func{}{WXTRACE}{formatString, ...} |
| 4422 | |
| 4423 | {\bf NB:} This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
| 4424 | |
| 4425 | Calls wxTrace with printf-style variable argument syntax. Output |
| 4426 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). |
| 4427 | |
| 4428 | \wxheading{Include files} |
| 4429 | |
| 4430 | <wx/memory.h> |
| 4431 | |
| 4432 | |
| 4433 | \membersection{WXTRACELEVEL}\label{tracelevel} |
| 4434 | |
| 4435 | \func{}{WXTRACELEVEL}{level, formatString, ...} |
| 4436 | |
| 4437 | {\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
| 4438 | |
| 4439 | Calls wxTraceLevel with printf-style variable argument syntax. Output |
| 4440 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). |
| 4441 | The first argument should be the level at which this information is appropriate. |
| 4442 | It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than |
| 4443 | this value. |
| 4444 | |
| 4445 | \wxheading{Include files} |
| 4446 | |
| 4447 | <wx/memory.h> |
| 4448 | |
| 4449 | |
| 4450 | \membersection{::wxTrace}\label{wxtrace} |
| 4451 | |
| 4452 | \func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} |
| 4453 | |
| 4454 | {\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
| 4455 | |
| 4456 | Takes printf-style variable argument syntax. Output |
| 4457 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). |
| 4458 | |
| 4459 | \wxheading{Include files} |
| 4460 | |
| 4461 | <wx/memory.h> |
| 4462 | |
| 4463 | |
| 4464 | \membersection{::wxTraceLevel}\label{wxtracelevel} |
| 4465 | |
| 4466 | \func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} |
| 4467 | |
| 4468 | {\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
| 4469 | |
| 4470 | Takes printf-style variable argument syntax. Output |
| 4471 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). |
| 4472 | The first argument should be the level at which this information is appropriate. |
| 4473 | It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than |
| 4474 | this value. |
| 4475 | |
| 4476 | \wxheading{Include files} |
| 4477 | |
| 4478 | <wx/memory.h> |
| 4479 | |
| 4480 | |
| 4481 | |
| 4482 | \section{Time functions}\label{timefunctions} |
| 4483 | |
| 4484 | The functions in this section deal with getting the current time and sleeping |
| 4485 | for the specified time interval. |
| 4486 | |
| 4487 | |
| 4488 | \membersection{::wxGetLocalTime}\label{wxgetlocaltime} |
| 4489 | |
| 4490 | \func{long}{wxGetLocalTime}{\void} |
| 4491 | |
| 4492 | Returns the number of seconds since local time 00:00:00 Jan 1st 1970. |
| 4493 | |
| 4494 | \wxheading{See also} |
| 4495 | |
| 4496 | \helpref{wxDateTime::Now}{wxdatetimenow} |
| 4497 | |
| 4498 | \wxheading{Include files} |
| 4499 | |
| 4500 | <wx/stopwatch.h> |
| 4501 | |
| 4502 | |
| 4503 | \membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis} |
| 4504 | |
| 4505 | \func{wxLongLong}{wxGetLocalTimeMillis}{\void} |
| 4506 | |
| 4507 | Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. |
| 4508 | |
| 4509 | \wxheading{See also} |
| 4510 | |
| 4511 | \helpref{wxDateTime::Now}{wxdatetimenow},\\ |
| 4512 | \helpref{wxLongLong}{wxlonglong} |
| 4513 | |
| 4514 | \wxheading{Include files} |
| 4515 | |
| 4516 | <wx/stopwatch.h> |
| 4517 | |
| 4518 | |
| 4519 | \membersection{::wxGetUTCTime}\label{wxgetutctime} |
| 4520 | |
| 4521 | \func{long}{wxGetUTCTime}{\void} |
| 4522 | |
| 4523 | Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. |
| 4524 | |
| 4525 | \wxheading{See also} |
| 4526 | |
| 4527 | \helpref{wxDateTime::Now}{wxdatetimenow} |
| 4528 | |
| 4529 | \wxheading{Include files} |
| 4530 | |
| 4531 | <wx/stopwatch.h> |
| 4532 | |
| 4533 | |
| 4534 | \membersection{::wxMicroSleep}\label{wxmicrosleep} |
| 4535 | |
| 4536 | \func{void}{wxMicroSleep}{\param{unsigned long}{ microseconds}} |
| 4537 | |
| 4538 | Sleeps for the specified number of microseconds. The microsecond resolution may |
| 4539 | not, in fact, be available on all platforms (currently only Unix platforms with |
| 4540 | nanosleep(2) may provide it) in which case this is the same as |
| 4541 | \helpref{wxMilliSleep}{wxmillisleep}(\arg{microseconds}$/1000$). |
| 4542 | |
| 4543 | \wxheading{Include files} |
| 4544 | |
| 4545 | <wx/utils.h> |
| 4546 | |
| 4547 | |
| 4548 | \membersection{::wxMilliSleep}\label{wxmillisleep} |
| 4549 | |
| 4550 | \func{void}{wxMilliSleep}{\param{unsigned long}{ milliseconds}} |
| 4551 | |
| 4552 | Sleeps for the specified number of milliseconds. Notice that usage of this |
| 4553 | function is encouraged instead of calling usleep(3) directly because the |
| 4554 | standard usleep() function is not MT safe. |
| 4555 | |
| 4556 | \wxheading{Include files} |
| 4557 | |
| 4558 | <wx/utils.h> |
| 4559 | |
| 4560 | |
| 4561 | \membersection{::wxNow}\label{wxnow} |
| 4562 | |
| 4563 | \func{wxString}{wxNow}{\void} |
| 4564 | |
| 4565 | Returns a string representing the current date and time. |
| 4566 | |
| 4567 | \wxheading{Include files} |
| 4568 | |
| 4569 | <wx/utils.h> |
| 4570 | |
| 4571 | |
| 4572 | \membersection{::wxSleep}\label{wxsleep} |
| 4573 | |
| 4574 | \func{void}{wxSleep}{\param{int}{ secs}} |
| 4575 | |
| 4576 | Sleeps for the specified number of seconds. |
| 4577 | |
| 4578 | \wxheading{Include files} |
| 4579 | |
| 4580 | <wx/utils.h> |
| 4581 | |
| 4582 | |
| 4583 | \membersection{::wxUsleep}\label{wxusleep} |
| 4584 | |
| 4585 | \func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}} |
| 4586 | |
| 4587 | This function is deprecated because its name is misleading: notice that the |
| 4588 | argument is in milliseconds, not microseconds. Please use either |
| 4589 | \helpref{wxMilliSleep}{wxmillisleep} or \helpref{wxMicroSleep}{wxmicrosleep} |
| 4590 | depending on the resolution you need. |
| 4591 | |
| 4592 | |
| 4593 | |
| 4594 | \section{Debugging macros and functions}\label{debugmacros} |
| 4595 | |
| 4596 | Useful macros and functions for error checking and defensive programming. |
| 4597 | wxWidgets defines three families of the assert-like macros: |
| 4598 | the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined |
| 4599 | (in other words, in the debug build) but disappear completely in the release |
| 4600 | build. On the other hand, the wxCHECK macros stay event in release builds but a |
| 4601 | check failure doesn't generate any user-visible effects then. Finally, the |
| 4602 | compile time assertions don't happen during the run-time but result in the |
| 4603 | compilation error messages if the condition they check fail. |
| 4604 | |
| 4605 | \wxheading{Include files} |
| 4606 | |
| 4607 | <wx/debug.h> |
| 4608 | |
| 4609 | |
| 4610 | \membersection{::wxOnAssert}\label{wxonassert} |
| 4611 | |
| 4612 | \func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{func}, \param{const char *}{cond}, \param{const char *}{msg = NULL}} |
| 4613 | |
| 4614 | This function is called whenever one of debugging macros fails (i.e. condition |
| 4615 | is false in an assertion). It is only defined in the debug mode, in release |
| 4616 | builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything. |
| 4617 | |
| 4618 | To override the default behaviour in the debug builds which is to show the user |
| 4619 | a dialog asking whether he wants to abort the program, continue or continue |
| 4620 | ignoring any subsequent assert failures, you may override |
| 4621 | \helpref{wxApp::OnAssertFailure}{wxapponassertfailure} which is called by this function if |
| 4622 | the global application object exists. |
| 4623 | |
| 4624 | |
| 4625 | \membersection{wxASSERT}\label{wxassert} |
| 4626 | |
| 4627 | \func{}{wxASSERT}{\param{}{condition}} |
| 4628 | |
| 4629 | Assert macro. An error message will be generated if the condition is false in |
| 4630 | debug mode, but nothing will be done in the release build. |
| 4631 | |
| 4632 | Please note that the condition in wxASSERT() should have no side effects |
| 4633 | because it will not be executed in release mode at all. |
| 4634 | |
| 4635 | \wxheading{See also} |
| 4636 | |
| 4637 | \helpref{wxASSERT\_MSG}{wxassertmsg},\\ |
| 4638 | \helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} |
| 4639 | |
| 4640 | |
| 4641 | \membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize} |
| 4642 | |
| 4643 | \func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}} |
| 4644 | |
| 4645 | This macro results in a |
| 4646 | \helpref{compile time assertion failure}{wxcompiletimeassert} if the size |
| 4647 | of the given type {\it type} is less than {\it size} bits. |
| 4648 | |
| 4649 | You may use it like this, for example: |
| 4650 | |
| 4651 | \begin{verbatim} |
| 4652 | // we rely on the int being able to hold values up to 2^32 |
| 4653 | wxASSERT_MIN_BITSIZE(int, 32); |
| 4654 | |
| 4655 | // can't work with the platforms using UTF-8 for wchar_t |
| 4656 | wxASSERT_MIN_BITSIZE(wchar_t, 16); |
| 4657 | \end{verbatim} |
| 4658 | |
| 4659 | |
| 4660 | \membersection{wxASSERT\_MSG}\label{wxassertmsg} |
| 4661 | |
| 4662 | \func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} |
| 4663 | |
| 4664 | Assert macro with message. An error message will be generated if the condition is false. |
| 4665 | |
| 4666 | \wxheading{See also} |
| 4667 | |
| 4668 | \helpref{wxASSERT}{wxassert},\\ |
| 4669 | \helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} |
| 4670 | |
| 4671 | |
| 4672 | \membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert} |
| 4673 | |
| 4674 | \func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}} |
| 4675 | |
| 4676 | Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the |
| 4677 | specified {\it condition} is false. The compiler error message should include |
| 4678 | the {\it msg} identifier - please note that it must be a valid C++ identifier |
| 4679 | and not a string unlike in the other cases. |
| 4680 | |
| 4681 | This macro is mostly useful for testing the expressions involving the |
| 4682 | {\tt sizeof} operator as they can't be tested by the preprocessor but it is |
| 4683 | sometimes desirable to test them at the compile time. |
| 4684 | |
| 4685 | Note that this macro internally declares a struct whose name it tries to make |
| 4686 | unique by using the {\tt \_\_LINE\_\_} in it but it may still not work if you |
| 4687 | use it on the same line in two different source files. In this case you may |
| 4688 | either change the line in which either of them appears on or use the |
| 4689 | \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} macro. |
| 4690 | |
| 4691 | Also note that Microsoft Visual C++ has a bug which results in compiler errors |
| 4692 | if you use this macro with `Program Database For Edit And Continue' |
| 4693 | (\texttt{/ZI}) option, so you shouldn't use it (`Program Database' |
| 4694 | (\texttt{/Zi}) is ok though) for the code making use of this macro. |
| 4695 | |
| 4696 | \wxheading{See also} |
| 4697 | |
| 4698 | \helpref{wxASSERT\_MSG}{wxassertmsg},\\ |
| 4699 | \helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize} |
| 4700 | |
| 4701 | |
| 4702 | \membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2} |
| 4703 | |
| 4704 | \func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}} |
| 4705 | |
| 4706 | This macro is identical to \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} |
| 4707 | except that it allows you to specify a unique {\it name} for the struct |
| 4708 | internally defined by this macro to avoid getting the compilation errors |
| 4709 | described \helpref{above}{wxcompiletimeassert}. |
| 4710 | |
| 4711 | |
| 4712 | \membersection{wxFAIL}\label{wxfail} |
| 4713 | |
| 4714 | \func{}{wxFAIL}{\void} |
| 4715 | |
| 4716 | Will always generate an assert error if this code is reached (in debug mode). |
| 4717 | |
| 4718 | See also: \helpref{wxFAIL\_MSG}{wxfailmsg} |
| 4719 | |
| 4720 | |
| 4721 | \membersection{wxFAIL\_MSG}\label{wxfailmsg} |
| 4722 | |
| 4723 | \func{}{wxFAIL\_MSG}{\param{}{msg}} |
| 4724 | |
| 4725 | Will always generate an assert error with specified message if this code is reached (in debug mode). |
| 4726 | |
| 4727 | This macro is useful for marking unreachable" code areas, for example |
| 4728 | it may be used in the "default:" branch of a switch statement if all possible |
| 4729 | cases are processed above. |
| 4730 | |
| 4731 | \wxheading{See also} |
| 4732 | |
| 4733 | \helpref{wxFAIL}{wxfail} |
| 4734 | |
| 4735 | |
| 4736 | \membersection{wxCHECK}\label{wxcheck} |
| 4737 | |
| 4738 | \func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} |
| 4739 | |
| 4740 | Checks that the condition is true, returns with the given return value if not (FAILs in debug mode). |
| 4741 | This check is done even in release mode. |
| 4742 | |
| 4743 | |
| 4744 | \membersection{wxCHECK\_MSG}\label{wxcheckmsg} |
| 4745 | |
| 4746 | \func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}} |
| 4747 | |
| 4748 | Checks that the condition is true, returns with the given return value if not (FAILs in debug mode). |
| 4749 | This check is done even in release mode. |
| 4750 | |
| 4751 | This macro may be only used in non-void functions, see also |
| 4752 | \helpref{wxCHECK\_RET}{wxcheckret}. |
| 4753 | |
| 4754 | |
| 4755 | \membersection{wxCHECK\_RET}\label{wxcheckret} |
| 4756 | |
| 4757 | \func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}} |
| 4758 | |
| 4759 | Checks that the condition is true, and returns if not (FAILs with given error |
| 4760 | message in debug mode). This check is done even in release mode. |
| 4761 | |
| 4762 | This macro should be used in void functions instead of |
| 4763 | \helpref{wxCHECK\_MSG}{wxcheckmsg}. |
| 4764 | |
| 4765 | |
| 4766 | \membersection{wxCHECK2}\label{wxcheck2} |
| 4767 | |
| 4768 | \func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}} |
| 4769 | |
| 4770 | Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute |
| 4771 | {\it operation} if it is not. This is a generalisation of |
| 4772 | \helpref{wxCHECK}{wxcheck} and may be used when something else than just |
| 4773 | returning from the function must be done when the {\it condition} is false. |
| 4774 | |
| 4775 | This check is done even in release mode. |
| 4776 | |
| 4777 | |
| 4778 | \membersection{wxCHECK2\_MSG}\label{wxcheck2msg} |
| 4779 | |
| 4780 | \func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}} |
| 4781 | |
| 4782 | This is the same as \helpref{wxCHECK2}{wxcheck2}, but |
| 4783 | \helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called |
| 4784 | instead of wxFAIL() if the {\it condition} is false. |
| 4785 | |
| 4786 | |
| 4787 | \membersection{::wxTrap}\label{wxtrap} |
| 4788 | |
| 4789 | \func{void}{wxTrap}{\void} |
| 4790 | |
| 4791 | In debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) this function generates a |
| 4792 | debugger exception meaning that the control is passed to the debugger if one is |
| 4793 | attached to the process. Otherwise the program just terminates abnormally. |
| 4794 | |
| 4795 | In release mode this function does nothing. |
| 4796 | |
| 4797 | \wxheading{Include files} |
| 4798 | |
| 4799 | <wx/debug.h> |
| 4800 | |
| 4801 | |
| 4802 | |
| 4803 | \membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning} |
| 4804 | |
| 4805 | \func{bool}{wxIsDebuggerRunning}{\void} |
| 4806 | |
| 4807 | Returns \true if the program is running under debugger, \false otherwise. |
| 4808 | |
| 4809 | Please note that this function is currently only implemented for Win32 and Mac |
| 4810 | builds using CodeWarrior and always returns \false elsewhere. |
| 4811 | |
| 4812 | |
| 4813 | |
| 4814 | |
| 4815 | \section{Environment access functions}\label{environfunctions} |
| 4816 | |
| 4817 | The functions in this section allow to access (get) or change value of |
| 4818 | environment variables in a portable way. They are currently implemented under |
| 4819 | Win32 and POSIX-like systems (Unix). |
| 4820 | |
| 4821 | % TODO add some stuff about env var inheriting but not propagating upwards (VZ) |
| 4822 | |
| 4823 | \wxheading{Include files} |
| 4824 | |
| 4825 | <wx/utils.h> |
| 4826 | |
| 4827 | |
| 4828 | \membersection{wxGetenv}\label{wxgetenvmacro} |
| 4829 | |
| 4830 | \func{wxChar *}{wxGetEnv}{\param{const wxString\&}{ var}} |
| 4831 | |
| 4832 | This is a macro defined as {\tt getenv()} or its wide char version in Unicode |
| 4833 | mode. |
| 4834 | |
| 4835 | Note that under Win32 it may not return correct value for the variables set |
| 4836 | with \helpref{wxSetEnv}{wxsetenv}, use \helpref{wxGetEnv}{wxgetenv} function |
| 4837 | instead. |
| 4838 | |
| 4839 | |
| 4840 | \membersection{wxGetEnv}\label{wxgetenv} |
| 4841 | |
| 4842 | \func{bool}{wxGetEnv}{\param{const wxString\&}{ var}, \param{wxString *}{value}} |
| 4843 | |
| 4844 | Returns the current value of the environment variable {\it var} in {\it value}. |
| 4845 | {\it value} may be {\tt NULL} if you just want to know if the variable exists |
| 4846 | and are not interested in its value. |
| 4847 | |
| 4848 | Returns \true if the variable exists, \false otherwise. |
| 4849 | |
| 4850 | |
| 4851 | \membersection{wxSetEnv}\label{wxsetenv} |
| 4852 | |
| 4853 | \func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxString\& }{value}} |
| 4854 | |
| 4855 | Sets the value of the environment variable {\it var} (adding it if necessary) |
| 4856 | to {\it value}. |
| 4857 | |
| 4858 | Returns \true on success. |
| 4859 | |
| 4860 | \wxheading{See also} |
| 4861 | |
| 4862 | \helpref{wxUnsetEnv}{wxunsetenv} |
| 4863 | |
| 4864 | |
| 4865 | \membersection{wxUnsetEnv}\label{wxunsetenv} |
| 4866 | |
| 4867 | \func{bool}{wxUnsetEnv}{\param{const wxString\&}{ var}} |
| 4868 | |
| 4869 | Removes the variable {\it var} from the environment. |
| 4870 | \helpref{wxGetEnv}{wxgetenv} will return {\tt NULL} after the call to this |
| 4871 | function. |
| 4872 | |
| 4873 | Returns \true on success. |
| 4874 | |
| 4875 | \wxheading{See also} |
| 4876 | |
| 4877 | \helpref{wxSetEnv}{wxsetenv} |
| 4878 | |
| 4879 | |
| 4880 | \section{Atomic operations}\label{atomicoperations} |
| 4881 | |
| 4882 | When using multi-threaded applications, it is often required to access or |
| 4883 | modify memory which is shared between threads. Atomic integer and pointer |
| 4884 | operations are an efficient way to handle this issue (another, less efficient, |
| 4885 | way is to use a \helpref{mutex}{wxmutex} or \helpref{critical |
| 4886 | section}{wxcriticalsection}). A native implementation exists for Windows, |
| 4887 | Linux, Solaris and Mac OS X, for other OS, a |
| 4888 | \helpref{wxCriticalSection}{wxcriticalsection} is used to protect the data. |
| 4889 | |
| 4890 | One particular application is reference counting (used by so-called smart |
| 4891 | pointers). |
| 4892 | |
| 4893 | You should define your variable with the type wxAtomicInt in order to apply |
| 4894 | atomic operations to it. |
| 4895 | |
| 4896 | \wxheading{Include files} |
| 4897 | |
| 4898 | <wx/atomic.h> |
| 4899 | |
| 4900 | \membersection{::wxAtomicInc}\label{wxatomicinc} |
| 4901 | |
| 4902 | \func{void}{wxAtomicInc}{\param{wxAtomicInt\& }{value}} |
| 4903 | |
| 4904 | This function increments \arg{value} in an atomic manner. |
| 4905 | |
| 4906 | |
| 4907 | \membersection{::wxAtomicDec}\label{wxatomicdec} |
| 4908 | |
| 4909 | \func{wxInt32}{wxAtomicDec}{\param{wxAtomicInt\& }{value}} |
| 4910 | |
| 4911 | This function decrements \arg{value} in an atomic manner. |
| 4912 | |
| 4913 | Returns 0 if \arg{value} is 0 after decrementation or any non-zero value (not |
| 4914 | necessarily equal to the value of the variable) otherwise. |
| 4915 | |
| 4916 | |