More initial reviews of d* interface headers.

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

diff --git a/interface/dialup.h b/interface/dialup.h
index 2b72e9786b7c34c2708f7e3dad5e1174f1c853fe..165bf575813002c511b62d481ff286d623fbc7d6 100644 (file)
--- a/interface/dialup.h
+++ b/interface/dialup.h
@@ -10,26 +10,33 @@
     @class wxDialUpManager
     @wxheader{dialup.h}
 
     @class wxDialUpManager
     @wxheader{dialup.h}
 

-    This class encapsulates functions dealing with verifying the connection status
-    of the workstation (connected to the Internet via a direct connection,
-    connected through a modem or not connected at all) and to establish this
-    connection if possible/required (i.e. in the case of the modem).
+    This class encapsulates functions dealing with verifying the connection
+    status of the workstation (connected to the Internet via a direct
+    connection, connected through a modem or not connected at all) and to
+    establish this connection if possible/required (i.e. in the case of the
+    modem).

 
     The program may also wish to be notified about the change in the connection
     status (for example, to perform some action when the user connects to the
 
     The program may also wish to be notified about the change in the connection
     status (for example, to perform some action when the user connects to the

-    network the next time or, on the contrary, to stop receiving data from the net
-    when the user hangs up the modem). For this, you need to use one of the event
-    macros described below.
+    network the next time or, on the contrary, to stop receiving data from the
+    net when the user hangs up the modem). For this, you need to use one of the
+    event macros described below.

 
 

-    This class is different from other wxWidgets classes in that there is at most
-    one instance of this class in the program accessed via
-    wxDialUpManager::Create and you can't
-    create the objects of this class directly.
+    This class is different from other wxWidgets classes in that there is at
+    most one instance of this class in the program accessed via Create() and
+    you can't create the objects of this class directly.
+
+    @beginEventTable{wxDialUpEvent}
+    @event{EVT_DIALUP_CONNECTED(func)}
+           A connection with the network was established.
+    @event{EVT_DIALUP_DISCONNECTED(func)}
+           The connection with the network was lost.
+    @endEventTable

 
     @library{wxcore}
     @category{net}
 
 
     @library{wxcore}
     @category{net}
 

-    @see @ref overview_sampledialup "dialup sample", wxDialUpEvent
+    @see @ref page_samples_dialup, wxDialUpEvent

 */
 class wxDialUpManager
 {
 */
 class wxDialUpManager
 {


@@ -40,35 +47,39 @@ public:
     ~wxDialUpManager();
 
     /**
     ~wxDialUpManager();
 
     /**

-        Cancel dialing the number initiated with Dial()
-        with async parameter equal to @true.
-        Note that this won't result in DISCONNECTED event being sent.
+        Cancel dialing the number initiated with Dial() with async parameter
+        equal to @true.
+
+        @note This won't result in a DISCONNECTED event being sent.

 
         @see IsDialing()
     */
     bool CancelDialing();
 
     /**
 
         @see IsDialing()
     */
     bool CancelDialing();
 
     /**

-        This function should create and return the object of the platform-specific
-        class derived from wxDialUpManager. You should delete the pointer when you are
-        done with it.
+        This function should create and return the object of the
+        platform-specific class derived from wxDialUpManager. You should delete
+        the pointer when you are done with it.

     */
     wxDialUpManager* Create();
 
     /**
         Dial the given ISP, use @a username and @a password to authenticate.
     */
     wxDialUpManager* Create();
 
     /**
         Dial the given ISP, use @a username and @a password to authenticate.

-        The parameters are only used under Windows currently, for Unix you should use
-        SetConnectCommand() to customize this
-        functions behaviour.
+
+        The parameters are only used under Windows currently, for Unix you
+        should use SetConnectCommand() to customize this functions behaviour.
+

         If no @a nameOfISP is given, the function will select the default one
         If no @a nameOfISP is given, the function will select the default one

-        (proposing the user to choose among all connections defined on this machine)
-        and if no username and/or password are given, the function will try to do
-        without them, but will ask the user if really needed.
-        If @a async parameter is @false, the function waits until the end of dialing
-        and returns @true upon successful completion.
+        (proposing the user to choose among all connections defined on this
+        machine) and if no username and/or password are given, the function
+        will try to do without them, but will ask the user if really needed.
+
+        If @a async parameter is @false, the function waits until the end of
+        dialing and returns @true upon successful completion.
+

         If @a async is @true, the function only initiates the connection and
         If @a async is @true, the function only initiates the connection and

-        returns immediately - the result is reported via events (an event is sent
-        anyhow, but if dialing failed it will be a DISCONNECTED one).
+        returns immediately - the result is reported via events (an event is
+        sent anyhow, but if dialing failed it will be a DISCONNECTED one).

     */
     bool Dial(const wxString& nameOfISP = wxEmptyString,
               const wxString& username = wxEmptyString,
     */
     bool Dial(const wxString& nameOfISP = wxEmptyString,
               const wxString& username = wxEmptyString,


@@ -83,20 +94,23 @@ public:
 
     /**
         Enable automatic checks for the connection status and sending of
 
     /**
         Enable automatic checks for the connection status and sending of

-        @c wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
-        parameter is only for Unix where we do the check manually and specifies how
-        often should we repeat the check (each minute by default). Under Windows, the
-        notification about the change of connection status is sent by the system and so
-        we don't do any polling and this parameter is ignored.
-        Returns @false if couldn't set up automatic check for online status.
+        wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
+        parameter is only for Unix where we do the check manually and specifies
+        how often should we repeat the check (each minute by default). Under
+        Windows, the notification about the change of connection status is sent
+        by the system and so we don't do any polling and this parameter is
+        ignored.
+
+        @returns @false if couldn't set up automatic check for online status.

     */
     bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60);
 
     /**
         This function is only implemented under Windows.
     */
     bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60);
 
     /**
         This function is only implemented under Windows.

+

         Fills the array with the names of all possible values for the first
         Fills the array with the names of all possible values for the first

-        parameter to Dial() on this machine and returns
-        their number (may be 0).
+        parameter to Dial() on this machine and returns their number (may be
+        0).

     */
     size_t GetISPNames(wxArrayString& names) const;
 
     */
     size_t GetISPNames(wxArrayString& names) const;
 


@@ -106,11 +120,13 @@ public:
     bool HangUp();
 
     /**
     bool HangUp();
 
     /**

-        Returns @true if the computer has a permanent network connection (i.e. is
-        on a LAN) and so there is no need to use Dial() function to go online.
-        @note this functions tries to guess the result and it is not always
-        guaranteed to be correct, so it is better to ask user for
-        confirmation or give him a possibility to override it.
+        Returns @true if the computer has a permanent network connection (i.e.
+        is on a LAN) and so there is no need to use Dial() function to go
+        online.
+
+        @note This function tries to guess the result and it is not always
+              guaranteed to be correct, so it is better to ask user for
+              confirmation or give him a possibility to override it.

     */
     bool IsAlwaysOnline() const;
 
     */
     bool IsAlwaysOnline() const;
 


@@ -123,32 +139,33 @@ public:
 
     /**
         Returns @true if the dialup manager was initialized correctly. If this
 
     /**
         Returns @true if the dialup manager was initialized correctly. If this

-        function returns @false, no other functions will work neither, so it is a
-        good idea to call this function and check its result before calling any other
-        wxDialUpManager methods
+        function returns @false, no other functions will work neither, so it is
+        a good idea to call this function and check its result before calling
+        any other wxDialUpManager methods.

     */
     bool IsOk() const;
 
     /**
     */
     bool IsOk() const;
 
     /**

-        Returns @true if the computer is connected to the network: under Windows,
-        this just means that a RAS connection exists, under Unix we check that
-        the "well-known host" (as specified by
-        wxDialUpManager::SetWellKnownHost) is reachable.
+        Returns @true if the computer is connected to the network: under
+        Windows, this just means that a RAS connection exists, under Unix we
+        check that the "well-known host" (as specified by SetWellKnownHost())
+        is reachable.

     */
     bool IsOnline() const;
 
     /**
     */
     bool IsOnline() const;
 
     /**

-        ,  wxString&@e commandHangup = wxT("/usr/bin/poff"))

         This method is for Unix only.
         This method is for Unix only.

+

         Sets the commands to start up the network and to hang up again.
     */
         Sets the commands to start up the network and to hang up again.
     */

-    void SetConnectCommand() const;
+    void SetConnectCommand(const wxString& commandDial = "/usr/bin/pon",
+                           const wxString& commandHangup = "/usr/bin/poff") const;

 
     /**
 
     /**

-        Sometimes the built-in logic for determining the online status may fail,
-        so, in general, the user should be allowed to override it. This function
-        allows to forcefully set the online status - whatever our internal
-        algorithm may think about it.
+        Sometimes the built-in logic for determining the online status may
+        fail, so, in general, the user should be allowed to override it. This
+        function allows to forcefully set the online status - whatever our
+        internal algorithm may think about it.

 
         @see IsOnline()
     */
 
         @see IsOnline()
     */


@@ -156,9 +173,11 @@ public:
 
     /**
         This method is for Unix only.
 
     /**
         This method is for Unix only.

+

         Under Unix, the value of well-known host is used to check whether we're
         Under Unix, the value of well-known host is used to check whether we're

-        connected to the internet. It is unused under Windows, but this function
-        is always safe to call. The default value is @c www.yahoo.com:80.
+        connected to the internet. It is unused under Windows, but this
+        function is always safe to call. The default value is
+        @c "www.yahoo.com:80".

     */
     void SetWellKnownHost(const wxString& hostname, int portno = 80);
 };
     */
     void SetWellKnownHost(const wxString& hostname, int portno = 80);
 };


@@ -169,8 +188,7 @@ public:
     @class wxDialUpEvent
     @wxheader{dialup.h}
 
     @class wxDialUpEvent
     @wxheader{dialup.h}
 

-    This is the event class for the dialup events sent by
-    wxDialUpManager.
+    This is the event class for the dialup events sent by wxDialUpManager.

 
     @library{wxcore}
     @category{events}
 
     @library{wxcore}
     @category{events}


@@ -184,8 +202,8 @@ public:
     wxDialUpEvent(bool isConnected, bool isOwnEvent);
 
     /**
     wxDialUpEvent(bool isConnected, bool isOwnEvent);
 
     /**

-        Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does it
-        notify about transition from offline to online state or vice versa?
+        Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does
+        it notify about transition from offline to online state or vice versa?

     */
     bool IsConnectedEvent() const;
 
     */
     bool IsConnectedEvent() const;
 

diff --git a/interface/dir.h b/interface/dir.h
index cb9ca739175e89e4feb9fe08d6cc19e9d73f1ea1..4e65800c5253b3aae153c1a406a13928c4804e67 100644 (file)
--- a/interface/dir.h
+++ b/interface/dir.h
@@ -1,47 +1,57 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dir.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dir.h

-// Purpose:     interface of wxDirTraverser
+// Purpose:     interface of wxDir and wxDirTraverser

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Possible return values of wxDirTraverser callback functions.
+*/
+enum wxDirTraverseResult
+{
+    wxDIR_IGNORE = -1,  ///< Ignore this directory but continue with others.
+    wxDIR_STOP,         ///< Stop traversing.
+    wxDIR_CONTINUE      ///< Continue into this directory.
+};
+

 /**
     @class wxDirTraverser
     @wxheader{dir.h}
 
 /**
     @class wxDirTraverser
     @wxheader{dir.h}
 

-    wxDirTraverser is an abstract interface which must be implemented by objects
-    passed to wxDir::Traverse function.
+    wxDirTraverser is an abstract interface which must be implemented by
+    objects passed to wxDir::Traverse() function.

 
 

-    Example of use (this works almost like wxDir::GetAllFiles):
+    Example of use (this works almost like wxDir::GetAllFiles()):

 
     @code
     class wxDirTraverserSimple : public wxDirTraverser
 
     @code
     class wxDirTraverserSimple : public wxDirTraverser

+    {
+    public:
+        wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
+
+        virtual wxDirTraverseResult OnFile(const wxString& filename)

         {
         {

-        public:
-            wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
-
-            virtual wxDirTraverseResult OnFile(const wxString& filename)
-            {
-                m_files.Add(filename);
-                return wxDIR_CONTINUE;
-            }
-
-            virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
-            {
-                return wxDIR_CONTINUE;
-            }
-
-        private:
-            wxArrayString& m_files;
-        };
-
-        // get the names of all files in the array
-        wxArrayString files;
-        wxDirTraverserSimple traverser(files);
-
-        wxDir dir(dirname);
-        dir.Traverse(traverser);
+            m_files.Add(filename);
+            return wxDIR_CONTINUE;
+        }
+
+        virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
+        {
+            return wxDIR_CONTINUE;
+        }
+
+    private:
+        wxArrayString& m_files;
+    };
+
+    // get the names of all files in the array
+    wxArrayString files;
+    wxDirTraverserSimple traverser(files);
+
+    wxDir dir(dirname);
+    dir.Traverse(traverser);

     @endcode
 
     @library{wxbase}
     @endcode
 
     @library{wxbase}


@@ -51,69 +61,87 @@ class wxDirTraverser
 {
 public:
     /**
 {
 public:
     /**

-        This function is called for each directory. It may return @c wxDIR_STOP
-        to abort traversing completely, @c wxDIR_IGNORE to skip this directory but
-        continue with others or @c wxDIR_CONTINUE to enumerate all files and
+        This function is called for each directory. It may return ::wxDIR_STOP
+        to abort traversing completely, ::wxDIR_IGNORE to skip this directory
+        but continue with others or ::wxDIR_CONTINUE to enumerate all files and

         subdirectories in this directory.
         subdirectories in this directory.

-        This is a pure virtual function and must be implemented in the derived class.
+
+        This is a pure virtual function and must be implemented in the derived
+        class.

     */
     virtual wxDirTraverseResult OnDir(const wxString& dirname);
 
     /**
     */
     virtual wxDirTraverseResult OnDir(const wxString& dirname);
 
     /**

-        This function is called for each file. It may return @c wxDIR_STOP to abort
-        traversing (for example, if the file being searched is found) or
-        @c wxDIR_CONTINUE to proceed.
-        This is a pure virtual function and must be implemented in the derived class.
+        This function is called for each file. It may return ::wxDIR_STOP to
+        abort traversing (for example, if the file being searched is found) or
+        ::wxDIR_CONTINUE to proceed.
+
+        This is a pure virtual function and must be implemented in the derived
+        class.

     */
     virtual wxDirTraverseResult OnFile(const wxString& filename);
 
     /**
         This function is called for each directory which we failed to open for
     */
     virtual wxDirTraverseResult OnFile(const wxString& filename);
 
     /**
         This function is called for each directory which we failed to open for

-        enumerating. It may return @c wxDIR_STOP to abort traversing completely,
-        @c wxDIR_IGNORE to skip this directory but continue with others or
-        @c wxDIR_CONTINUE to retry opening this directory once again.
-        The base class version always returns @c wxDIR_IGNORE.
+        enumerating. It may return ::wxDIR_STOP to abort traversing completely,
+        ::wxDIR_IGNORE to skip this directory but continue with others or
+        ::wxDIR_CONTINUE to retry opening this directory once again.
+
+        The base class version always returns ::wxDIR_IGNORE.

     */
     virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
 };
 
 
 
     */
     virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
 };
 
 
 

