X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9d8aca4832f9052729d2fc51d25c23f6d7006cab..60b1fda237b5544162b8df38ca89cdef23e3f6b1:/docs/latex/wx/function.tex

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index ad14fa41f1..42069bf337 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}\\
@@ -96,6 +95,7 @@ the corresponding topic.
 \helpref{wxFinite}{wxfinite}\\
 \helpref{wxGetActiveWindow}{wxgetactivewindow}\\
 \helpref{wxGetApp}{wxgetapp}\\
+\helpref{wxGetBatteryState}{wxgetbatterystate}\\
 \helpref{wxGetClipboardData}{wxgetclipboarddata}\\
 \helpref{wxGetClipboardFormatName}{wxgetclipboardformatname}\\
 \helpref{wxGetColourFromUser}{wxgetcolourfromuser}\\
@@ -107,6 +107,7 @@ the corresponding topic.
 \helpref{wxGetElapsedTime}{wxgetelapsedtime}\\
 \helpref{wxGetEmailAddress}{wxgetemailaddress}\\
 \helpref{wxGetEnv}{wxgetenv}\\
+\helpref{wxGetFileKind}{wxgetfilekind}\\
 \helpref{wxGetFontFromUser}{wxgetfontfromuser}\\
 \helpref{wxGetFreeMemory}{wxgetfreememory}\\
 \helpref{wxGetFullHostName}{wxgetfullhostname}\\
@@ -123,6 +124,7 @@ the corresponding topic.
 \helpref{wxGetOsDescription}{wxgetosdescription}\\
 \helpref{wxGetOsVersion}{wxgetosversion}\\
 \helpref{wxGetPasswordFromUser}{wxgetpasswordfromuser}\\
+\helpref{wxGetPowerType}{wxgetpowertype}\\
 \helpref{wxGetPrinterCommand}{wxgetprintercommand}\\
 \helpref{wxGetPrinterFile}{wxgetprinterfile}\\
 \helpref{wxGetPrinterMode}{wxgetprintermode}\\
@@ -188,6 +190,7 @@ the corresponding topic.
 \helpref{wxOnAssert}{wxonassert}\\
 \helpref{wxOpenClipboard}{wxopenclipboard}\\
 \helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\
+\helpref{wxPathExists}{functionwxpathexists}\\
 \helpref{wxPathOnly}{wxpathonly}\\
 \helpref{wxPostDelete}{wxpostdelete}\\
 \helpref{wxPostEvent}{wxpostevent}\\
@@ -681,7 +684,7 @@ enum wxKillError
 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 work you should have created the process by passing wxEXEC\_MAKE\_GROUP\_LEADER
 to wxExecute.
 
 \wxheading{See also}
@@ -911,13 +914,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}}
@@ -974,7 +970,7 @@ For example:
 
 \begin{verbatim}
   wxString f = wxFindFirstFile("/home/project/*.*");
