]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/function.tex
added wxMessageQueue class for inter-thread communications
[wxWidgets.git] / docs / latex / wx / function.tex
index 39d4e61b67c57a0759e54cec79eddf089eefac1b..b3230a5d8e4d09273994ae0de12710e4f77f8338 100644 (file)
@@ -76,6 +76,7 @@ the corresponding topic.
 \helpref{WXDEBUG\_NEW}{debugnew}\\
 \helpref{wxDEPRECATED}{wxdeprecated}\\
 \helpref{wxDEPRECATED\_BUT\_USED\_INTERNALLY}{wxdeprecatedbutusedinternally}\\
 \helpref{WXDEBUG\_NEW}{debugnew}\\
 \helpref{wxDEPRECATED}{wxdeprecated}\\
 \helpref{wxDEPRECATED\_BUT\_USED\_INTERNALLY}{wxdeprecatedbutusedinternally}\\
+\helpref{wxDEPRECATED\_INLINE}{wxdeprecatedinline}\\
 \helpref{wxDirExists}{functionwxdirexists}\\
 \helpref{wxDirSelector}{wxdirselector}\\
 \helpref{wxDisplayDepth}{wxdisplaydepth}\\
 \helpref{wxDirExists}{functionwxdirexists}\\
 \helpref{wxDirSelector}{wxdirselector}\\
 \helpref{wxDisplayDepth}{wxdisplaydepth}\\
@@ -1570,11 +1571,14 @@ that there isn't always a standard way to do a reliable check on the OS architec
 
 \membersection{::wxGetUserHome}\label{wxgetuserhome}
 
 
 \membersection{::wxGetUserHome}\label{wxgetuserhome}
 
-\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
+\func{wxString}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
 
 
-Returns the home directory for the given user. If the username is empty
-(default value), this function behaves like
-\helpref{wxGetHomeDir}{wxgethomedir}.
+Returns the home directory for the given user. If the \arg{user} is empty
+(default value), this function behaves like 
+\helpref{wxGetHomeDir}{wxgethomedir} i.e. returns the current user home
+directory.
+
+If the home directory couldn't be determined, an empty string is returned.
 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 
@@ -1801,11 +1805,9 @@ 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
 \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 (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).
+value of its argument.
 
 
-However it does have a purpose and it is to mark the literal strings for the
+However it does have a purpose which 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 a
 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 a
@@ -1820,7 +1822,7 @@ translated (note that it is a bad example, really, as
 day names already). If you write
 
 \begin{verbatim}
 day names already). If you write
 
 \begin{verbatim}
-static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
+static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 ...
 // use weekdays[n] as usual
 \end{verbatim}
 ...
 // use weekdays[n] as usual
 \end{verbatim}
@@ -1829,7 +1831,7 @@ the code wouldn't compile because the function calls are forbidden in the array
 initializer. So instead you should do
 
 \begin{verbatim}
 initializer. So instead you should do
 
 \begin{verbatim}
-static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
+static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
 ...
 // use wxGetTranslation(weekdays[n])
 \end{verbatim}
 ...
 // use wxGetTranslation(weekdays[n])
 \end{verbatim}
@@ -1841,6 +1843,7 @@ 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.
 
 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}}
 \membersection{::wxVsnprintf}\label{wxvsnprintf}
 
 \func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
@@ -1959,6 +1962,8 @@ See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
 
 Ring the system bell.
 
 
 Ring the system bell.
 
+Note that this function is categorized as a GUI one and so is not thread-safe.
+
 \wxheading{Include files}
 
 <wx/utils.h>
 \wxheading{Include files}
 
 <wx/utils.h>
@@ -2843,13 +2848,18 @@ The clipboard must have previously been opened for this call to succeed.
 
 \membersection{wxBase64Decode}\label{wxbase64decode}
 
 
 \membersection{wxBase64Decode}\label{wxbase64decode}
 
