Demonstrates printing

[wxWidgets.git] / docs / latex / wx / dynlib.tex

diff --git a/docs/latex/wx/dynlib.tex b/docs/latex/wx/dynlib.tex
index 61accb8f3d85cefc09240087ecb08414c38e9ba3..6c64a245ea124dc126fdabbc9d3810896ea8ff26 100644 (file)
--- a/docs/latex/wx/dynlib.tex
+++ b/docs/latex/wx/dynlib.tex
@@ -1,12 +1,12 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% Name:        dynlib.tex
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% Name:        dynlib.tex

-%% Purpose:     wxDynamicLibrary documentation
+%% Purpose:     wxDynamicLibrary and wxDynamicLibraryDetails documentation

 %% Author:      Vadim Zeitlin
 %% Modified by:
 %% Created:     14.01.02 (extracted from dllload.tex)
 %% RCS-ID:      $Id$
 %% Copyright:   (c) Vadim Zeitlin
 %% Author:      Vadim Zeitlin
 %% Modified by:
 %% Created:     14.01.02 (extracted from dllload.tex)
 %% RCS-ID:      $Id$
 %% Copyright:   (c) Vadim Zeitlin

-%% License:     wxWidgets license
+%% License:     wxWindows license

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary}


@@ -22,6 +22,17 @@ done in the objects destructor automatically.
 %
 %\helpref{wxDllLoader}{wxdllloader}
 
 %
 %\helpref{wxDllLoader}{wxdllloader}
 

+\wxheading{Derived from}
+
+No base class.
+
+\wxheading{Include files}
+
+<wx/dynlib.h>
+
+(only available if \texttt{wxUSE\_DYNLIB\_CLASS} is set to $1$)
+
+\latexignore{\rtfignore{\wxheading{Members}}}

 
 \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary}
 
 
 \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary}
 


@@ -31,9 +42,10 @@ done in the objects destructor automatically.
 
 Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}.
 
 
 Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}.
 

+

 \membersection{wxDynamicLibrary::CanonicalizeName}\label{wxdynamiclibrarycanonicalizename}
 
 \membersection{wxDynamicLibrary::CanonicalizeName}\label{wxdynamiclibrarycanonicalizename}
 

-\func{wxString}{CanonicalizeName}{\param{const wxString\& }{name}, \param{wxDynamicLibraryCategory}{ cat = wxDL\_LIBRARY}}
+\func{static wxString}{CanonicalizeName}{\param{const wxString\& }{name}, \param{wxDynamicLibraryCategory}{ cat = wxDL\_LIBRARY}}

 
 Returns the platform-specific full name for the library called \arg{name}. E.g.
 it adds a {\tt ".dll"} extension under Windows and {\tt "lib"} prefix and 
 
 Returns the platform-specific full name for the library called \arg{name}. E.g.
 it adds a {\tt ".dll"} extension under Windows and {\tt "lib"} prefix and 


@@ -51,9 +63,10 @@ The possible values for \arg{cat} are:
 \helpref{CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname}
 
 
 \helpref{CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname}
 
 

+

 \membersection{wxDynamicLibrary::CanonicalizePluginName}\label{wxdynamiclibrarycanonicalizepluginname}
 
 \membersection{wxDynamicLibrary::CanonicalizePluginName}\label{wxdynamiclibrarycanonicalizepluginname}
 

-\func{wxString}{CanonicalizePluginName}{\param{const wxString\& }{name}, \param{wxPluginCategory}{ cat = wxDL\_PLUGIN\_GUI}}
+\func{static wxString}{CanonicalizePluginName}{\param{const wxString\& }{name}, \param{wxPluginCategory}{ cat = wxDL\_PLUGIN\_GUI}}

 
 This function does the same thing as 
 \helpref{CanonicalizeName}{wxdynamiclibrarycanonicalizename} but for wxWidgets
 
 This function does the same thing as 
 \helpref{CanonicalizeName}{wxdynamiclibrarycanonicalizename} but for wxWidgets


