| 1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 2 | %% Name: dynlib.tex |
| 3 | %% Purpose: wxDynamicLibrary documentation |
| 4 | %% Author: Vadim Zeitlin |
| 5 | %% Modified by: |
| 6 | %% Created: 14.01.02 (extracted from dllload.tex) |
| 7 | %% RCS-ID: $Id$ |
| 8 | %% Copyright: (c) Vadim Zeitlin |
| 9 | %% License: wxWindows license |
| 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 11 | |
| 12 | \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary} |
| 13 | |
| 14 | wxDynamicLibrary is a class representing dynamically loadable library |
| 15 | (Windows DLL, shared library under Unix etc.). Just create an object of |
| 16 | this class to load a library and don't worry about unloading it -- it will be |
| 17 | done in the objects destructor automatically. |
| 18 | |
| 19 | % deprecated now... |
| 20 | % |
| 21 | %\wxheading{See also} |
| 22 | % |
| 23 | %\helpref{wxDllLoader}{wxdllloader} |
| 24 | |
| 25 | |
| 26 | \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary} |
| 27 | |
| 28 | \func{}{wxDynamicLibrary}{\void} |
| 29 | |
| 30 | \func{}{wxDynamicLibrary}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}} |
| 31 | |
| 32 | Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}. |
| 33 | |
| 34 | \membersection{wxDynamicLibrary::CanonicalizeName}\label{wxdynamiclibrarycanonicalizename} |
| 35 | |
| 36 | \func{wxString}{CanonicalizeName}{\param{const wxString\& }{name}, \param{wxDynamicLibraryCategory}{ cat = wxDL\_LIBRARY}} |
| 37 | |
| 38 | Returns the platform-specific full name for the library called \arg{name}. E.g. |
| 39 | it adds a {\tt ".dll"} extension under Windows and {\tt "lib"} prefix and |
| 40 | {\tt ".so"}, {\tt ".sl"} or maybe {\tt ".dylib"} extension under Unix. |
| 41 | |
| 42 | The possible values for \arg{cat} are: |
| 43 | |
| 44 | \begin{twocollist} |
| 45 | \twocolitem{wxDL\_LIBRARY}{normal library} |
| 46 | \twocolitem{wxDL\_MODULE}{a loadable module or plugin} |
| 47 | \end{twocollist} |
| 48 | |
| 49 | \wxheading{See also} |
| 50 | |
| 51 | \helpref{CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname} |
| 52 | |
| 53 | |
| 54 | \membersection{wxDynamicLibrary::CanonicalizePluginName}\label{wxdynamiclibrarycanonicalizepluginname} |
| 55 | |
| 56 | \func{wxString}{CanonicalizePluginName}{\param{const wxString\& }{name}, \param{wxPluginCategory}{ cat = wxDL\_PLUGIN\_GUI}} |
| 57 | |
| 58 | This function does the same thing as |
| 59 | \helpref{CanonicalizeName}{wxdynamiclibrarycanonicalizename} but for wxWindows |
| 60 | plugins. The only difference is that compiler and version information are added |
| 61 | to the name to ensure that the plugin which is going to be loaded will be |
| 62 | compatible with the main program. |
| 63 | |
| 64 | The possible values for \arg{cat} are: |
| 65 | |
| 66 | \begin{twocollist} |
| 67 | \twocolitem{wxDL\_PLUGIN\_GUI}{plugin which uses GUI classes (default)} |
| 68 | \twocolitem{wxDL\_PLUGIN\_BASE}{plugin which only uses wxBase} |
| 69 | \end{twocollist} |
| 70 | |
| 71 | \membersection{wxDynamicLibrary::Detach}\label{wxdynamiclibrarydetach} |
| 72 | |
| 73 | \func{wxDllType}{Detach}{\void} |
| 74 | |
| 75 | Detaches this object from its library handle, i.e. the object will not unload |
| 76 | the library any longer in its destructor but it is now the callers |
| 77 | responsability to do this using \helpref{Unload}{wxdynamiclibraryunload}. |
| 78 | |
| 79 | \membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol} |
| 80 | |
| 81 | \constfunc{void*}{GetSymbol}{\param{const wxString\& }{name}} |
| 82 | |
| 83 | Returns pointer to symbol {\it name} in the library or NULL if the library |
| 84 | contains no such symbol. |
| 85 | |
| 86 | \wxheading{See also} |
| 87 | |
| 88 | \helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction} |
| 89 | |
| 90 | \membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded} |
| 91 | |
| 92 | \constfunc{bool}{IsLoaded}{\void} |
| 93 | |
| 94 | Returns \true if the library was successfully loaded, \false otherwise. |
| 95 | |
| 96 | \membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload} |
| 97 | |
| 98 | \func{bool}{Load}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}} |
| 99 | |
| 100 | Loads DLL with the given \arg{name} into memory. The \arg{flags} argument can |
| 101 | be a combination of the following bits: |
| 102 | \begin{twocollist} |
| 103 | \twocolitem{wxDL\_LAZY}{equivalent of RTLD\_LAZY under Unix, ignored elsewhere} |
| 104 | \twocolitem{wxDL\_NOW}{equivalent of RTLD\_NOW under Unix, ignored elsewhere} |
| 105 | \twocolitem{wxDL\_GLOBAL}{equivalent of RTLD\_GLOBAL under Unix, ignored elsewhere} |
| 106 | \twocolitem{wxDL\_VERBATIM}{don't try to append the appropriate extension to |
| 107 | the library name (this is done by default).} |
| 108 | \end{twocollist} |
| 109 | |
| 110 | Returns \true if the library was successfully loaded, \false otherwise. |
| 111 | |
| 112 | \membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload} |
| 113 | |
| 114 | \func{void}{Unload}{\void} |
| 115 | |
| 116 | \func{static void}{Unload}{\param{wxDllType }{handle}} |
| 117 | |
| 118 | Unloads the library from memory. wxDynamicLibrary object automatically calls |
| 119 | this method from its destructor if it had been successfully loaded. |
| 120 | |
| 121 | The second version is only used if you need to keep the library in memory |
| 122 | during a longer period of time than the scope of the wxDynamicLibrary object. |
| 123 | In this case you may call \helpref{Detach}{wxdynamiclibrarydetach} and store |
| 124 | the handle somewhere and call this static method later to unload it. |
| 125 | |