added Unload(handle); updated the docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@22578 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/dynlib.tex

@@ -12,48 +12,70 @@
 \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary}
 
 wxDynamicLibrary is a class representing dynamically loadable library
-(Windows DLL, shared library under Unix etc.). It is implemented as a wrapper
-to \helpref{wxDllLoader}{wxdllloader}.
+(Windows DLL, shared library under Unix etc.). Just create an object of
+this class to load a library and don't worry about unloading it -- it will be
+done in the objects destructor automatically.
 
-\wxheading{See also}
+% deprecated now...
+%
+%\wxheading{See also}
+%
+%\helpref{wxDllLoader}{wxdllloader}
 
-\helpref{wxDllLoader}{wxdllloader}
 
 \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary}
 
 \func{}{wxDynamicLibrary}{\void}
 
-\func{}{wxDynamicLibrary}{\param{const wxString\& }{name}}
+\func{}{wxDynamicLibrary}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}
 
 Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}.
 
+
+\membersection{wxDynamicLibrary::CanonicalizeName}\label{wxdynamiclibrarycanonicalizename}
+
+\func{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 
+{\tt ".so"}, {\tt ".sl"} or maybe {\tt ".dylib"} extension under Unix.
+
+The possible values for \arg{cat} are:
+\begin{twocollist}
+    \twocolitem{wxDL\_LIBRARY}{normal library}
+    \twocolitem{wxDL\_MODULE}{a loadable module or plugin}
+\end{twocollist}
+
+\wxheading{See also}
+
+\helpref{CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname}
+
+
+\membersection{wxDynamicLibrary::CanonicalizePluginName}\label{wxdynamiclibrarycanonicalizepluginname}
+
+\func{wxString}{CanonicalizePluginName}{\param{const wxString\& }{name}, \param{wxPluginCategory cat = wxDL\_PLUGIN\_GUI}}
+
+This function does the same thing as 
+\helpref{CanonicalizeName}{wxdynamiclibrarycanonicalizename} but for wxWindows
+plugins. The only difference is that compiler and version information are added
+to the name to ensure that the plugin which is going to be loaded will be
+compatible with the main program.
+
+The possible values for \arg{cat} are:
+\begin{twocollist}
+    \twocolitem{wxDL\_PLUGIN\_GUI}{plugin which uses GUI classes (default)}
+    \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
-responsability to do this.
+responsability to do this using \helpref{Unload}{wxdynamiclibraryunload}.
 
-\membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded}
-
-\constfunc{bool}{IsLoaded}{\void}
-
-Returns true if the library was successfully loaded, false otherwise.
-
-\membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload}
-
-\func{bool}{Load}{\param{const wxString\& }{name}}
-
-Loads DLL into memory.
-
-Returns true if the library was successfully loaded, false otherwise.
-
-\membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload}
-
-\func{void}{Unload}{\void}
-
-Unloads the library from memory.
 
 \membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol}
 
@@ -66,3 +88,46 @@ contains no such symbol.
 
 \helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}
 
+
+\membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded}
+
+\constfunc{bool}{IsLoaded}{\void}
+
+Returns \true if the library was successfully loaded, \false otherwise.
+
+
+\membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload}
+
+\func{bool}{Load}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}
+
+Loads DLL with the given \arg{name} into memory. The \arg{flags} argument can
+be a combination of the following bits:
+\begin{twocollist}
+\twocolitem{wxDL\_LAZY}{equivalent of RTLD\_LAZY under Unix, ignored elsewhere}
+\twocolitem{wxDL\_NOW}{equivalent of RTLD\_NOW under Unix, ignored elsewhere}
+\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).}
+\end{twocollist}
+
+Returns \true if the library was successfully loaded, \false otherwise.
+
+\wxheading{See also}
+
+\helpref{}{}
+
+
+\membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload}
+
+\func{void}{Unload}{\void}
+
+\func{static void}{Unload}{\param{wxDllType }{handle}}
+
+Unloads the library from memory. wxDynamicLibrary object automatically calls
+this method from its destructor if it had been successfully loaded.
+
+The second version is only used if you need to keep the library in memory
+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.
+

include/wx/dynlib.h

@@ -141,8 +141,11 @@ public:
     // doing this
     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 
+    // unload the given library handle (presumably returned by Detach() before)
+    static void Unload(wxDllType handle);
+
     // unload the library, also done automatically in dtor
-    void Unload();
+    void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } }
 
     // Return the raw handle from dlopen and friends.
     wxDllType GetLibHandle() const { return m_handle; }
@@ -168,8 +171,9 @@ public:
 
     // return name of wxWindows plugin (adds compiler and version info
     // to the filename):
-    static wxString CanonicalizePluginName(const wxString& name,
-                                           wxPluginCategory cat);
+    static wxString
+    CanonicalizePluginName(const wxString& name,
+                           wxPluginCategory cat = wxDL_PLUGIN_GUI);
 
     // return plugin directory on platforms where it makes sense and empty
     // string on others: