+
+\section{Miscellaneous functions and macros}\label{miscellany}
+
+
+\membersection{wxBase64Decode}\label{wxbase64decode}
+
+\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 wxString\& }{src},\\
+\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
+\param{size\_t }{*posErr = \NULL}}
+
+These function decode a Base64-encoded string. The first version is a raw
+decoding function and decodes the data into the provided buffer \arg{dst} of
+the given size \arg{dstLen}. An error is returned if the buffer is not large
+enough -- that is not at least \helpref{wxBase64DecodedSize(srcLen)}{wxbase64decodedsize}
+bytes. The second version allocates memory internally and returns it as
+\helpref{wxMemoryBuffer}{wxmemorybuffer} and is recommended for normal use.
+
+The first version returns the number of bytes written to the buffer or the
+necessary buffer size if \arg{dst} was \NULL or \texttt{wxCONV\_FAILED} on
+error, e.g. if the output buffer is too small or invalid characters were
+encountered in the input string. The second version returns a buffer with the
+base64 decoded binary equivalent of the input string. In neither case is the
+buffer NUL-terminated.
+
+\wxheading{Parameters}
+
+\docparam{dst}{Pointer to output buffer, may be \NULL to just compute the
+necessary buffer size.}
+
+\docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is
+\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
+computed by this function itself.}
+
+\docparam{mode}{This parameter specifies the function behaviour when invalid
+characters are encountered in input. By default, any such character stops the
+decoding with error. If the mode is wxBase64DecodeMode\_SkipWS, then the white
+space characters are silently skipped instead. And if it is
+wxBase64DecodeMode\_Relaxed, then all invalid characters are skipped.}
+
+\docparam{posErr}{If this pointer is non-\NULL and an error occurs during
+decoding, it is filled with the index of the invalid character.}
+
+\wxheading{Include files}
+
+<wx/base64.h>
+
+
+\membersection{wxBase64DecodedSize}\label{wxbase64decodedsize}
+
+\func{size\_t}{wxBase64DecodedSize}{\param{size\_t }{srcLen}}
+
+Returns the size of the buffer necessary to contain the data encoded in a
+base64 string of length \arg{srcLen}. This can be useful for allocating a
+buffer to be passed to \helpref{wxBase64Decode}{wxbase64decode}.
+
+
+\membersection{wxBase64Encode}\label{wxbase64encode}
+
+\func{size\_t}{wxBase64Encode}{\param{char *}{dst}, \param{size\_t }{dstLen},
+\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}}
+
+These functions encode the given data using base64. The first of them is the
+raw encoding function writing the output string into provided buffer while the
+other ones return the output as wxString. There is no error return for these
+functions except for the first one which returns \texttt{wxCONV\_FAILED} if the
+output buffer is too small. To allocate the buffer of the correct size, use
+\helpref{wxBase64EncodedSize}{wxbase64encodedsize} or call this function with
+\arg{dst} set to \NULL -- it will then return the necessary buffer size.
+
+\wxheading{Parameters}
+
+\docparam{dst}{The output buffer, may be \NULL to retrieve the needed buffer
+size.}
+
+\docparam{dstLen}{The output buffer size, ignored if \arg{dst} is \NULL.}
+
+\docparam{src}{The input buffer, must not be \NULL.}
+
+\docparam{srcLen}{The length of the input data.}
+
+\wxheading{Include files}
+
+<wx/base64.h>
+
+
+\membersection{wxBase64EncodedSize}\label{wxbase64encodedsize}
+
+\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
+to \helpref{wxBase64Encode}{wxbase64encode}.
+
+
+\membersection{wxCONCAT}\label{wxconcat}
+
+\func{}{wxCONCAT}{\param{}{x}, \param{}{y}}
+
+This macro returns the concatenation of two tokens \arg{x} and \arg{y}.
+
+
+\membersection{wxDECLARE\_APP}\label{wxdeclareapp}
+
+\func{}{wxDECLARE\_APP}{className}
+
+This is used in headers to create a forward declaration of the
+\helpref{wxGetApp}{wxgetapp} function implemented by
+\helpref{wxIMPLEMENT\_APP}{wximplementapp}. It creates the declaration
+{\tt className\& wxGetApp(void)}.
+
+Example:
+
+\begin{verbatim}
+ wxDECLARE_APP(MyApp)
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/app.h>
+
+
+\membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction}
+
+\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
+repeat this type twice if you want to declare and define a function pointer all
+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}
+\arg{dynlib}.
+
+\wxheading{Parameters}
+
+\docparam{type}{the type of the function}
+
+\docparam{name}{the name of the function to load, not a string (without quotes,
+it is quoted automatically by the macro)}
+
+\docparam{dynlib}{the library to load the function from}
+
+
+
+\membersection{wxDEPRECATED}\label{wxdeprecated}
+
+This macro can be used around a function declaration to generate warnings
+indicating that this function is deprecated (i.e. obsolete and planned to be
+removed in the future) when it is used. Only Visual C++ 7 and higher and g++
+compilers currently support this functionality.
+
+Example of use:
+\begin{verbatim}
+ // old function, use wxString version instead
+ wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
+
+ // ...
+ wxString wxGetSomething();
+\end{verbatim}
+
+
+\membersection{wxDEPRECATED\_BUT\_USED\_INTERNALLY}\label{wxdeprecatedbutusedinternally}
+
+This is a special version of \helpref{wxDEPRECATED}{wxdeprecated} macro which
+only does something when the deprecated function is used from the code outside
+wxWidgets itself but doesn't generate warnings when it is used from wxWidgets.
+It is used with the virtual functions which are called by the library itself --
+even if such function is deprecated the library still has to call it to ensure
+that the existing code overriding it continues to work, but the use of this
+macro ensures that a deprecation warning will be generated if this function is
+used from the user code or, in case of Visual C++, even when it is simply
+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
+the compiler supports it or nothing otherwise. Thus, it can be used even in the
+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}}
+
+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}
+
+<wx/utils.h>
+
+
+\membersection{wxLL}\label{wxll}
+
+\func{wxLongLong\_t}{wxLL}{\param{}{number}}
+
+This macro is defined for the platforms with a native 64 bit integer type and
+allows to define 64 bit compile time constants:
+
+\begin{verbatim}
+ #ifdef wxLongLong_t
+ wxLongLong_t ll = wxLL(0x1234567890abcdef);
+ #endif
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/longlong.h>
+
+\wxheading{See also}
+
+\helpref{wxULL}{wxull}, \helpref{wxLongLong}{wxlonglong}
+
+
+\membersection{wxLongLongFmtSpec}\label{wxlonglongfmtspec}
+
+This macro is defined to contain the {\tt printf()} format specifier using
+which 64 bit integer numbers (i.e. those of type {\tt wxLongLong\_t}) can be
+printed. Example of using it:
+
+\begin{verbatim}
+ #ifdef wxLongLong_t
+ wxLongLong_t ll = wxLL(0x1234567890abcdef);
+ printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
+ #endif
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxLL}{wxll}
+
+\wxheading{Include files}
+
+<wx/longlong.h>
+
projects / wxWidgets.git / blobdiff