-  while ( !f.IsEmpty() )
+  while ( !f.empty() )
   {
     ...
     f = wxFindNextFile();
@@ -1013,6 +1009,30 @@ Mac OS and generic Unix provided the system has {\tt statfs()} function.
 This function first appeared in wxWidgets 2.3.2.
 
 
+\membersection{::wxGetFileKind}\label{wxgetfilekind}
+
+\func{wxFileKind}{wxGetFileKind}{\param{int }{fd}}
+
+\func{wxFileKind}{wxGetFileKind}{\param{FILE *}{fp}}
+
+Returns the type of an open file. Possible return values are:
+
+\begin{verbatim}
+enum wxFileKind
+{
+  wxFILE_KIND_UNKNOWN,
+  wxFILE_KIND_DISK,     // a file supporting seeking to arbitrary offsets
+  wxFILE_KIND_TERMINAL, // a tty
+  wxFILE_KIND_PIPE      // a pipe
+};
+
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/filefn.h>
+
+
 \membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
 
 \func{wxString}{wxGetOSDirectory}{\void}
@@ -1028,6 +1048,13 @@ Returns true if the argument is an absolute filename, i.e. with a slash
 or drive name at the beginning.
 
 
+\membersection{::wxPathExists}\label{functionwxpathexists}
+
+\func{bool}{wxPathExists}{\param{const wxString\& }{dirname}}
+
+Returns true if the path exists.
+
+
 \membersection{::wxPathOnly}\label{wxpathonly}
 
 \func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
@@ -1242,13 +1269,29 @@ The functions in this section are used to retrieve information about the
 current computer and/or user characteristics.
 
 
+\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
+
+\func{wxString}{wxGetEmailAddress}{\void}
+
+\func{bool}{wxGetEmailAddress}{\param{char * }{buf}, \param{int }{sz}}
+
+Copies the user's email address into the supplied buffer, by
+concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
+and \helpref{wxGetUserId}{wxgetuserid}.
+
+Returns true if successful, false otherwise.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
 \membersection{::wxGetFreeMemory}\label{wxgetfreememory}
 
 \func{wxMemorySize}{wxGetFreeMemory}{\void}
 
 Returns the amount of free memory in bytes under environments which
-support it, and -1 if not supported. Currently, it is supported only
-under Windows, Linux and Solaris.
+support it, and -1 if not supported or failed to perform measurement.
 
 \wxheading{Include files}
 
@@ -1271,21 +1314,6 @@ error.
 <wx/utils.h>
 
 
-\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
-
-\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
-
-Copies the user's email address into the supplied buffer, by
-concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
-and \helpref{wxGetUserId}{wxgetuserid}.
-
-Returns true if successful, false otherwise.
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
-
 \membersection{::wxGetHomeDir}\label{wxgethomedir}
 
 \func{wxString}{wxGetHomeDir}{\void}
@@ -1328,32 +1356,6 @@ if successful, false otherwise.
 <wx/utils.h>
 
 
-\membersection{::wxGetUserId}\label{wxgetuserid}
-
-\func{wxString}{wxGetUserId}{\void}
-
-\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
-
-This function returns the "user id" also known as "login name" under Unix i.e.
-something like "jsmith". It uniquely identifies the current user (on this system).
-
-Under Windows or NT, this function first looks in the environment
-variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
-in the {\bf wxWidgets} section of the WIN.INI file is tried.
-
-The first variant of this function returns the login name if successful or an
-empty string otherwise. The second (deprecated) function returns true
-if successful, false otherwise.
-
-\wxheading{See also}
-
-\helpref{wxGetUserName}{wxgetusername}
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
-
 \membersection{::wxGetOsDescription}\label{wxgetosdescription}
 
 \func{wxString}{wxGetOsDescription}{\void}
@@ -1386,10 +1388,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}
 
@@ -1415,6 +1420,32 @@ Returns the home directory for the given user. If the username is empty
 <wx/utils.h>
 
 
+\membersection{::wxGetUserId}\label{wxgetuserid}
+
+\func{wxString}{wxGetUserId}{\void}
+
+\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
+
+This function returns the "user id" also known as "login name" under Unix i.e.
+something like "jsmith". It uniquely identifies the current user (on this system).
+
+Under Windows or NT, this function first looks in the environment
+variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
+in the {\bf wxWidgets} section of the WIN.INI file is tried.
+
+The first variant of this function returns the login name if successful or an
+empty string otherwise. The second (deprecated) function returns true
+if successful, false otherwise.
+
+\wxheading{See also}
+
+\helpref{wxGetUserName}{wxgetusername}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
 \membersection{::wxGetUserName}\label{wxgetusername}
 
 \func{wxString}{wxGetUserName}{\void}
@@ -1605,7 +1636,7 @@ initialization.
 
 Here is an example which should make it more clear: suppose that you have a
 static array of strings containing the weekday names and which have to be
-translated (note that it is a bad example, really, as 
+translated (note that it is a bad example, really, as
 \helpref{wxDateTime}{wxdatetime} already can be used to get the localized week
 day names already). If you write
 
@@ -1648,7 +1679,7 @@ argument instead of arbitrary number of parameters.
 
 \func{const wxChar *}{\_}{\param{const char *}{s}}
 
-This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation} 
+This macro expands into a call to \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.
@@ -2178,7 +2209,7 @@ checkbox which is shown in the tips dialog.}
 
 \func{int}{wxFinite}{\param{double }{x}}
 