+/**
+    These flags define what kind of filenames are included in the list of files
+    enumerated by wxDir::GetFirst() and wxDir::GetNext().
+*/
+enum
+{
+    wxDIR_FILES     = 0x0001,   ///< Includes files.
+    wxDIR_DIRS      = 0x0002,   ///< Includes directories.
+    wxDIR_HIDDEN    = 0x0004,   ///< Includes hidden files.
+    wxDIR_DOTDOT    = 0x0008,   ///< Includes "." and "..".
+
+    wxDIR_DEFAULT   = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
+};
+

 /**
     @class wxDir
     @wxheader{dir.h}
 
     wxDir is a portable equivalent of Unix open/read/closedir functions which
 /**
     @class wxDir
     @wxheader{dir.h}
 
     wxDir is a portable equivalent of Unix open/read/closedir functions which

-    allow enumerating of the files in a directory. wxDir allows to enumerate files
-    as well as directories.
+    allow enumerating of the files in a directory. wxDir allows to enumerate
+    files as well as directories.

 
     wxDir also provides a flexible way to enumerate files recursively using
 
     wxDir also provides a flexible way to enumerate files recursively using

-    wxDir::Traverse or a simpler
-    wxDir::GetAllFiles function.
+    Traverse() or a simpler GetAllFiles() function.

 
     Example of use:
 
     @code
     wxDir dir(wxGetCwd());
 
 
     Example of use:
 
     @code
     wxDir dir(wxGetCwd());
 

-        if ( !dir.IsOpened() )
-        {
-            // deal with the error here - wxDir would already log an error message
-            // explaining the exact reason of the failure
-            return;
-        }
+    if ( !dir.IsOpened() )
+    {
+        // deal with the error here - wxDir would already log an error message
+        // explaining the exact reason of the failure
+        return;
+    }

 
 

-        puts("Enumerating object files in current directory:");
+    puts("Enumerating object files in current directory:");

 
 

-        wxString filename;
+    wxString filename;

 
 

-        bool cont = dir.GetFirst(, filespec, flags);
-        while ( cont )
-        {
-            printf("%s\n", filename.c_str());
+    bool cont = dir.GetFirst(&filename, filespec, flags);
+    while ( cont )
+    {
+        printf("%s\n", filename.c_str());

 
 

-            cont = dir.GetNext();
-        }
+        cont = dir.GetNext(&filename);
+    }

     @endcode
 
     @library{wxbase}
     @endcode
 
     @library{wxbase}


@@ -122,51 +150,55 @@ public:
 class wxDir
 {
 public:
 class wxDir
 {
 public:

-    //@{

     /**
     /**

-        Opens the directory for enumeration, use IsOpened()
-        to test for errors.
+        Default constructor, use Open() afterwards.

     */
     wxDir();
     */
     wxDir();

+    /**
+        Opens the directory for enumeration, use IsOpened() to test for errors.
+    */

     wxDir(const wxString& dir);
     wxDir(const wxString& dir);

-    //@}

 
     /**
 
     /**

-        Destructor cleans up the associated resources. It is not virtual and so this
-        class is not meant to be used polymorphically.
+        Destructor cleans up the associated resources. It is not virtual and so
+        this class is not meant to be used polymorphically.

     */
     ~wxDir();
 
     /**
     */
     ~wxDir();
 
     /**

-        Test for existence of a directory with the given name
+        Test for existence of a directory with the given name.

     */
     static bool Exists(const wxString& dir);
 
     /**
     */
     static bool Exists(const wxString& dir);
 
     /**

-        The function returns the path of the first file matching the given @e filespec
-        or an empty string if there are no files matching it.
-        The @a flags parameter may or may not include @c wxDIR_FILES, the
+        The function returns the path of the first file matching the given
+        @a filespec or an empty string if there are no files matching it.
+
+        The @a flags parameter may or may not include ::wxDIR_FILES, the

         function always behaves as if it were specified. By default, @a flags
         function always behaves as if it were specified. By default, @a flags

-        includes @c wxDIR_DIRS and so the function recurses into the subdirectories
-        but if this flag is not specified, the function restricts the search only to
-        the directory @a dirname itself.
-        See also: Traverse()
+        includes ::wxDIR_DIRS and so the function recurses into the
+        subdirectories but if this flag is not specified, the function
+        restricts the search only to the directory @a dirname itself.
+
+        @see Traverse()

     */
     static wxString FindFirst(const wxString& dirname,
                               const wxString& filespec,
                               int flags = wxDIR_DEFAULT);
 
     /**
     */
     static wxString FindFirst(const wxString& dirname,
                               const wxString& filespec,
                               int flags = wxDIR_DEFAULT);
 
     /**

-        The function appends the names of all the files under directory @a dirname
-        to the array @a files (note that its old content is preserved). Only files
-        matching the @a filespec are taken, with empty spec matching all the files.
-        The @a flags parameter should always include @c wxDIR_FILES or the array
-        would be unchanged and should include @c wxDIR_DIRS flag to recurse into
+        The function appends the names of all the files under directory
+        @a dirname to the array @a files (note that its old content is
+        preserved). Only files matching the @a filespec are taken, with empty
+        spec matching all the files.
+
+        The @a flags parameter should always include ::wxDIR_FILES or the array
+        would be unchanged and should include ::wxDIR_DIRS flag to recurse into

         subdirectories (both flags are included in the value by default).
         subdirectories (both flags are included in the value by default).

-        See also: Traverse()
+
+        @see Traverse()

     */
     */

-    static size_t GetAllFiles(const wxString& dirname,
-                              wxArrayString* files,
+    static size_t GetAllFiles(const wxString& dirname, wxArrayString* files,

                               const wxString& filespec = wxEmptyString,
                               int flags = wxDIR_DEFAULT);
 
                               const wxString& filespec = wxEmptyString,
                               int flags = wxDIR_DEFAULT);
 


@@ -179,76 +211,79 @@ public:
                   int flags = wxDIR_DEFAULT) const;
 
     /**
                   int flags = wxDIR_DEFAULT) const;
 
     /**

-        Returns the name of the directory itself. The returned string does not have the
-        trailing path separator (slash or backslash).
+        Returns the name of the directory itself. The returned string does not
+        have the trailing path separator (slash or backslash).

     */
     wxString GetName() const;
 
     /**
     */
     wxString GetName() const;
 
     /**

-        Continue enumerating files which satisfy the criteria specified by the last
-        call to GetFirst().
+        Continue enumerating files which satisfy the criteria specified by the
+        last call to GetFirst().

     */
     bool GetNext(wxString* filename) const;
 
     /**
         Returns the size (in bytes) of all files recursively found in @c dir or
         @c wxInvalidSize in case of error.
     */
     bool GetNext(wxString* filename) const;
 
     /**
         Returns the size (in bytes) of all files recursively found in @c dir or
         @c wxInvalidSize in case of error.

-        In case it happens that while traversing folders a file's size can not be read,
-        that file is added to the @c filesSkipped array, if not @NULL, and then
-        skipped.
-        This usually happens with some special folders which are locked by the
-        operating system
-        or by another process. Remember that when @c filesSkipped-GetCount() is not
-        zero,
-        then the returned value is not 100% accurate and, if the skipped files were
-        big, it could be
+
+        In case it happens that while traversing folders a file's size can not
+        be read, that file is added to the @a filesSkipped array, if not @NULL,
+        and then skipped. This usually happens with some special folders which
+        are locked by the operating system or by another process. Remember that
+        when the size of @a filesSkipped is not zero, then the returned value
+        is not 100% accurate and, if the skipped files were big, it could be

         far from real size of the directory.
         far from real size of the directory.

-        See also: wxFileName::GetHumanReadableSize,
-        wxGetDiskSpace()
+
+        @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace()

     */
     static wxULongLong GetTotalSize(const wxString& dir,
                                     wxArrayString* filesSkipped = NULL);
 
     /**
         Returns @true if the directory contains any files matching the given
     */
     static wxULongLong GetTotalSize(const wxString& dir,
                                     wxArrayString* filesSkipped = NULL);
 
     /**
         Returns @true if the directory contains any files matching the given

-        @e filespec. If @a filespec is empty, look for any files at all. In any
+        @a filespec. If @a filespec is empty, look for any files at all. In any

         case, even hidden files are taken into account.
     */
     bool HasFiles(const wxString& filespec = wxEmptyString);
 
     /**
         Returns @true if the directory contains any subdirectories (if a non
         case, even hidden files are taken into account.
     */
     bool HasFiles(const wxString& filespec = wxEmptyString);
 
     /**
         Returns @true if the directory contains any subdirectories (if a non

-        empty @e filespec is given, only check for directories matching it).
+        empty @a filespec is given, only check for directories matching it).

         The hidden subdirectories are taken into account as well.
     */
     bool HasSubDirs(const wxString& dirspec = wxEmptyString);
 
     /**
         The hidden subdirectories are taken into account as well.
     */
     bool HasSubDirs(const wxString& dirspec = wxEmptyString);
 
     /**

-        Returns @true if the directory was successfully opened by a previous call to
-        Open().
+        Returns @true if the directory was successfully opened by a previous
+        call to Open().

     */
     bool IsOpened() const;
 
     /**
     */
     bool IsOpened() const;
 
     /**

-        Open the directory for enumerating, returns @true on success
-        or @false if an error occurred.
+        Open the directory for enumerating, returns @true on success or @false
+        if an error occurred.

     */
     bool Open(const wxString& dir);
 
     /**
     */
     bool Open(const wxString& dir);
 
     /**

-        Enumerate all files and directories under the given directory recursively
-        calling the element of the provided wxDirTraverser
-        object for each of them.
+        Enumerate all files and directories under the given directory
+        recursively calling the element of the provided wxDirTraverser object
+        for each of them.
+

         More precisely, the function will really recurse into subdirectories if
         More precisely, the function will really recurse into subdirectories if

-        @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but
-        still possibly recurse into subdirectories) if @c wxDIR_FILES flag is
+        @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but
+        still possibly recurse into subdirectories) if ::wxDIR_FILES flag is

         given.
         given.

-        For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called
-        and @ref wxDirTraverser::onfile sink.OnFile is called for every file.
-        Depending on the return value, the enumeration may continue or stop.
-        The function returns the total number of files found or @c (size_t)-1 on
-        error.
-        See also: GetAllFiles()
+
+        For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()"
+        is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
+        for every file. Depending on the return value, the enumeration may
+        continue or stop.
+
+        The function returns the total number of files found or @c "(size_t)-1"
+        on error.
+
+        @see GetAllFiles()

     */
     size_t Traverse(wxDirTraverser& sink,
                     const wxString& filespec = wxEmptyString,
     */
     size_t Traverse(wxDirTraverser& sink,
                     const wxString& filespec = wxEmptyString,

diff --git a/interface/dirctrl.h b/interface/dirctrl.h
index 018686b534415e381485bfa5bea4ab58ace89aac..b83c4248df8d8426fca17ac25ab6b9160c389798 100644 (file)
--- a/interface/dirctrl.h
+++ b/interface/dirctrl.h
@@ -10,20 +10,35 @@
     @class wxGenericDirCtrl
     @wxheader{dirctrl.h}
 
     @class wxGenericDirCtrl
     @wxheader{dirctrl.h}
 

-    This control can  be used to place a directory listing (with optional files) on
-    an arbitrary window.
+    This control can  be used to place a directory listing (with optional
+    files) on an arbitrary window.

 
     The control contains a wxTreeCtrl window representing the directory
     hierarchy, and optionally, a wxChoice window containing a list of filters.
 
 
     The control contains a wxTreeCtrl window representing the directory
     hierarchy, and optionally, a wxChoice window containing a list of filters.
 

+    @beginStyleTable
+    @style{wxDIRCTRL_DIR_ONLY}
+           Only show directories, and not files.
+    @style{wxDIRCTRL_3D_INTERNAL}
+           Use 3D borders for internal controls.
+    @style{wxDIRCTRL_SELECT_FIRST}
+           When setting the default path, select the first file in the
+           directory.
+    @style{wxDIRCTRL_EDIT_LABELS}
+           Allow the folder and file labels to be editable.
+    @endStyleTable
+

     @library{wxbase}
     @category{ctrl}
     @library{wxbase}
     @category{ctrl}

-    @appearance{genericdirctrl.png}
+    <!-- @appearance{genericdirctrl.png} -->

 */
 class wxGenericDirCtrl : public wxControl
 {
 public:
 */
 class wxGenericDirCtrl : public wxControl
 {
 public:

-    //@{
+    /**
+        Default constructor.
+    */
+    wxGenericDirCtrl();

     /**
         Main constructor.
 
     /**
         Main constructor.
 


@@ -38,18 +53,17 @@ public:
         @param size
             Size.
         @param style
         @param size
             Size.
         @param style

-            Window style. Please see wxGenericDirCtrl for a list of possible styles.
+            Window style. Please see wxGenericDirCtrl for a list of possible
+            styles.

         @param filter
         @param filter

-            A filter string, using the same syntax as that for wxFileDialog. This may
-        be empty if filters
-            are not being used.
-            Example: "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg"
+            A filter string, using the same syntax as that for wxFileDialog.
+            This may be empty if filters are not being used. Example:
+            @c "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg"

         @param defaultFilter
             The zero-indexed default filter setting.
         @param name
             The window name.
     */
         @param defaultFilter
             The zero-indexed default filter setting.
         @param name
             The window name.
     */

-    wxGenericDirCtrl();

     wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1,
                      const wxString& dir = wxDirDialogDefaultFolderStr,
                      const wxPoint& pos = wxDefaultPosition,
     wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1,
                      const wxString& dir = wxDirDialogDefaultFolderStr,
                      const wxPoint& pos = wxDefaultPosition,


@@ -58,7 +72,6 @@ public:
                      const wxString& filter = wxEmptyString,
                      int defaultFilter = 0,
                      const wxString& name = wxTreeCtrlNameStr);
                      const wxString& filter = wxEmptyString,
                      int defaultFilter = 0,
                      const wxString& name = wxTreeCtrlNameStr);

-    //@}

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -66,7 +79,7 @@ public:
     ~wxGenericDirCtrl();
 
     /**
     ~wxGenericDirCtrl();
 
     /**

-        Collapse the given path.
+        Collapse the given @a path.

     */
     bool CollapsePath(const wxString& path);
 
     */
     bool CollapsePath(const wxString& path);
 


@@ -76,7 +89,8 @@ public:
     void CollapseTree();
 
     /**
     void CollapseTree();
 
     /**

-        Create function for two-step construction. See wxGenericDirCtrl() for details.
+        Create function for two-step construction. See wxGenericDirCtrl() for
+        details.

     */
     bool Create(wxWindow* parent, const wxWindowID id = -1,
                 const wxString& dir = wxDirDialogDefaultFolderStr,
     */
     bool Create(wxWindow* parent, const wxWindowID id = -1,
                 const wxString& dir = wxDirDialogDefaultFolderStr,


@@ -88,8 +102,8 @@ public:
                 const wxString& name = wxTreeCtrlNameStr);
 
     /**
                 const wxString& name = wxTreeCtrlNameStr);
 
     /**

-        Tries to expand as much of the given path as possible, so that the filename or
-        directory is visible in the tree control.
+        Tries to expand as much of the given @a path as possible, so that the
+        filename or directory is visible in the tree control.

     */
     bool ExpandPath(const wxString& path);
 
     */
     bool ExpandPath(const wxString& path);
 


@@ -100,6 +114,7 @@ public:
 
     /**
         Gets selected filename path only (else empty string).
 
     /**
         Gets selected filename path only (else empty string).

+

         This function doesn't count a directory as a selection.
     */
     wxString GetFilePath() const;
         This function doesn't count a directory as a selection.
     */
     wxString GetFilePath() const;


@@ -140,8 +155,8 @@ public:
     void Init();
 
     /**
     void Init();
 
     /**

-        Collapse and expand the tree, thus re-creating it from scratch.
-        May be used to update the displayed directory content.
+        Collapse and expand the tree, thus re-creating it from scratch. May be
+        used to update the displayed directory content.

     */
     void ReCreateTree();
 
     */
     void ReCreateTree();
 

diff --git a/interface/dirdlg.h b/interface/dirdlg.h
index c6bd03c27355c06d6652ce30f51d2d0ed03688ae..4d21deac8577d18008a59a56462bdd2f1e7d95a4 100644 (file)
--- a/interface/dirdlg.h
+++ b/interface/dirdlg.h
@@ -26,17 +26,19 @@
            user.
     @endStyleTable
 
            user.
     @endStyleTable
 

+    @note On Windows the new directory button is only available with recent
+          versions of the common dialogs.
+

     @library{wxcore}
     @category{cmndlg}
 
     @library{wxcore}
     @category{cmndlg}
 

-    @see @ref overview_wxdirdialogoverview "wxDirDialog overview", wxFileDialog
+    @see @ref overview_cmndlg_dir, wxFileDialog

 */
 class wxDirDialog : public wxDialog
 {
 public:
     /**
 */
 class wxDirDialog : public wxDialog
 {
 public:
     /**

-        Constructor. Use ShowModal() to show
-        the dialog.
+        Constructor. Use ShowModal() to show the dialog.

 
         @param parent
             Parent window.
 
         @param parent
             Parent window.


@@ -87,8 +89,8 @@ public:
     void SetPath(const wxString& path);
 
     /**
     void SetPath(const wxString& path);
 
     /**

-        Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
-        otherwise.
+        Shows the dialog, returning wxID_OK if the user pressed OK, and
+        wxID_CANCEL otherwise.

     */
     int ShowModal();
 };
     */
     int ShowModal();
 };

diff --git a/interface/display.h b/interface/display.h
index e4a3c747e2740a5eb223a483a82bb9369e0213d0..71eeeba4f58793cfe4dfbf3f198f336f542261c6 100644 (file)
--- a/interface/display.h
+++ b/interface/display.h
@@ -13,7 +13,7 @@
     Determines the sizes and locations of displays connected to the system.
 
     @library{wxcore}
     Determines the sizes and locations of displays connected to the system.
 
     @library{wxcore}

-    @category{FIXME}
+    @category{misc}

 
     @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM()
 */
 
     @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM()
 */


@@ -21,11 +21,12 @@ class wxDisplay
 {
 public:
     /**
 {
 public:
     /**

-        Constructor, setting up a wxDisplay instance with the specified display.
+        Constructor, setting up a wxDisplay instance with the specified
+        display.

 
         @param index
 
         @param index

-            The index of the display to use.  This must be non-negative
-            and lower than the value returned by GetCount().
+            The index of the display to use. This must be non-negative and
+            lower than the value returned by GetCount().

     */
     wxDisplay(unsigned index = 0);
 
     */
     wxDisplay(unsigned index = 0);
 


@@ -35,27 +36,28 @@ public:
     ~wxDisplay();
 
     /**
     ~wxDisplay();
 
     /**

-        Changes the video mode of this display to the mode specified
-        in the mode parameter.
-        If wxDefaultVideoMode is passed in as the mode parameter,
-        the defined behaviour is that wxDisplay will reset the video
-        mode to the default mode used by the display.  On Windows,
-        the behavior is normal.  However, there are differences on other
-        platforms. On Unix variations using X11 extensions it should
-        behave as defined, but some irregularities may occur.
-        On wxMac passing in wxDefaultVideoMode as the mode
-        parameter does nothing.  This happens because carbon
-        no longer has access to DMUseScreenPrefs, an undocumented
-        function that changed the video mode to the system
-        default by using the system's 'scrn' resource.
+        Changes the video mode of this display to the mode specified in the
+        mode parameter.
+
+        If wxDefaultVideoMode is passed in as the mode parameter, the defined
+        behaviour is that wxDisplay will reset the video mode to the default
+        mode used by the display. On Windows, the behavior is normal. However,
+        there are differences on other platforms. On Unix variations using X11
+        extensions it should behave as defined, but some irregularities may
+        occur.
+
+        On wxMac passing in wxDefaultVideoMode as the mode parameter does
+        nothing. This happens because carbon no longer has access to
+        @c DMUseScreenPrefs(), an undocumented function that changed the video
+        mode to the system default by using the system's "scrn" resource.

     */
     bool ChangeMode(const wxVideoMode& mode = wxDefaultVideoMode);
 
     /**
     */
     bool ChangeMode(const wxVideoMode& mode = wxDefaultVideoMode);
 
     /**

-        Returns the client area of the display. The client area is the part of the
-        display available for the normal (non full screen) windows, usually it is the
-        same as GetGeometry() but it could be less if
-        there is a taskbar (or equivalent) on this display.
+        Returns the client area of the display. The client area is the part of
+        the display available for the normal (non full screen) windows, usually
+        it is the same as GetGeometry() but it could be less if there is a
+        taskbar (or equivalent) on this display.

     */
     wxRect GetClientArea() const;
 
     */
     wxRect GetClientArea() const;
 


@@ -70,12 +72,13 @@ public:
     wxVideoMode GetCurrentMode() const;
 
     /**
     wxVideoMode GetCurrentMode() const;
 
     /**

-        Returns the bit depth of the display whose index was passed to the constructor.
+        Returns the bit depth of the display whose index was passed to the
+        constructor.

     */
     int GetDepth() const;
 
     /**
     */
     int GetDepth() const;
 
     /**

-        Returns the index of the display on which the given point lies.  Returns
+        Returns the index of the display on which the given point lies, or

         @c wxNOT_FOUND if the point is not on any connected display.
 
         @param pt
         @c wxNOT_FOUND if the point is not on any connected display.
 
         @param pt


@@ -85,8 +88,10 @@ public:
 
     /**
         Returns the index of the display on which the given window lies.
 
     /**
         Returns the index of the display on which the given window lies.

-        If the window is on more than one display it gets the display that overlaps the
-        window the most.
+
+        If the window is on more than one display it gets the display that
+        overlaps the window the most.
+

         Returns @c wxNOT_FOUND if the window is not on any connected display.
 
         @param win
         Returns @c wxNOT_FOUND if the window is not on any connected display.
 
         @param win


@@ -95,27 +100,28 @@ public:
     static int GetFromWindow(const wxWindow* win);
 
     /**
     static int GetFromWindow(const wxWindow* win);
 
     /**

-        Returns the bounding rectangle of the display whose index was passed to the
-        constructor.
+        Returns the bounding rectangle of the display whose index was passed to
+        the constructor.
+
+        @see GetClientArea(), wxDisplaySize()

     */
     wxRect GetGeometry() const;
 
     /**
     */
     wxRect GetGeometry() const;
 
     /**

-        Fills and returns an array with all the video modes that
-        are supported by this display, or video modes that are
-        supported by this display and match the mode parameter
-        (if mode is not wxDefaultVideoMode).
+        Fills and returns an array with all the video modes that are supported
+        by this display, or video modes that are supported by this display and
+        match the mode parameter (if mode is not wxDefaultVideoMode).

     */
     wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode) const;
 
     /**
     */
     wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode) const;
 
     /**

-        Returns the display's name.  A name is not available on all platforms.
+        Returns the display's name. A name is not available on all platforms.

     */
     wxString GetName() const;
 
     /**
     */
     wxString GetName() const;
 
     /**

-        Returns @true if the display is the primary display.  The primary display is the
-        one whose index is 0.
+        Returns @true if the display is the primary display. The primary
+        display is the one whose index is 0.

     */
     bool IsPrimary();
 };
     */
     bool IsPrimary();
 };