@@ -68,17 +81,19 @@ The possible values for \arg{cat} are:
     \twocolitem{wxDL\_PLUGIN\_BASE}{plugin which only uses wxBase}
 \end{twocollist}
 
     \twocolitem{wxDL\_PLUGIN\_BASE}{plugin which only uses wxBase}
 \end{twocollist}
 

+

 \membersection{wxDynamicLibrary::Detach}\label{wxdynamiclibrarydetach}
 
 \func{wxDllType}{Detach}{\void}
 
 Detaches this object from its library handle, i.e. the object will not unload
 the library any longer in its destructor but it is now the callers
 \membersection{wxDynamicLibrary::Detach}\label{wxdynamiclibrarydetach}
 
 \func{wxDllType}{Detach}{\void}
 
 Detaches this object from its library handle, i.e. the object will not unload
 the library any longer in its destructor but it is now the callers

-responsability to do this using \helpref{Unload}{wxdynamiclibraryunload}.
+responsibility to do this using \helpref{Unload}{wxdynamiclibraryunload}.
+

 
 \membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol}
 
 
 \membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol}
 

-\constfunc{void*}{GetSymbol}{\param{const wxString\& }{name}}
+\constfunc{void *}{GetSymbol}{\param{const wxString\& }{name}}

 
 Returns pointer to symbol {\it name} in the library or NULL if the library
 contains no such symbol.
 
 Returns pointer to symbol {\it name} in the library or NULL if the library
 contains no such symbol.


@@ -87,12 +102,59 @@ contains no such symbol.
 
 \helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}
 
 
 \helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}
 

+
+\membersection{wxDynamicLibrary::GetSymbolAorW}\label{wxdynamiclibrarygetsymbolaorw}
+
+\constfunc{void *}{GetSymbolAorW}{\param{const wxString\& }{name}}
+
+This function is available only under Windows as it is only useful when
+dynamically loading symbols from standard Windows DLLs. Such functions have
+either \texttt{'A'} (in ANSI build) or \texttt{'W'} (in Unicode, or wide
+character build) suffix if they take string parameters. Using this function you
+can use just the base name of the function and the correct suffix is appende
+automatically depending on the current build. Otherwise, this method is
+identical to \helpref{GetSymbol}{wxdynamiclibrarygetsymbol}.
+
+
+\membersection{wxDynamicLibrary::GetProgramHandle}\label{wxdynamiclibrarygetprogramhandle}
+
+\func{static wxDllType}{GetProgramHandle}{\void}
+
+Return a valid handle for the main program itself or \texttt{NULL} if symbols
+from the main program can't be loaded on this platform.
+
+
+\membersection{wxDynamicLibrary::HasSymbol}\label{wxdynamiclibraryhassymbol}
+
+\constfunc{bool}{HasSymbol}{\param{const wxString\& }{name}}
+
+Returns \true if the symbol with the given \arg{name} is present in the dynamic
+library, \false otherwise. Unlike \helpref{GetSymbol}{wxdynamiclibrarygetsymbol},
+this function doesn't log an error message if the symbol is not found.
+
+\newsince{2.5.4}
+
+

 \membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded}
 
 \constfunc{bool}{IsLoaded}{\void}
 
 Returns \true if the library was successfully loaded, \false otherwise.
 
 \membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded}
 
 \constfunc{bool}{IsLoaded}{\void}
 
 Returns \true if the library was successfully loaded, \false otherwise.
 

+
+\membersection{wxDynamicLibrary::ListLoaded}\label{wxdynamiclibrarylistloaded}
+
+\func{static wxDynamicLibraryDetailsArray}{ListLoaded}{\void}
+
+This static method returns an \helpref{array}{wxarray} containing the details
+of all modules loaded into the address space of the current project, the array
+elements are object of \texttt{wxDynamicLibraryDetails} class. The array will
+be empty if an error occurred.
+
+This method is currently implemented only under Win32 and Linux and is useful
+mostly for diagnostics purposes.
+
+

 \membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload}
 
 \func{bool}{Load}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}
 \membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload}
 
 \func{bool}{Load}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}