-Returns a non-zero value if {\it x} is neither infinite or NaN (not a number), 
+Returns a non-zero value if {\it x} is neither infinite or NaN (not a number),
 returns 0 otherwise.
 
 
@@ -2595,7 +2626,7 @@ This macro returns the concatenation of two tokens \arg{x} and \arg{y}.
 
 \func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}}
 
-When loading a function from a DLL you always have to cast the returned 
+When loading a function from a DLL you always have to cast the returned
 {\tt void *} pointer to the correct type and, even more annoyingly, you have to
 repeat this type twice if you want to declare and define a function pointer all
 in one line
@@ -2603,7 +2634,7 @@ in one line
 This macro makes this slightly less painful by allowing you to specify the
 type only once, as the first parameter, and creating a variable of this type
 named after the function but with {\tt pfn} prefix and initialized with the
-function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary} 
+function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary}
 \arg{dynlib}.
 
 \wxheading{Parameters}
@@ -2629,9 +2660,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}
 
@@ -2822,6 +2858,21 @@ Gets the currently active window (Windows only).
 <wx/windows.h>
 
 
+\membersection{::wxGetBatteryState}\label{wxgetbatterystate}
+
+\func{wxBatteryState}{wxGetBatteryState}{\void}
+
+Returns battery state as one of \texttt{wxBATTERY\_NORMAL\_STATE},
+\texttt{wxBATTERY\_LOW\_STATE}, \texttt{wxBATTERY\_CRITICAL\_STATE},
+\texttt{wxBATTERY\_SHUTDOWN\_STATE} or \texttt{wxBATTERY\_UNKNOWN\_STATE}.
+\texttt{wxBATTERY\_UNKNOWN\_STATE} is also the default on platforms where
+this feature is not implemented.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
 \membersection{::wxGetDisplayName}\label{wxgetdisplayname}
 
 \func{wxString}{wxGetDisplayName}{\void}
@@ -2833,6 +2884,20 @@ Under X only, returns the current display name. See also \helpref{wxSetDisplayNa
 <wx/utils.h>
 
 
+\membersection{::wxGetPowerType}\label{wxgetpowertype}
+
+\func{wxPowerType}{wxGetPowerType}{\void}
+
+Returns the type of power source as one of \texttt{wxPOWER\_SOCKET},
+\texttt{wxPOWER\_BATTERY} or \texttt{wxPOWER\_UNKNOWN}.
+\texttt{wxPOWER\_UNKNOWN} is also the default on platforms where this
+feature is not implemented.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
 \membersection{::wxGetMousePosition}\label{wxgetmouseposition}
 
 \func{wxPoint}{wxGetMousePosition}{\void}
@@ -2879,6 +2944,28 @@ See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxco
 <wx/utils.h>
 
 
+\membersection{::wxGetStockLabel}\label{wxgetstocklabel}
+
+\func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{wxString }{accelerator = wxEmptyString}}
+
+Returns label that should be used for given {\it id} element.
+
+\wxheading{Parameters}
+
+\docparam{id}{given id of the \helpref{wxMenuItem}{wxmenuitem}, \helpref{wxButton}{wxbutton}, \helpref{wxToolBar}{wxtoolbar} tool, etc.}
+
+\docparam{withCodes}{if false then strip accelerator code from the label;
+usefull for getting labels without accelerator char code like for toolbar tooltip or
+under platforms without traditional keyboard like smartphones}
+
+\docparam{accelerator}{optional accelerator string automatically added to label; useful
+for building labels for \helpref{wxMenuItem}{wxmenuitem}}
+
+\wxheading{Include files}
+
+<wx/stockitem.h>
+
+
 \membersection{::wxGetTopLevelParent}\label{wxgettoplevelparent}
 
 \func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}}
@@ -3011,7 +3098,7 @@ 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 
+As with \texttt{va\_start}, each call to \texttt{wxVaCopy} must have a matching
 \texttt{va\_end}.
 
 
@@ -3170,9 +3257,9 @@ class wxCommand: public wxObject
 
 \func{}{DECLARE\_APP}{className}
 