diff --git a/interface/dnd.h b/interface/dnd.h
index e93ddeef7e0657fee9b121f3315eb35696381cfb..b82f304cdc8dec969f85fcf1193b15465f9fd21a 100644 (file)
--- a/interface/dnd.h
+++ b/interface/dnd.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dnd.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dnd.h

-// Purpose:     interface of wxTextDropTarget
+// Purpose:     interface of wxDropSource and wx*DropTarget

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -15,7 +15,7 @@
     @library{wxcore}
     @category{dnd}
 
     @library{wxcore}
     @category{dnd}
 

-    @see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxFileDropTarget
+    @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget

 */
 class wxTextDropTarget : public wxDropTarget
 {
 */
 class wxTextDropTarget : public wxDropTarget
 {


@@ -26,8 +26,8 @@ public:
     wxTextDropTarget();
 
     /**
     wxTextDropTarget();
 
     /**

-        See wxDropTarget::OnDrop. This function is implemented
-        appropriately for text, and calls OnDropText().
+        See wxDropTarget::OnDrop(). This function is implemented appropriately
+        for text, and calls OnDropText().

     */
     virtual bool OnDrop(long x, long y, const void data, size_t size);
 
     */
     virtual bool OnDrop(long x, long y, const void data, size_t size);
 


@@ -40,41 +40,47 @@ public:
             The y coordinate of the mouse.
         @param data
             The data being dropped: a wxString.
             The y coordinate of the mouse.
         @param data
             The data being dropped: a wxString.

+
+        Return @true to accept the data, or @false to veto the operation.

     */
     */

-    virtual bool OnDropText(wxCoord x, wxCoord y,
-                            const wxString& data);
+    virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data);

 };
 
 
 
 };
 
 
 

+/**
+    Result returned from a wxDropSource::DoDragDrop() call.
+*/
+enum wxDragResult
+{
+    wxDragError,    ///< Error prevented the D&D operation from completing.
+    wxDragNone,     ///< Drag target didn't accept the data.
+    wxDragCopy,     ///< The data was successfully copied.
+    wxDragMove,     ///< The data was successfully moved (MSW only).
+    wxDragLink,     ///< Operation is a drag-link.
+    wxDragCancel    ///< The operation was cancelled by user (not an error).
+};
+

 /**
     @class wxDropTarget
     @wxheader{dnd.h}
 
 /**
     @class wxDropTarget
     @wxheader{dnd.h}
 

-    This class represents a target for a drag and drop operation. A wxDataObject
-    can be associated with it and by default, this object will be filled with the
-    data from the
-    drag source, if the data formats supported by the data object match the drag
-    source data
-    format.
-
-    There are various virtual handler functions defined in this class which may be
-    overridden
-    to give visual feedback or react in a more fine-tuned way, e.g. by not
-    accepting data on
-    the whole window area, but only a small portion of it. The normal sequence of
-    calls is
-    wxDropTarget::OnEnter, possibly many times wxDropTarget::OnDragOver,
-    wxDropTarget::OnDrop and finally wxDropTarget::OnData.
-
-    See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview
-    for more information.
+    This class represents a target for a drag and drop operation. A
+    wxDataObject can be associated with it and by default, this object will be
+    filled with the data from the drag source, if the data formats supported by
+    the data object match the drag source data format.
+
+    There are various virtual handler functions defined in this class which may
+    be overridden to give visual feedback or react in a more fine-tuned way,
+    e.g. by not accepting data on the whole window area, but only a small
+    portion of it. The normal sequence of calls is OnEnter(), OnDragOver()
+    possibly many times, OnDrop() and finally OnData().

 
     @library{wxcore}
     @category{dnd}
 
 
     @library{wxcore}
     @category{dnd}
 

-    @see wxDropSource, wxTextDropTarget, wxFileDropTarget, wxDataFormat,
-    wxDataObject
+    @see @ref overview_dnd, @ref overview_dataobject, wxDropSource,
+         wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject

 */
 class wxDropTarget
 {
 */
 class wxDropTarget
 {


@@ -90,49 +96,47 @@ public:
     ~wxDropTarget();
 
     /**
     ~wxDropTarget();
 
     /**

-        This method may only be called from within OnData().
-        By default, this method copies the data from the drop source to the
-        wxDataObject associated with this drop target,
-        calling its wxDataObject::SetData method.
+        This method may only be called from within OnData(). By default, this
+        method copies the data from the drop source to the wxDataObject
+        associated with this drop target, calling its wxDataObject::SetData()
+        method.

     */
     virtual void GetData();
 
     /**
     */
     virtual void GetData();
 
     /**

-        Called after OnDrop() returns @true. By default this
-        will usually GetData() and will return the suggested
-        default value @e def.
+        Called after OnDrop() returns @true. By default this will usually
+        GetData() and will return the suggested default value @a def.

     */
     */

-    virtual wxDragResult OnData(wxCoord x, wxCoord y,
-                                wxDragResult def);
+    virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult def);

 
     /**
 
     /**

-        Called when the mouse is being dragged over the drop target. By default,
-        this calls functions return the suggested return value @e def.
+        Called when the mouse is being dragged over the drop target. By
+        default, this calls functions return the suggested return value @a def.

 
         @param x
             The x coordinate of the mouse.
         @param y
             The y coordinate of the mouse.
         @param def
 
         @param x
             The x coordinate of the mouse.
         @param y
             The y coordinate of the mouse.
         @param def

-            Suggested value for return value. Determined by SHIFT or CONTROL key states.
+            Suggested value for return value. Determined by SHIFT or CONTROL
+            key states.

 
 

-        @returns Returns the desired operation or wxDragNone. This is used for
-                 optical feedback from the side of the drop source,
-                 typically in form of changing the icon.
+        @returns The desired operation or wxDragNone. This is used for optical
+                 feedback from the side of the drop source, typically in form
+                 of changing the icon.

     */
     */

-    virtual wxDragResult OnDragOver(wxCoord x, wxCoord y,
-                                    wxDragResult def);
+    virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult def);

 
     /**
 
     /**

-        Called when the user drops a data object on the target. Return @false to veto
-        the operation.
+        Called when the user drops a data object on the target. Return @false
+        to veto the operation.

 
         @param x
             The x coordinate of the mouse.
         @param y
             The y coordinate of the mouse.
 
 
         @param x
             The x coordinate of the mouse.
         @param y
             The y coordinate of the mouse.
 

-        @returns Return @true to accept the data, @false to veto the operation.
+        @returns @true to accept the data, or @false to veto the operation.

     */
     virtual bool OnDrop(wxCoord x, wxCoord y);
 
     */
     virtual bool OnDrop(wxCoord x, wxCoord y);
 


@@ -145,15 +149,14 @@ public:
         @param y
             The y coordinate of the mouse.
         @param def
         @param y
             The y coordinate of the mouse.
         @param def

-            Suggested default for return value. Determined by SHIFT or CONTROL key
-        states.
+            Suggested default for return value. Determined by SHIFT or CONTROL
+            key states.

 
 

-        @returns Returns the desired operation or wxDragNone. This is used for
-                 optical feedback from the side of the drop source,
-                 typically in form of changing the icon.
+        @returns The desired operation or wxDragNone. This is used for optical
+                 feedback from the side of the drop source, typically in form
+                 of changing the icon.

     */
     */

-    virtual wxDragResult OnEnter(wxCoord x, wxCoord y,
-                                 wxDragResult def);
+    virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult def);

 
     /**
         Called when the mouse leaves the drop target.
 
     /**
         Called when the mouse leaves the drop target.


@@ -161,8 +164,8 @@ public:
     virtual void OnLeave();
 
     /**
     virtual void OnLeave();
 
     /**

-        Sets the data wxDataObject associated with the
-        drop target and deletes any previously associated data object.
+        Sets the data wxDataObject associated with the drop target and deletes
+        any previously associated data object.

     */
     void SetDataObject(wxDataObject* data);
 };
     */
     void SetDataObject(wxDataObject* data);
 };


@@ -175,25 +178,21 @@ public:
 
     This class represents a source for a drag and drop operation.
 
 
     This class represents a source for a drag and drop operation.
 

-    See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview
-    for more information.
-

     @library{wxcore}
     @category{dnd}
 
     @library{wxcore}
     @category{dnd}
 