-\func{size\_t}{wxBase64Decode}{\param{void *}{dst}, \param{size\_t}{dstLen},\\
+\func{size\_t}{wxBase64Decode}{\param{void *}{dst}, \param{size\_t }{dstLen}, 
+\param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN}, 
+\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict}, 
+\param{size\_t }{*posErr = \NULL}}
+
+\func{wxMemoryBuffer}{wxBase64Decode}{\\
 \param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN},\\
 \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
 \param{size\_t }{*posErr = \NULL}}
 
 \func{wxMemoryBuffer}{wxBase64Decode}{\\
 \param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN},\\
 \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
 \param{size\_t }{*posErr = \NULL}}
 
 \func{wxMemoryBuffer}{wxBase64Decode}{\\
-\param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN},\\
+\param{const wxString\& }{src},\\
 \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
 \param{size\_t }{*posErr = \NULL}}
 
 \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
 \param{size\_t }{*posErr = \NULL}}
 
@@ -2875,7 +2885,8 @@ necessary buffer size.}
 \docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is
 \NULL.}
 
 \docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is
 \NULL.}
 
-\docparam{src}{The input string, must not be \NULL.}
+\docparam{src}{The input string, must not be \NULL. For the version using
+wxString, the input string should contain only ASCII characters.}
 
 \docparam{srcLen}{The length of the input string or special value
 \texttt{wxNO\_LEN} if the string is \NUL-terminated and the length should be
 
 \docparam{srcLen}{The length of the input string or special value
 \texttt{wxNO\_LEN} if the string is \NUL-terminated and the length should be
@@ -2906,10 +2917,10 @@ buffer to be passed to \helpref{wxBase64Decode}{wxbase64decode}.
 
 \membersection{wxBase64Encode}\label{wxbase64encode}
 
 
 \membersection{wxBase64Encode}\label{wxbase64encode}
 
-\func{size\_t}{wxBase64Encode}{\param{char *}{dst}, \param{size\_t}{dstLen},\\
+\func{size\_t}{wxBase64Encode}{\param{char *}{dst}, \param{size\_t }{dstLen}, 
 \param{const void *}{src}, \param{size\_t }{srcLen}}
 
 \param{const void *}{src}, \param{size\_t }{srcLen}}
 
-\func{wxString}{wxBase64Encode}{\param{const void *}{src}, \param{size\_t}{srcLen}}
+\func{wxString}{wxBase64Encode}{\param{const void *}{src}, \param{size\_t }{srcLen}}
 
 \func{wxString}{wxBase64Encode}{\param{const wxMemoryBuffer\& }{buf}}
 
 
 \func{wxString}{wxBase64Encode}{\param{const wxMemoryBuffer\& }{buf}}
 
@@ -2939,7 +2950,7 @@ size.}
 
 \membersection{wxBase64EncodedSize}\label{wxbase64encodedsize}
 
 
 \membersection{wxBase64EncodedSize}\label{wxbase64encodedsize}
 
-\func{size\_t}{wxBase64EncodedSize}{\param{size\_t}{len}}
+\func{size\_t}{wxBase64EncodedSize}{\param{size\_t }{len}}
 
 Returns the length of the string with base64 representation of a buffer of
 specified size \arg{len}. This can be useful for allocating the buffer passed
 
 Returns the length of the string with base64 representation of a buffer of
 specified size \arg{len}. This can be useful for allocating the buffer passed
@@ -3009,6 +3020,25 @@ used from the user code or, in case of Visual C++, even when it is simply
 overridden.
 
 
 overridden.
 
 
+\membersection{wxDEPRECATED\_INLINE}\label{wxdeprecatedinline}
+
+\func{}{wxDEPRECATED\_INLINE}{\param{}{func}, \param{}{body}}
+
+This macro is similar to \helpref{wxDEPRECATED}{wxdeprecated} but can be used
+to not only declare the function \arg{func} as deprecated but to also provide
+its (inline) implementation \arg{body}.
+
+It can be used as following:
+\begin{verbatim}
+    class wxFoo
+    {
+    public:
+        // OldMethod() is deprecated, use NewMethod() instead
+        void NewMethod();
+        wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
+    };
+\end{verbatim}
+
 \membersection{wxEXPLICIT}\label{wxexplicit}
 
 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if
 \membersection{wxEXPLICIT}\label{wxexplicit}
 
 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if
@@ -3100,7 +3130,9 @@ Generates an integer identifier unique to this run of the program.
 \membersection{wxON\_BLOCK\_EXIT}\label{wxonblockexit}
 
 \func{}{wxON\_BLOCK\_EXIT0}{\param{}{func}}
 \membersection{wxON\_BLOCK\_EXIT}\label{wxonblockexit}
 
 \func{}{wxON\_BLOCK\_EXIT0}{\param{}{func}}
+
 \func{}{wxON\_BLOCK\_EXIT1}{\param{}{func}, \param{}{p1}}
 \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}
 \func{}{wxON\_BLOCK\_EXIT2}{\param{}{func}, \param{}{p1}, \param{}{p2}}
 
 This family of macros allows to ensure that the global function \arg{func}
@@ -3128,7 +3160,9 @@ details.
 \membersection{wxON\_BLOCK\_EXIT\_OBJ}\label{wxonblockexitobj}
 
 \func{}{wxON\_BLOCK\_EXIT\_OBJ0}{\param{}{obj}, \param{}{method}}
 \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\_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}
 \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}
@@ -3257,6 +3291,18 @@ Find the deepest window at the mouse pointer position, returning the window
 and current pointer position in screen coordinates.
 
 
 and current pointer position in screen coordinates.
 
 
+\membersection{wxFromString}\label{wxfromstring}
+
+\func{bool}{wxFromString}{\param{const wxString\& }{str},
+                           \param{wxColour* }{col}}
+
+\func{bool}{wxFromString}{\param{const wxString\& }{str},
+                           \param{wxFont* }{col}}
+
+Converts string to the type of the second argument. Returns \true on success.
+See also: \helpref{wxToString}{wxtostring}.
+
+
 \membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
 
 \func{wxWindow *}{wxGetActiveWindow}{\void}
 \membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
 
 \func{wxWindow *}{wxGetActiveWindow}{\void}
@@ -3326,7 +3372,7 @@ Returns the mouse position in screen coordinates.
 
 Returns the current state of the mouse.  Returns a wxMouseState
 instance that contains the current position of the mouse pointer in
 
 Returns the current state of the mouse.  Returns a wxMouseState
 instance that contains the current position of the mouse pointer in
-screen coordinants, as well as boolean values indicating the up/down
+screen coordinates, as well as boolean values indicating the up/down
 status of the mouse buttons and the modifier keys.
 
 \wxheading{Include files}
 status of the mouse buttons and the modifier keys.
 
 \wxheading{Include files}
@@ -3381,8 +3427,8 @@ Returns label that should be used for given {\it id} element.
 \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;
 \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}
+useful for getting labels without accelerator char code like for toolbar tooltip or
+on platforms without traditional keyboard like smartphones}
 
 \docparam{accelerator}{optional accelerator string automatically added to label; useful
 for building labels for \helpref{wxMenuItem}{wxmenuitem}}
 
 \docparam{accelerator}{optional accelerator string automatically added to label; useful
 for building labels for \helpref{wxMenuItem}{wxmenuitem}}
@@ -3572,6 +3618,16 @@ class name internally. Example of using the macro:
 Notice that there should be no semicolon after this macro.
 
 
 Notice that there should be no semicolon after this macro.
 
 
+\membersection{wxToString}\label{wxtostring}
+
+\func{wxString}{wxToString}{\param{const wxColour\& }{col}}
+
+\func{wxString}{wxToString}{\param{const wxFont\& }{col}}
+
+Converts its argument to string.
+See also: \helpref{wxFromString}{wxfromstring}.
+
+
 \membersection{wxULL}\label{wxull}
 
 \func{wxLongLong\_t}{wxULL}{\param{}{number}}
 \membersection{wxULL}\label{wxull}
 
 \func{wxLongLong\_t}{wxULL}{\param{}{number}}