added and documented wxDYNLIB_FUNCTION

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

docs/latex/wx/dynlib.tex

@@ -62,4 +62,7 @@ Unloads the library from memory.
 Returns pointer to symbol {\it name} in the library or NULL if the library
 contains no such symbol.
 
+\wxheading{See also}
+
+\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}
 

docs/latex/wx/function.tex

@@ -65,6 +65,7 @@ the corresponding topic.
 \helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
 \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
 \helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}\\
 \helpref{wxEmptyClipboard}{wxemptyclipboard}\\
 \helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\
 \helpref{wxEndBusyCursor}{wxendbusycursor}\\
@@ -2354,8 +2355,34 @@ Passes data to the clipboard.
 
 The clipboard must have previously been opened for this call to succeed.
 
+
 \section{Miscellaneous functions}\label{miscellany}
 
+\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{wxEXPLICIT}\label{wxexplicit}
 
 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if

include/wx/dynlib.h

@@ -38,7 +38,6 @@
 
 // Note: WXPM/EMX has to be tested first, since we want to use
 // native version, even if configure detected presence of DLOPEN.
-
 #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
     typedef HMODULE             wxDllType;
 #elif defined(HAVE_DLOPEN)
@@ -55,16 +54,9 @@ typedef CFragConnectionID   wxDllType;
     #error "Dynamic Loading classes can't be compiled on this platform, sorry."
 #endif
 
-
+// ----------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
+// constants
-// wxDynamicLibrary
+// ----------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-
-//FIXME:  This class isn't really common at all, it should be moved
-//        into platform dependent files.
-
-// NOTE: this class is (deliberately) not virtual, do not attempt
-//       to use it polymorphically.
 
 enum wxDLFlags
 {
@@ -98,17 +90,33 @@ enum wxPluginCategory
     wxDL_PLUGIN_BASE,   // wxBase-only plugin
 };
 
+// ----------------------------------------------------------------------------
+// macros
+// ----------------------------------------------------------------------------
+
+// when loading a function from a DLL you always have to cast the returned
+// "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
+// called "pfn<name>" initialized with the "name" from the "dynlib"
+#define wxDYNLIB_FUNCTION(type, name, dynlib) \
+    type pfn ## name = (type)(dynlib).GetSymbol(_T(#name))
+
+// ---------------------------------------------------------------------------
+// wxDynamicLibrary
+// ---------------------------------------------------------------------------
 
 class WXDLLIMPEXP_BASE wxDynamicLibrary
 {
 public:
-        // return a valid handle for the main program itself or NULL if
+    // return a valid handle for the main program itself or NULL if back
-        // back linking is not supported by the current platform (e.g. Win32)
+    // linking is not supported by the current platform (e.g. Win32)
-
     static wxDllType         GetProgramHandle();
 
     // return the platform standard DLL extension (with leading dot)
-
     static const wxChar *GetDllExt() { return ms_dllext; }
 
     wxDynamicLibrary() : m_handle(0) { }
@@ -117,47 +125,41 @@ public:
     {
         Load(libname, flags);
     }
+
+    // NOTE: this class is (deliberately) not virtual, do not attempt
+    //       to use it polymorphically.
     ~wxDynamicLibrary() { Unload(); }
 
     // return TRUE if the library was loaded successfully
-
     bool IsLoaded() const { return m_handle != 0; }
 
-        // load the library with the given name
+    // load the library with the given name (full or not), return true if ok
-        // (full or not), return TRUE on success
-
     bool Load(wxString libname, int flags = wxDL_DEFAULT);
 
-        // detach the library object from its handle, i.e. prevent the object
+    // detach the library object from its handle, i.e. prevent the object from
-        // from unloading the library in its dtor -- the caller is now
+    // unloading the library in its dtor -- the caller is now responsible for
-        // responsible for doing this
+    // doing this
     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 
     // unload the library, also done automatically in dtor
-
     void Unload();
 
     // Return the raw handle from dlopen and friends.
-
     wxDllType GetLibHandle() const { return m_handle; }
 
-        // resolve a symbol in a loaded DLL, such as a variable or function
+    // resolve a symbol in a loaded DLL, such as a variable or function name.
-        // name.  'name' is the (possibly mangled) name of the symbol.
+    // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to
-        // (use extern "C" to export unmangled names)
+    // export unmangled names)
     //
-        // Since it is perfectly valid for the returned symbol to actually be
+    // Since it is perfectly valid for the returned symbol to actually be NULL,
-        // NULL, that is not always indication of an error.  Pass and test the
+    // that is not always indication of an error.  Pass and test the parameter
-        // parameter 'success' for a true indication of success or failure to
+    // 'success' for a true indication of success or failure to load the
-        // load the symbol.
+    // symbol.
     //
-        // Returns a pointer to the symbol on success, or NULL if an error
+    // Returns a pointer to the symbol on success, or NULL if an error occurred
-        // occurred or the symbol wasn't found.
+    // or the symbol wasn't found.
-
     void *GetSymbol(const wxString& name, bool *success = 0) const;
 
-#if WXWIN_COMPATIBILITY_2_2
-    operator bool() const { return IsLoaded(); }
-#endif
 
     // return platform-specific name of dynamic library with proper extension
     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
@@ -173,19 +175,20 @@ public:
     // string on others:
     static wxString GetPluginsDirectory();
 
+
+#if WXWIN_COMPATIBILITY_2_2
+    operator bool() const { return IsLoaded(); }
+#endif
+
 protected:
-
+    // platform specific shared lib suffix.
-        // Platform specific shared lib suffix.
-
     static const wxChar *ms_dllext;
 
     // the handle to DLL or NULL
-
     wxDllType m_handle;
 
-        // no copy ctor/assignment operators
+    // no copy ctor/assignment operators (or we'd try to unload the library
-        // or we'd try to unload the library twice
+    // twice)
-
     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 };
 

src/msw/app.cpp

@@ -854,9 +854,6 @@ void wxApp::OnQueryEndSession(wxCloseEvent& event)
     }
 }
 
-#define wxDYNLIB_FUNCTION(type, name, dll)                                    \
-    type pfn ## name = (type)dll.GetSymbol(_T(#name))
-
 /* static */
 int wxApp::GetComCtl32Version()
 {