-    @see wxDropTarget, wxTextDropTarget, wxFileDropTarget
+    @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
+         wxTextDropTarget, wxFileDropTarget

 */
 class wxDropSource
 {
 public:
 */
 class wxDropSource
 {
 public:

-    //@{

     /**
     /**

-        The constructors for wxDataObject.
-        If you use the constructor without @a data parameter you must call
-        SetData() later.
-        Note that the exact type of @a iconCopy and subsequent parameters differs
-        between wxMSW and wxGTK: these are cursors under Windows but icons for GTK.
-        You should use the macro wxDROP_ICON() in portable
+        This constructor requires that you must call SetData() later.
+
+        Note that the exact type of @a iconCopy and subsequent parameters
+        differs between wxMSW and wxGTK: these are cursors under Windows but
+        icons for GTK. You should use the macro wxDROP_ICON() in portable

         programs instead of directly using either of these types.
 
         @param win
         programs instead of directly using either of these types.
 
         @param win


@@ -209,30 +208,44 @@ public:
                  const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
                  const wxIconOrCursor& iconMove = wxNullIconOrCursor,
                  const wxIconOrCursor& iconNone = wxNullIconOrCursor);
                  const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
                  const wxIconOrCursor& iconMove = wxNullIconOrCursor,
                  const wxIconOrCursor& iconNone = wxNullIconOrCursor);

+    /**
+        Note that the exact type of @a iconCopy and subsequent parameters
+        differs between wxMSW and wxGTK: these are cursors under Windows but
+        icons for GTK. You should use the macro wxDROP_ICON() in portable
+        programs instead of directly using either of these types.
+
+        @param win
+            The window which initiates the drag and drop operation.
+        @param iconCopy
+            The icon or cursor used for feedback for copy operation.
+        @param iconMove
+            The icon or cursor used for feedback for move operation.
+        @param iconNone
+            The icon or cursor used for feedback when operation can't be done.
+    */

     wxDropSource(wxDataObject& data, wxWindow* win = NULL,
                  const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
                  const wxIconOrCursor& iconMove = wxNullIconOrCursor,
                  const wxIconOrCursor& iconNone = wxNullIconOrCursor);
     wxDropSource(wxDataObject& data, wxWindow* win = NULL,
                  const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
                  const wxIconOrCursor& iconMove = wxNullIconOrCursor,
                  const wxIconOrCursor& iconNone = wxNullIconOrCursor);

-    //@}

 
     /**
 
     /**

-
+        Default constructor.

     */
     ~wxDropSource();
 
     /**
     */
     ~wxDropSource();
 
     /**

-        Do it (call this in response to a mouse button press, for example). This starts
-        the drag-and-drop operation which will terminate when the user releases the
-        mouse.
+        Starts the drag-and-drop operation which will terminate when the user
+        releases the mouse. Call this in response to a mouse button press, for
+        example.

 
         @param flags
 
         @param flags

-            If wxDrag_AllowMove is included in the flags, data may
-            be moved and not only copied (default). If wxDrag_DefaultMove is
-            specified (which includes the previous flag), this is even the default
-            operation
+            If wxDrag_AllowMove is included in the flags, data may be moved and
+            not only copied (default). If wxDrag_DefaultMove is specified
+            (which includes the previous flag), this is even the default
+            operation.

 
 

-        @returns Returns the operation requested by the user, may be wxDragCopy,
-                 wxDragMove, wxDragLink, wxDragCancel or wxDragNone if
+        @returns The operation requested by the user, may be ::wxDragCopy,
+                 ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if

                  an error occurred.
     */
     virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly);
                  an error occurred.
     */
     virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly);


@@ -243,21 +256,18 @@ public:
     wxDataObject* GetDataObject();
 
     /**
     wxDataObject* GetDataObject();
 
     /**

-        Overridable: you may give some custom UI feedback during the drag and drop
-        operation
-        in this function. It is called on each mouse move, so your implementation must
-        not be too
-        slow.
+        You may give some custom UI feedback during the drag and drop operation
+        by overriding this function. It is called on each mouse move, so your
+        implementation must not be too slow.

 
         @param effect
 
         @param effect

-            The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and
-        wxDragNone.
+            The effect to implement. One of ::wxDragCopy, ::wxDragMove,
+            ::wxDragLink and ::wxDragNone.

         @param scrolling
             @true if the window is scrolling. MSW only.
 
         @param scrolling
             @true if the window is scrolling. MSW only.
 

-        @returns Return @false if you want default feedback, or @true if you
-                 implement your own feedback. The return values is
-                 ignored under GTK.
+        @returns @false if you want default feedback, or @true if you implement
+                 your own feedback. The return values is ignored under GTK.

     */
     virtual bool GiveFeedback(wxDragResult effect);
 
     */
     virtual bool GiveFeedback(wxDragResult effect);
 


@@ -272,8 +282,8 @@ public:
     void SetCursor(wxDragResult res, const wxCursor& cursor);
 
     /**
     void SetCursor(wxDragResult res, const wxCursor& cursor);
 
     /**

-        Sets the data wxDataObject associated with the
-        drop source. This will not delete any previously associated data.
+        Sets the data wxDataObject associated with the drop source. This will
+        not delete any previously associated data.

     */
     void SetData(wxDataObject& data);
 };
     */
     void SetData(wxDataObject& data);
 };


@@ -284,13 +294,13 @@ public:
     @class wxFileDropTarget
     @wxheader{dnd.h}
 
     @class wxFileDropTarget
     @wxheader{dnd.h}
 

-    This is a @ref overview_wxdroptarget "drop target" which accepts files (dragged
-    from File Manager or Explorer).
+    This is a drop target which accepts files (dragged from File Manager or
+    Explorer).

 
     @library{wxcore}
     @category{dnd}
 
 
     @library{wxcore}
     @category{dnd}
 

-    @see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxTextDropTarget
+    @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget

 */
 class wxFileDropTarget : public wxDropTarget
 {
 */
 class wxFileDropTarget : public wxDropTarget
 {


@@ -301,8 +311,8 @@ public:
     wxFileDropTarget();
 
     /**
     wxFileDropTarget();
 
     /**

-        See wxDropTarget::OnDrop. This function is implemented
-        appropriately for files, and calls OnDropFiles().
+        See wxDropTarget::OnDrop(). This function is implemented appropriately
+        for files, and calls OnDropFiles().

     */
     virtual bool OnDrop(long x, long y, const void data, size_t size);
 
     */
     virtual bool OnDrop(long x, long y, const void data, size_t size);
 


@@ -315,6 +325,8 @@ public:
             The y coordinate of the mouse.
         @param filenames
             An array of filenames.
             The y coordinate of the mouse.
         @param filenames
             An array of filenames.

+
+        Return @true to accept the data, or @false to veto the operation.

     */
     virtual bool OnDropFiles(wxCoord x, wxCoord y,
                              const wxArrayString& filenames);
     */
     virtual bool OnDropFiles(wxCoord x, wxCoord y,
                              const wxArrayString& filenames);