X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bc253a97e78b2c42b93c1f3cc8e1bcceec68a336..733a25f0f454eefbb1392faad986d8dde7919230:/docs/latex/wx/function.tex

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index 2358699e70..5d553b30d0 100644
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -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}\\
@@ -39,6 +38,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}\\
@@ -109,6 +109,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 +175,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}\\
@@ -181,6 +184,7 @@ the corresponding topic.
 \helpref{wxNow}{wxnow}\\
 \helpref{wxOnAssert}{wxonassert}\\
 \helpref{wxOpenClipboard}{wxopenclipboard}\\
+\helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\
 \helpref{wxPathOnly}{wxpathonly}\\
 \helpref{wxPostDelete}{wxpostdelete}\\
 \helpref{wxPostEvent}{wxpostevent}\\
@@ -250,6 +254,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
@@ -260,11 +266,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}
 
 <wx/version.h> or <wx/defs.h>
 
 
+\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}}
@@ -288,13 +306,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}
@@ -1078,7 +1095,7 @@ Returns true if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatc
 
 \func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
 
-Returns true if the {\it pattern}\/ matches the {\it text}\/; if {\it
+Returns true if the \arg{pattern}\/ matches the {\it text}\/; if {\it
 dot\_special}\/ is true, filenames beginning with a dot are not matched
 with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
 
@@ -1087,24 +1104,38 @@ with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
 
 \func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
 
-Makes the directory {\it dir}, returning true if successful.
+Makes the directory \arg{dir}, returning true if successful.
 
 {\it perm} is the access mask for the directory for the systems on which it is
 supported (Unix) and doesn't have effect for the other ones.
 
 
+\membersection{::wxParseCommonDialogsFilter}\label{wxparsecommondialogsfilter}
+
+\func{int}{wxParseCommonDialogsFilter}{\param{const wxString\& }{wildCard}, \param{wxArrayString\& }{descriptions}, \param{wxArrayString\& }{filters}}
+
+Parses the \arg{wildCard}, returning the number of filters.
+Returns 0 if none or if there's a problem.
+The arrays will contain an equal number of items found before the error.
+On platforms where native dialogs handle only one filter per entry,
+entries in arrays are automatically adjusted.
+\arg{wildCard} is in the form:
+\begin{verbatim}
+ "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
+\end{verbatim}
+
 \membersection{::wxRemoveFile}\label{wxremovefile}
 
 \func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
 
-Removes {\it file}, returning true if successful.
+Removes \arg{file}, returning true if successful.
 
 
 \membersection{::wxRenameFile}\label{wxrenamefile}
 
 \func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
 
-Renames {\it file1} to {\it file2}, returning true if successful.
+Renames \arg{file1} to \arg{file2}, returning true if successful.
 
 
 \membersection{::wxRmdir}\label{wxrmdir}
@@ -1393,22 +1424,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}}
@@ -1432,10 +1447,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}}
@@ -1544,21 +1560,21 @@ build. In fact, its definition is:
 \func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}}
 
 This macro doesn't do anything in the program code -- it simply expands to the
-value of its argument (expand in Unicode build where it is equivalent to 
+value of its argument (except in Unicode build where it is equivalent to 
 \helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT
 with the same string which would be really unreadable).
 
 However it does have a purpose and it is to mark the literal strings for the
 extraction into the message catalog created by {\tt xgettext} program. Usually
 this is achieved using \helpref{\_()}{underscore} but that macro not only marks
-the string for extraction but also expands into 
+the string for extraction but also expands into a 
 \helpref{wxGetTranslation}{wxgettranslation} function call which means that it
-cannot be used in some situations, notably for the static arrays
+cannot be used in some situations, notably for static array
 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
 
@@ -1584,8 +1600,6 @@ wxTRANSLATE() in the above, it wouldn't work as expected because there would be
 no translations for the weekday names in the program message catalog and
 wxGetTranslation wouldn't find them.
 
-
-
 \membersection{::wxVsnprintf}\label{wxvsnprintf}
 
 \func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
@@ -1610,11 +1624,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}
 
@@ -1729,7 +1738,7 @@ If path is empty, the current directory will be used. If filename is empty,
 no default filename will be supplied. The wildcard determines what files
 are displayed in the file selector, and file extension supplies a type
 extension for the required filename. Flags may be a combination of wxOPEN,
-wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, wxFILE\_MUST\_EXIST, wxMULTIPLE or 0.
+wxSAVE, wxOVERWRITE\_PROMPT, wxFILE\_MUST\_EXIST, wxMULTIPLE or 0.
 
 Both the Unix and Windows versions implement a wildcard filter. Typing a
 filename containing wildcards (*, ?) in the filename text item, and
@@ -2555,7 +2564,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 
-\tt{void *} pointer to the correct type and, even more annoyingly, you have to
+{\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
 
@@ -2584,6 +2593,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}
+
+<wx/utils.h>
+
+
 \membersection{wxLL}\label{wxll}
 
 \func{wxLongLong\_t}{wxLL}{\param{}{number}}
@@ -3837,6 +3859,33 @@ Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
 <wx/timer.h>
 
 
+\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}
+
+<wx/utils.h>
+
+
+\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}
+
+<wx/utils.h>
+
+
 \membersection{::wxNow}\label{wxnow}
 
 \func{wxString}{wxNow}{\void}
@@ -3876,13 +3925,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}
-
-<wx/utils.h>
+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.
 
 
 
