X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/daf3246330c8ae7b4536cd1f6deef733a405cecd..9180b5352f9d5b5bcccee563e9b3c0f68c4f1303:/docs/latex/wx/function.tex?ds=sidebyside diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index d31df54da0..9abdc11976 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -6,7 +6,7 @@ The functions and macros defined in wxWidgets are described here: you can either look up a function using the alphabetical listing of them or find it in the corresponding topic. -\section{Alphabetical functions and macros list} +\section{Alphabetical functions and macros list}\label{functionsalphabetically} \helpref{CLASSINFO}{classinfo}\\ \helpref{copystring}{copystring}\\ @@ -21,7 +21,6 @@ the corresponding topic. \helpref{IMPLEMENT\_CLASS}{implementclass}\\ \helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\ \helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\ -\helpref{ngettext}{ngettext}\\ \helpref{wxCONCAT}{wxconcat}\\ \helpref{WXDEBUG\_NEW}{debugnew}\\ \helpref{WXTRACELEVEL}{tracelevel}\\ @@ -32,6 +31,7 @@ the corresponding topic. \helpref{wxBITMAP}{wxbitmapmacro}\\ \helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\ \helpref{wxBell}{wxbell}\\ +\helpref{wxCHANGE\_UMASK}{wxchangeumask}\\ \helpref{wxCHECK}{wxcheck}\\ \helpref{wxCHECK2\_MSG}{wxcheck2msg}\\ \helpref{wxCHECK2}{wxcheck2}\\ @@ -39,6 +39,7 @@ the corresponding topic. \helpref{wxCHECK\_MSG}{wxcheckmsg}\\ \helpref{wxCHECK\_RET}{wxcheckret}\\ \helpref{wxCHECK\_VERSION}{wxcheckversion}\\ +\helpref{wxCHECK\_VERSION\_FULL}{wxcheckversionfull}\\ \helpref{wxCHECK\_W32API\_VERSION}{wxcheckw32apiversion}\\ \helpref{wxClientDisplayRect}{wxclientdisplayrect}\\ \helpref{wxClipboardOpen}{functionwxclipboardopen}\\ @@ -101,6 +102,8 @@ the corresponding topic. \helpref{wxGetCwd}{wxgetcwd}\\ \helpref{wxGetDiskSpace}{wxgetdiskspace}\\ \helpref{wxGetDisplayName}{wxgetdisplayname}\\ +\helpref{wxGetDisplaySize}{wxdisplaysize}\\ +\helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\ \helpref{wxGetElapsedTime}{wxgetelapsedtime}\\ \helpref{wxGetEmailAddress}{wxgetemailaddress}\\ \helpref{wxGetEnv}{wxgetenv}\\ @@ -109,6 +112,7 @@ the corresponding topic. \helpref{wxGetFullHostName}{wxgetfullhostname}\\ \helpref{wxGetHomeDir}{wxgethomedir}\\ \helpref{wxGetHostName}{wxgethostname}\\ +\helpref{wxGetKeyState}{wxgetkeystate}\\ \helpref{wxGetLocalTimeMillis}{wxgetlocaltimemillis}\\ \helpref{wxGetLocalTime}{wxgetlocaltime}\\ \helpref{wxGetMousePosition}{wxgetmouseposition}\\ @@ -174,6 +178,8 @@ the corresponding topic. \helpref{wxMakeMetafilePlaceable}{wxmakemetafileplaceable}\\ \helpref{wxMatchWild}{wxmatchwild}\\ \helpref{wxMessageBox}{wxmessagebox}\\ +\helpref{wxMilliSleep}{wxmillisleep}\\ +\helpref{wxMicroSleep}{wxmicrosleep}\\ \helpref{wxMkdir}{wxmkdir}\\ \helpref{wxMutexGuiEnter}{wxmutexguienter}\\ \helpref{wxMutexGuiLeave}{wxmutexguileave}\\ @@ -232,11 +238,13 @@ the corresponding topic. \helpref{wxUnix2DosFilename}{wxunix2dosfilename}\\ \helpref{wxUnsetEnv}{wxunsetenv}\\ \helpref{wxUsleep}{wxusleep}\\ +\helpref{wxVaCopy}{wxvacopy}\\ \helpref{wxVsnprintf}{wxvsnprintf}\\ \helpref{wxWakeUpIdle}{wxwakeupidle}\\ \helpref{wxWriteResource}{wxwriteresource}\\ \helpref{wxYield}{wxyield}\\ \helpref{wx\_const\_cast}{wxconstcastraw}\\ +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\ \helpref{wx\_static\_cast}{wxstaticcastraw}\\ \helpref{\_}{underscore}\\ \helpref{\_T}{underscoret} @@ -251,6 +259,8 @@ The following constants are defined in wxWidgets: \item {\tt wxMAJOR\_VERSION} is the major version of wxWidgets \item {\tt wxMINOR\_VERSION} is the minor version of wxWidgets \item {\tt wxRELEASE\_NUMBER} is the release number +\item {\tt wxSUBRELEASE\_NUMBER} is the subrelease number which is $0$ for all +official releases \end{itemize} For example, the values or these constants for wxWidgets 2.1.15 are 2, 1 and @@ -261,11 +271,23 @@ the full wxWidgets version and {\tt wxVERSION\_NUMBER} is a combination of the three version numbers above: for 2.1.15, it is 2115 and it is 2200 for wxWidgets 2.2. +The subrelease number is only used for the sources in between official releases +and so normally is not useful. + \wxheading{Include files} or +\membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion} + +\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}} + +Returns $1$ if the compiler being used to compile the code is GNU C++ +compiler (g++) version major.minor.release or greater. Otherwise, and also if +the compiler is not GNU C++ at all, returns $0$. + + \membersection{wxCHECK\_VERSION}\label{wxcheckversion} \func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}} @@ -289,13 +311,12 @@ the following can be done: \end{verbatim} -\membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion} +\membersection{wxCHECK\_VERSION\_FULL}\label{wxcheckversionfull} -\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}} +\func{bool}{wxCHECK\_VERSION\_FULL}{\param{}{major, minor, release, subrel}} -Returns $1$ if the compiler being used to compile the code is GNU C++ -compiler (g++) version major.minor.release or greater. Otherwise, and also if -the compiler is not GNU C++ at all, returns $0$. +Same as \helpref{wxCHECK\_VERSION}{wxcheckversion} but also checks that +\texttt{wxSUBRELEASE\_NUMBER} is at least \arg{subrel}. \membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion} @@ -556,9 +577,9 @@ happening, i.e. with this flag the child process window will be shown normally. Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure that the new process is a group leader (this will create a new session if -needed). Calling \helpref{wxKill}{wxkill} with the argument of -pid where pid -is the process ID of the new process will kill this process as well as all of -its children (except those which have started their own session). +needed). Calling \helpref{wxKill}{wxkill} passing wxKILL\_CHILDREN will +will kill this process as well as all of its children (except those which have +started their own session). Finally, you may use the third overloaded version of this function to execute a process (always synchronously) and capture its output in the array @@ -608,7 +629,7 @@ application. See \helpref{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp} \membersection{::wxKill}\label{wxkill} -\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}} +\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}, \param{int }{flags = 0}} Equivalent to the Unix kill function: send the given signal {\it sig} to the process with PID {\it pid}. The valid signal values are @@ -653,6 +674,12 @@ enum wxKillError }; \end{verbatim} +The {\it flags} parameter can be wxKILL\_NOCHILDREN (the default), +or wxKILL\_CHILDREN, in which case the child processes of this +process will be killed too. Note that under Unix, for wxKILL\_CHILDREN +to work you should have created the process by passing wxEXEC\_MAKE_GROUP\_LEADER +to wxExecute. + \wxheading{See also} \helpref{wxProcess::Kill}{wxprocesskill},\rtfsp @@ -870,7 +897,7 @@ threads. \wxheading{Include files} - + \wxheading{See also} @@ -931,6 +958,10 @@ that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFi get the next matching file. Neither will report the current directory "." or the parent directory "..". +\wxheading{Warning} + +As of wx 2.5.2, these functions are not thread-safe! (use static variables) + {\it spec} may contain wildcards. {\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either. @@ -1008,6 +1039,18 @@ Converts a Unix to a DOS filename by replacing forward slashes with backslashes. +\membersection{wxCHANGE\_UMASK}\label{wxchangeumask} + +\func{}{wxCHANGE\_UMASK}{\param{int }{mask}} + +Under Unix this macro changes the current process umask to the given value, +unless it is equal to $-1$ in which case nothing is done, and restores it to +the original value on scope exit. It works by declaring a variable which sets +umask to \arg{mask} in its constructor and restores it in its destructor. + +Under other platforms this macro expands to nothing. + + \membersection{::wxConcatFiles}\label{wxconcatfiles} \func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, @@ -1395,7 +1438,7 @@ if successful, {\tt false} otherwise. -\section{String functions} +\section{String functions}\label{stringfunctions} \membersection{::copystring}\label{copystring} @@ -1408,22 +1451,6 @@ deleted with the {\it delete} operator. This function is deprecated, use \helpref{wxString}{wxstring} class instead. -\membersection{ngettext}\label{ngettext} - -\func{const wxChar *}{ngettext}{\param{const char *}{str}, \param{const char *}{strPlural}, \param{size\_t }{n}} - -This macro expands into a call to plural form version of -\helpref{wxGetTranslation}{wxgettranslation} -function, so it marks the message for the extraction by {\tt xgettext} just as -\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of -the string for the current locale during execution, either singular or plural -form depending on the value of \arg{n}. - -\wxheading{See also} - -\helpref{\_}{underscore} - - \membersection{::wxGetTranslation}\label{wxgettranslation} \func{const char *}{wxGetTranslation}{\param{const char * }{str}} @@ -1447,10 +1474,11 @@ 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', -otherwise \arg{strPlural}. The \helpref{ngettext}{ngettext} macro is defined -to do the same thing. +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. +Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}. + \membersection{::wxIsEmpty}\label{wxisempty} \func{bool}{wxIsEmpty}{\param{const char *}{ p}} @@ -1623,11 +1651,6 @@ the string for the current locale during execution. Don't confuse this macro with \helpref{\_T()}{underscoret}! -\wxheading{See also} - -\helpref{ngettext}{ngettext} - - \membersection{\_T}\label{underscoret} @@ -1732,7 +1755,7 @@ if ( !dir.empty() ) \func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\ \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\ - \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = ""},\\ + \param{const wxString\& }{wildcard = "*.*"}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\ \param{int}{ x = -1}, \param{int}{ y = -1}} Pops up a file selector box. In Windows, this is the common file selector @@ -1901,8 +1924,9 @@ Dialog is centered on its {\it parent} unless an explicit position is given in \membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser} -\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ - \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}} +\func{wxString}{wxGetPasswordFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ + \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}} Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered in the dialog is not shown on screen but replaced with stars. This is intended @@ -1917,7 +1941,7 @@ to be used for entering passwords as the function name implies. \func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ - \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = true}} + \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}} Pop up a dialog box with title set to {\it caption}, {\it message}, and a \rtfsp{\it default\_value}. The user may type in text and press OK to return this text, @@ -2117,7 +2141,7 @@ message will be split into separate lines, to cater for large messages. \param{bool }{showAtStartup = true}} This function shows a "startup tip" to the user. The return value is the -state of the ``Show tips at startup'' checkbox. +state of the `Show tips at startup' checkbox. \docparam{parent}{The parent window for the modal dialog} @@ -2139,7 +2163,7 @@ checkbox which is shown in the tips dialog.} -\section{Math functions} +\section{Math functions}\label{mathfunctions} \wxheading{Include files} @@ -2597,6 +2621,19 @@ code which might have to be compiled with an old compiler without support for this language feature but still take advantage of it when it is available. +\membersection{::wxGetKeyState}\label{wxgetkeystate} + +\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). + +\wxheading{Include files} + + + + \membersection{wxLL}\label{wxll} \func{wxLongLong\_t}{wxLL}{\param{}{number}} @@ -2961,6 +2998,19 @@ allows to define unsigned 64 bit compile time constants: \helpref{wxLL}{wxll}, \helpref{wxLongLong}{wxlonglong} +\membersection{wxVaCopy}\label{wxvacopy} + +\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 +preserve the value of a \texttt{va\_list} object if you need to use it after +passing it to another function because it can be modified by the latter. + +As with \texttt{va\_start}, each call to \texttt{wxVaCopy} must have a matching +\texttt{va\_end}. + + \membersection{::wxWriteResource}\label{wxwriteresource} \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, @@ -3410,7 +3460,21 @@ arguments is the same as for the standard cast. \wxheading{See also} -\helpref{wx\_static\_cast}{wxstaticcastraw}\\ +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ +\helpref{wx\_static\_cast}{wxstaticcastraw} + + +\membersection{wx\_reinterpret\_cast}\label{wxreinterpretcastraw} + +\func{T}{wx\_reinterpret\_cast}{T, x} + +Same as \texttt{reinterpret\_cast(x)} if the compiler supports reinterpret cast or +\texttt{(T)x} for old compilers. + +\wxheading{See also} + +\helpref{wx\_const\_cast}{wxconstcastraw},\\ +\helpref{wx\_static\_cast}{wxstaticcastraw} \membersection{wx\_static\_cast}\label{wxstaticcastraw} @@ -3425,7 +3489,8 @@ star is not appended to it. \wxheading{See also} -\helpref{wx\_const\_cast}{wxconstcastraw}\\ +\helpref{wx\_const\_cast}{wxconstcastraw},\\ +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw} @@ -3640,7 +3705,14 @@ used by wxWidgets are: \item wxTRACE\_OleCalls: trace OLE method calls (Win32 only) \end{itemize} -The third version of the function only logs the message if all the bit +{\bf Caveats:} since both the mask and the format string are strings, +this might lead to function signature confusion in some cases: +if you intend to call the format string only version of wxLogTrace, +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. +In this case you'll unfortunately have to avoid having two leading +string parameters, e.g. by adding a bogus integer (with its \%d format string). + +The third version of the function only logs the message if all the bits corresponding to the {\it mask} are set in the wxLog trace mask which can be set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less flexible than the previous one because it doesn't allow defining the user @@ -3850,6 +3922,33 @@ Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. +\membersection{::wxMicroSleep}\label{wxmicrosleep} + +\func{void}{wxMicroSleep}{\param{unsigned long}{ microseconds}} + +Sleeps for the specified number of microseconds. The microsecond resolution may +not, in fact, be available on all platforms (currently only Unix platforms with +nanosleep(2) may provide it) in which case this is the same as +\helpref{wxMilliSleep}{wxmillisleep}(\arg{microseconds}$/1000$). + +\wxheading{Include files} + + + + +\membersection{::wxMilliSleep}\label{wxmillisleep} + +\func{void}{wxMilliSleep}{\param{unsigned long}{ milliseconds}} + +Sleeps for the specified number of milliseconds. Notice that usage of this +function is encouraged instead of calling usleep(3) directly because the +standard usleep() function is not MT safe. + +\wxheading{Include files} + + + + \membersection{::wxNow}\label{wxnow} \func{wxString}{wxNow}{\void} @@ -3889,13 +3988,10 @@ See also \helpref{wxTimer}{wxtimer}. \func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}} -Sleeps for the specified number of milliseconds. Notice that usage of this -function is encouraged instead of calling usleep(3) directly because the -standard usleep() function is not MT safe. - -\wxheading{Include files} - - +This function is deprecated because its name is misleading: notice that the +argument is in milliseconds, not microseconds. Please use either +\helpref{wxMilliSleep}{wxmillisleep} or \helpref{wxMicroSleep}{wxmicrosleep} +depending on the resolution you need. @@ -3997,8 +4093,8 @@ either change the line in which either of them appears on or use the \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} macro. Also note that Microsoft Visual C++ has a bug which results in compiler errors -if you use this macro with ``Program Database For Edit And Continue'' -(\texttt{/ZI}) option, so you shouldn't use it (``Program Database'' +if you use this macro with `Program Database For Edit And Continue' +(\texttt{/ZI}) option, so you shouldn't use it (`Program Database' (\texttt{/Zi}) is ok though) for the code making use of this macro. \wxheading{See also}