-This is used in headers to create a forward declaration of the 
-\helpref{wxGetApp}{wxgetapp} function implemented by 
-\helpref{IMPLEMENT\_APP}{implementapp}. It creates the declaration 
+This is used in headers to create a forward declaration of the
+\helpref{wxGetApp}{wxgetapp} function implemented by
+\helpref{IMPLEMENT\_APP}{implementapp}. It creates the declaration
 {\tt className\& wxGetApp(void)}.
 
 Example:
@@ -3421,7 +3508,7 @@ Example:
 \helpref{RTTI overview}{runtimeclassoverview}\\
 \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
 \helpref{wxConstCast}{wxconstcast}\\
-\helpref{wxStatiicCast}{wxstaticcast}
+\helpref{wxStaticCast}{wxstaticcast}
 
 
 \membersection{wxDynamicCastThis}\label{wxdynamiccastthis}
@@ -3457,7 +3544,7 @@ result of executing an equivalent of {\tt static\_cast<classname *>(ptr)}.
 
 \func{T}{wx\_const\_cast}{T, x}
 
-Same as \texttt{const\_cast<T>(x)} if the compiler supports const cast or 
+Same as \texttt{const\_cast<T>(x)} if the compiler supports const cast or
 \texttt{(T)x} for old compilers. Unlike \helpref{wxConstCast}{wxconstcast},
 the cast it to the type \arg{T} and not to \texttt{T *} and also the order of
 arguments is the same as for the standard cast.
@@ -3472,7 +3559,7 @@ arguments is the same as for the standard cast.
 
 \func{T}{wx\_reinterpret\_cast}{T, x}
 
-Same as \texttt{reinterpret\_cast<T>(x)} if the compiler supports reinterpret cast or 
+Same as \texttt{reinterpret\_cast<T>(x)} if the compiler supports reinterpret cast or
 \texttt{(T)x} for old compilers.
 
 \wxheading{See also}
@@ -3485,7 +3572,7 @@ Same as \texttt{reinterpret\_cast<T>(x)} if the compiler supports reinterpret ca
 
 \func{T}{wx\_static\_cast}{T, x}
 
-Same as \texttt{static\_cast<T>(x)} if the compiler supports static cast or 
+Same as \texttt{static\_cast<T>(x)} if the compiler supports static cast or
 \texttt{(T)x} for old compilers. Unlike \helpref{wxStaticCast}{wxstaticcast},
 there are no checks being done and the meaning of the macro arguments is exactly
 the same as for the standard static cast, i.e. \arg{T} is the full type name and
@@ -3606,11 +3693,7 @@ the program work.
 \func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
 
 For all normal, informational messages. They also appear in a message box by
-default (but it can be changed). Notice that the standard behaviour is to not
-show informational messages if there are any errors later - the logic being
-that the later error messages make the informational messages preceding them
-meaningless.
-
+default (but it can be changed).
 
 \membersection{::wxLogVerbose}\label{wxlogverbose}
 
@@ -3932,7 +4015,7 @@ Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
 
 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 
+nanosleep(2) may provide it) in which case this is the same as
 \helpref{wxMilliSleep}{wxmillisleep}(\arg{microseconds}$/1000$).
 
 \wxheading{Include files}
@@ -3993,8 +4076,8 @@ See also \helpref{wxTimer}{wxtimer}.
 \func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
 
 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} 
+argument is in milliseconds, not microseconds. Please use either
+\helpref{wxMilliSleep}{wxmillisleep} or \helpref{wxMicroSleep}{wxmicrosleep}
 depending on the resolution you need.
 
 
@@ -4212,11 +4295,10 @@ In release mode this function does nothing.
 
 \func{bool}{wxIsDebuggerRunning}{\void}
 
-Returns {\tt true} if the program is running under debugger, {\tt false} 
-otherwise.
+Returns \true if the program is running under debugger, \false otherwise.
 
-Please note that this function is currently only implemented for Mac builds
-using CodeWarrior and always returns {\tt false} elsewhere.
+Please note that this function is currently only implemented for Win32 and Mac
+builds using CodeWarrior and always returns \false elsewhere.
 
 
 