@@ -106,10 +168,12 @@ be a combination of the following bits:
 \twocolitem{wxDL\_GLOBAL}{equivalent of RTLD\_GLOBAL under Unix, ignored elsewhere}
 \twocolitem{wxDL\_VERBATIM}{don't try to append the appropriate extension to
 the library name (this is done by default).}
 \twocolitem{wxDL\_GLOBAL}{equivalent of RTLD\_GLOBAL under Unix, ignored elsewhere}
 \twocolitem{wxDL\_VERBATIM}{don't try to append the appropriate extension to
 the library name (this is done by default).}

+\twocolitem{wxDL\_DEFAULT}{default flags, same as wxDL\_NOW currently}

 \end{twocollist}
 
 Returns \true if the library was successfully loaded, \false otherwise.
 
 \end{twocollist}
 
 Returns \true if the library was successfully loaded, \false otherwise.
 

+

 \membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload}
 
 \func{void}{Unload}{\void}
 \membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload}
 
 \func{void}{Unload}{\void}


@@ -124,3 +188,70 @@ during a longer period of time than the scope of the wxDynamicLibrary object.
 In this case you may call \helpref{Detach}{wxdynamiclibrarydetach} and store
 the handle somewhere and call this static method later to unload it.
 
 In this case you may call \helpref{Detach}{wxdynamiclibrarydetach} and store
 the handle somewhere and call this static method later to unload it.
 

+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxDynamicLibraryDetails}}\label{wxdynamiclibrarydetails}
+
+This class is used for the objects returned by 
+\helpref{wxDynamicLibrary::ListLoaded}{wxdynamiclibrarylistloaded} method and
+contains the information about a single module loaded into the address space of
+the current process. A module in this context may be either a dynamic library
+or the main program itself.
+
+\wxheading{Derived from}
+
+No base class.
+
+\wxheading{Include files}
+
+<wx/dynlib.h>
+
+(only available if \texttt{wxUSE\_DYNLIB\_CLASS} is set to $1$)
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDynamicLibraryDetails::GetName}\label{wxdynamiclibrarygetname}
+
+\constfunc{wxString}{GetName}{\void}
+
+Returns the base name of this module, e.g. \texttt{kernel32.dll} or 
+\texttt{libc-2.3.2.so}.
+
+
+\membersection{wxDynamicLibraryDetails::GetPath}\label{wxdynamiclibrarygetpath}
+
+\constfunc{wxString}{GetPath}{\void}
+
+Returns the full path of this module if available, e.g. 
+\texttt{c:$\backslash$windows$\backslash$system32$\backslash$kernel32.dll} or 
+\texttt{/lib/libc-2.3.2.so}.
+
+
+\membersection{wxDynamicLibraryDetails::GetAddress}\label{wxdynamiclibrarygetaddress}
+
+\constfunc{bool}{GetAddress}{\param{void **}{addr}, \param{size\_t }{*len}}
+
+Retrieves the load address and the size of this module.
+
+\wxheading{Parameters}
+
+\docparam{addr}{the pointer to the location to return load address in, may be
+\texttt{NULL}}
+
+\docparam{len}{pointer to the location to return the size of this module in
+memory in, may be \texttt{NULL}}
+
+\wxheading{Return value}
+
+\true if the load address and module size were retrieved, \false if this
+information is not available.
+
+
+\membersection{wxDynamicLibraryDetails::GetVersion}\label{wxdynamiclibrarygetversion}
+
+\constfunc{wxString}{GetVersion}{\void}
+
+Returns the version of this module, e.g. \texttt{5.2.3790.0} or 
+\texttt{2.3.2}. The returned string is empty if the version information is not
+available.
+