X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/330be5349367f48b25c9f19dbeadd0f30593c830..316189733a8b7f28aa7f9f555884bb45da30da33:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index dcca717867..29398496a8 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -60,7 +60,6 @@ the corresponding topic. \helpref{wxDDEInitialize}{wxddeinitialize}\\ \helpref{wxDROP\_ICON}{wxdropicon}\\ \helpref{wxDebugMsg}{wxdebugmsg}\\ -\helpref{wxDirExists}{functionwxdirexists}\\ \helpref{wxDirSelector}{wxdirselector}\\ \helpref{wxDisplayDepth}{wxdisplaydepth}\\ \helpref{wxDisplaySize}{wxdisplaysize}\\ @@ -165,6 +164,7 @@ the corresponding topic. \helpref{wxIsNaN}{wxisnan}\\ \helpref{wxIsWild}{wxiswild}\\ \helpref{wxKill}{wxkill}\\ +\helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser}\\ \helpref{wxLEAVE\_CRIT\_SECT}{wxleavecritsect}\\ \helpref{wxLoadUserResource}{wxloaduserresource}\\ \helpref{wxLogDebug}{wxlogdebug}\\ @@ -189,8 +189,11 @@ the corresponding topic. \helpref{wxNewId}{wxnewid}\\ \helpref{wxNow}{wxnow}\\ \helpref{wxOnAssert}{wxonassert}\\ +\helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}\\ +\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}\\ \helpref{wxOpenClipboard}{wxopenclipboard}\\ \helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\ +\helpref{wxDirExists}{functionwxdirexists}\\ \helpref{wxPathOnly}{wxpathonly}\\ \helpref{wxPostDelete}{wxpostdelete}\\ \helpref{wxPostEvent}{wxpostevent}\\ @@ -226,6 +229,7 @@ the corresponding topic. \helpref{wxStricmp}{wxstricmp}\\ \helpref{wxStringEq}{wxstringeq}\\ \helpref{wxStringMatch}{wxstringmatch}\\ +\helpref{wxStringTokenize}{wxstringtokenize}\\ \helpref{wxStripMenuCodes}{wxstripmenucodes}\\ \helpref{wxStrlen}{wxstrlen}\\ \helpref{wxSysErrorCode}{wxsyserrorcode}\\ @@ -249,7 +253,9 @@ the corresponding topic. \helpref{wx\_const\_cast}{wxconstcastraw}\\ \helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\ \helpref{wx\_static\_cast}{wxstaticcastraw}\\ +\helpref{wx\_truncate\_cast}{wxtruncatecast}\\ \helpref{\_}{underscore}\\ +\helpref{wxPLURAL}{wxplural}\\ \helpref{\_T}{underscoret} @@ -435,7 +441,7 @@ This function is used in wxBase only and only if you don't create \helpref{wxApp}{wxapp} object at all. In this case you must call it from your {\tt main()} function before calling any other wxWidgets functions. -If the function returns {\tt false} the initialization could not be performed, +If the function returns \false the initialization could not be performed, in this case the library cannot be used and \helpref{wxUninitialize}{wxuninitialize} shouldn't be called neither. @@ -740,7 +746,7 @@ and that this function is only implemented under Unix and Win32. \wxheading{Returns} -{\tt true} on success, {\tt false} if an error occured. +\true on success, \false if an error occurred. \wxheading{Include files} @@ -841,7 +847,7 @@ This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if \func{bool}{wxIsMainThread}{\void} -Returns {\tt true} if this thread is the main one. Always returns {\tt true} if +Returns \true if this thread is the main one. Always returns \true if {\tt wxUSE\_THREADS} is $0$. @@ -914,13 +920,6 @@ threads. \helpref{wxFileName}{wxfilename} -\membersection{::wxDirExists}\label{functionwxdirexists} - -\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} - -Returns true if the directory exists. - - \membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename} \func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}} @@ -942,6 +941,8 @@ Returns true if the file exists and is a plain file. Returns time of last modification of given file. +The return value is $0$ if an error occured (e.g. file not found). + \membersection{::wxFileNameFromPath}\label{wxfilenamefrompath} @@ -967,7 +968,7 @@ parent directory "..". \wxheading{Warning} -As of wx 2.5.2, these functions are not thread-safe! (use static variables) +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. {\it spec} may contain wildcards. @@ -1005,7 +1006,7 @@ information is not needed. \wxheading{Returns} -{\tt true} on success, {\tt false} if an error occured (for example, the +\true on success, \false if an error occurred (for example, the directory doesn't exist). \wxheading{Portability} @@ -1055,6 +1056,13 @@ Returns true if the argument is an absolute filename, i.e. with a slash or drive name at the beginning. +\membersection{::wxDirExists}\label{functionwxdirexists} + +\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} + +Returns true if the path exists. + + \membersection{::wxPathOnly}\label{wxpathonly} \func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} @@ -1064,7 +1072,9 @@ Returns the directory part of the filename. \membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename} -\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}} +\func{void}{wxUnix2DosFilename}{\param{wxChar *}{s}} + +This function is deprecated, use \helpref{wxFileName}{wxfilename} instead. Converts a Unix to a DOS filename by replacing forward slashes with backslashes. @@ -1322,7 +1332,8 @@ Return the (current) user's home directory. \wxheading{See also} -\helpref{wxGetUserHome}{wxgetuserhome} +\helpref{wxGetUserHome}{wxgetuserhome}\\ +\helpref{wxStandardPaths}{wxstandardpaths} \wxheading{Include files} @@ -1388,10 +1399,13 @@ Both {\it major} and {\it minor} have to be looked at as hexadecimal numbers. So \twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.} \twocolitem{OS/2}{Return value is wxOS2\_PM.} \twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.} -\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}} +\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}.} \twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.} \twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.} \twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.} +\twocolitem{Windows PocketPC}{Return value is wxWINDOWS\_POCKETPC, version is returned in {\it major} and {\it minor}.} +\twocolitem{Windows Smartphone}{Return value is wxWINDOWS\_SMARTPHONE, version is returned in {\it major} and {\it minor}.} +\twocolitem{Windows CE (non-specific)}{Return value is wxWINDOWS\_CE, version is returned in {\it major} and {\it minor}.} \twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.} \end{twocollist} @@ -1457,8 +1471,8 @@ is running, the entry {\bf Current} in the section {\bf User} of the PENWIN.INI file is used. The first variant of this function returns the user name if successful or an -empty string otherwise. The second (deprecated) function returns {\tt true} -if successful, {\tt false} otherwise. +empty string otherwise. The second (deprecated) function returns \true +if successful, \false otherwise. \wxheading{See also} @@ -1500,23 +1514,33 @@ as wxGetTranslation. The second form is used when retrieving translation of string that has different singular and plural form in English or different plural forms in some -other language. It takes two extra arguments: \arg{str} -parameter must contain the singular form of the string to be converted. -It is also used as the key for the search in the catalog. -The \arg{strPlural} parameter is the plural form (in English). -The parameter \arg{n} is used to determine the plural form. If no -message catalog is found \arg{str} is returned if `n == 1', +other language. It takes two extra arguments: as above, \arg{str} +parameter must contain the singular form of the string to be converted and +is used as the key for the search in the catalog. The \arg{strPlural} parameter +is the plural form (in English). The parameter \arg{n} is used to determine the +plural form. If no message catalog is found \arg{str} is returned if `n == 1', otherwise \arg{strPlural}. -See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} for additional information on plural forms handling. + +See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} +for additional information on plural forms handling. For a shorter alternative +see the \helpref{wxPLURAL()}{wxplural} macro. Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}. +Note that this function is not suitable for literal strings in Unicode +builds, since the literal strings must be enclosed into +\helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them +unrecognised by \texttt{xgettext}, and so they are not extracted to the message +catalog. Instead, use the \helpref{\_()}{underscore} and +\helpref{wxPLURAL}{wxplural} macro for all literal strings. + + \membersection{::wxIsEmpty}\label{wxisempty} \func{bool}{wxIsEmpty}{\param{const char *}{ p}} -Returns {\tt true} if the pointer is either {\tt NULL} or points to an empty -string, {\tt false} otherwise. +Returns \true if the pointer is either {\tt NULL} or points to an empty +string, \false otherwise. \membersection{::wxStrcmp}\label{wxstrcmp} @@ -1541,6 +1565,19 @@ This function complements the standard C function {\it strcmp()} which performs case-sensitive comparison. +\membersection{::wxStringEq}\label{wxstringeq} + +\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} + +{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead. + +A macro defined as: + +\begin{verbatim} +#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) +\end{verbatim} + + \membersection{::wxStringMatch}\label{wxstringmatch} \func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\ @@ -1548,22 +1585,24 @@ case-sensitive comparison. {\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead. -Returns {\tt true} if the substring {\it s1} is found within {\it s2}, -ignoring case if {\it exact} is false. If {\it subString} is {\tt false}, +Returns \true if the substring {\it s1} is found within {\it s2}, +ignoring case if {\it exact} is false. If {\it subString} is \false, no substring matching is done. -\membersection{::wxStringEq}\label{wxstringeq} +\membersection{::wxStringTokenize}\label{wxstringtokenize} -\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} +\func{wxArrayString}{wxStringTokenize}{\param{const wxString\& }{str},\\ + \param{const wxString\& }{delims = wxDEFAULT\_DELIMITERS},\\ + \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}} -{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead. - -A macro defined as: +This is a convenience function wrapping +\helpref{wxStringTokenizer}{wxstringtokenizer} which simply returns all tokens +found in the given \arg{str} in an array. -\begin{verbatim} -#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) -\end{verbatim} +Please see +\helpref{wxStringTokenizer::wxStringTokenizer}{wxstringtokenizerwxstringtokenizer} +for the description of the other parameters. \membersection{::wxStrlen}\label{wxstrlen} @@ -1684,6 +1723,14 @@ the string for the current locale during execution. Don't confuse this macro with \helpref{\_T()}{underscoret}! +\membersection{wxPLURAL}\label{wxplural} + +\func{const wxChar *}{wxPLURAL}{\param{const char *}{sing}, \param{const char *}{plur}, \param{size\_t}{n}} + +This macro is identical to \helpref{\_()}{underscore} but for the plural variant +of \helpref{wxGetTranslation}{wxgettranslation}. + + \membersection{\_T}\label{underscoret} \func{wxChar}{\_T}{\param{char }{ch}} @@ -2525,7 +2572,7 @@ Empties the clipboard. \membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats} -\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}} +\func{int}{wxEnumClipboardFormats}{\param{int}{ dataFormat}} Enumerates the formats found in a list of available formats that belong to the clipboard. Each call to this function specifies a known @@ -2546,7 +2593,7 @@ wxOpenClipboard function. \membersection{::wxGetClipboardData}\label{wxgetclipboarddata} -\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}} +\func{wxObject *}{wxGetClipboardData}{\param{int}{ dataFormat}} Gets data from the clipboard. @@ -2562,7 +2609,7 @@ The clipboard must have previously been opened for this call to succeed. \membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname} -\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}} +\func{bool}{wxGetClipboardFormatName}{\param{int}{ dataFormat}, \param{const wxString\& }{formatName}, \param{int}{ maxCount}} Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format. @@ -2570,7 +2617,7 @@ length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard \membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable} -\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}} +\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{ dataFormat}} Returns true if the given data format is available on the clipboard. @@ -2591,7 +2638,7 @@ Registers the clipboard data format name and returns an identifier. \membersection{::wxSetClipboardData}\label{wxsetclipboarddata} -\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}} +\func{bool}{wxSetClipboardData}{\param{int}{ dataFormat}, \param{wxObject*}{ data}, \param{int}{ width}, \param{int}{ height}} Passes data to the clipboard. @@ -2607,8 +2654,6 @@ Passes data to the clipboard. The clipboard must have previously been opened for this call to succeed. - - \section{Miscellaneous functions}\label{miscellany} @@ -2657,9 +2702,14 @@ this language feature but still take advantage of it when it is available. \func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}} -Returns \true if the key parameter is currently pressed on the keyboard, or -with modifier keys, (caps lock, etc) if the key is active (the led light is -on). +For normal keys, returns \true if the specified key is currently down. + +For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns +\true if the key is toggled such that its LED indicator is lit. There is +currently no way to test whether togglable keys are up or down. + +Even though there are virtual key codes defined for mouse buttons, they +cannot be used with this function currently. \wxheading{Include files} @@ -2721,6 +2771,48 @@ Generates an integer identifier unique to this run of the program. +\membersection{wxON\_BLOCK\_EXIT}\label{wxonblockexit} + +\func{}{wxON\_BLOCK\_EXIT0}{\param{}{func}} +\func{}{wxON\_BLOCK\_EXIT1}{\param{}{func}, \param{}{p1}} +\func{}{wxON\_BLOCK\_EXIT2}{\param{}{func}, \param{}{p1}, \param{}{p2}} + +This family of macros allows to ensure that the global function \arg{func} +with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is +executed on scope exit, whether due to a normal function return or because an +exception has been thrown. A typical example of its usage: +\begin{verbatim} + void *buf = malloc(size); + wxON_BLOCK_EXIT1(free, buf); +\end{verbatim} + +Please see the original article by Andrei Alexandrescu and Petru Marginean +published in December 2000 issue of \emph{C/C++ Users Journal} for more +details. + +\wxheading{Include files} + + + +\wxheading{See also} + +\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj} + + +\membersection{wxON\_BLOCK\_EXIT\_OBJ}\label{wxonblockexitobj} + +\func{}{wxON\_BLOCK\_EXIT\_OBJ0}{\param{}{obj}, \param{}{method}} +\func{}{wxON\_BLOCK\_EXIT\_OBJ1}{\param{}{obj}, \param{}{method}, \param{}{p1}} +\func{}{wxON\_BLOCK\_EXIT\_OBJ2}{\param{}{obj}, \param{}{method}, \param{}{p1}, \param{}{p2}} + +This family of macros is similar to \helpref{wxON\_BLOCK\_EXIT}{wxonblockexit} +but calls a method of the given object instead of a free function. + +\wxheading{Include files} + + + + \membersection{::wxRegisterId}\label{wxregisterid} \func{void}{wxRegisterId}{\param{long}{ id}} @@ -2766,7 +2858,7 @@ See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows} -\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = true}} +\func{void}{wxEnableTopLevelWindows}{\param{bool}{ enable = true}} This function enables or disables all top level windows. It is used by \helpref{::wxSafeYield}{wxsafeyield}. @@ -2938,7 +3030,7 @@ See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxco \membersection{::wxGetStockLabel}\label{wxgetstocklabel} -\func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{wxString }{accelerator = wxEmptyString}} +\func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{const wxString\& }{accelerator = wxEmptyString}} Returns label that should be used for given {\it id} element. @@ -2970,6 +3062,21 @@ frame or dialog containing it, or {\tt NULL}. +\membersection{::wxLaunchDefaultBrowser}\label{wxlaunchdefaultbrowser} + +\func{bool}{wxLaunchDefaultBrowser}{\param{const wxString\& }{url}, \param{int }{flags = $0$}} + +Open the \arg{url} in user's default browser. If \arg{flags} parameter contains +\texttt{wxBROWSER\_NEW\_WINDOW} flag, a new window is opened for the URL +(currently this is only supported under Windows). + +Returns \true if the application was successfully launched. + +\wxheading{Include files} + + + + \membersection{::wxLoadUserResource}\label{wxloaduserresource} \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} @@ -3083,7 +3190,7 @@ allows to define unsigned 64 bit compile time constants: \membersection{wxVaCopy}\label{wxvacopy} -\func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{argptrSrc}} +\func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{ argptrSrc}} This macro is the same as the standard C99 \texttt{va\_copy} for the compilers which support it or its replacement for those that don't. It must be used to @@ -3282,8 +3389,11 @@ dynamically. The same as DECLARE\_ABSTRACT\_CLASS. \func{}{DECLARE\_DYNAMIC\_CLASS}{className} -Used inside a class declaration to declare that the objects of this class should be dynamically -creatable from run-time type information. +Used inside a class declaration to make the class known to wxWidgets RTTI +system and also declare that the objects of this class should be dynamically +creatable from run-time type information. Notice that this implies that the +class should have a default constructor, if this is not the case consider using +\helpref{DECLARE\_CLASS}{declareclass}. Example: @@ -3573,8 +3683,20 @@ star is not appended to it. \wxheading{See also} \helpref{wx\_const\_cast}{wxconstcastraw},\\ -\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw} +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ +\helpref{wx\_truncate\_cast}{wxtruncatecast} + + +\membersection{wx\_truncate\_cast}\label{wxtruncatecast} +\func{T}{wx\_truncate\_cast}{T, x} + +This case doesn't correspond to any standard cast but exists solely to make +casts which possibly result in a truncation of an integer value more readable. + +\wxheading{See also} + +\helpref{wx\_static\_cast}{wxstaticcastraw} \section{Log functions}\label{logfunctions} @@ -4328,7 +4450,7 @@ Returns the current value of the environment variable {\it var} in {\it value}. {\it value} may be {\tt NULL} if you just want to know if the variable exists and are not interested in its value. -Returns {\tt true} if the variable exists, {\tt false} otherwise. +Returns \true if the variable exists, \false otherwise. \membersection{wxSetEnv}\label{wxsetenv} @@ -4338,7 +4460,7 @@ Returns {\tt true} if the variable exists, {\tt false} otherwise. Sets the value of the environment variable {\it var} (adding it if necessary) to {\it value}. -Returns {\tt true} on success. +Returns \true on success. \membersection{wxUnsetEnv}\label{wxunsetenv} @@ -4349,5 +4471,5 @@ Removes the variable {\it var} from the environment. \helpref{wxGetEnv}{wxgetenv} will return {\tt NULL} after the call to this function. -Returns {\tt true} on success. +Returns \true on success.