X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/clipbrd.h

diff --git a/interface/clipbrd.h b/interface/clipbrd.h
index 5ba025568d..307793295c 100644
--- a/interface/clipbrd.h
+++ b/interface/clipbrd.h
@@ -1,69 +1,70 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        clipbrd.h
-// Purpose:     documentation for wxClipboard class
+// Purpose:     interface of wxClipboard
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    The backwards compatible access macro that returns the global clipboard
+    object pointer.
+*/
+#define wxTheClipboard
+
 /**
     @class wxClipboard
     @wxheader{clipbrd.h}
 
-    A class for manipulating the clipboard. Note that this is not compatible with
-    the
-    clipboard class from wxWidgets 1.xx, which has the same name but a different
-    implementation.
+    A class for manipulating the clipboard.
 
-    To use the clipboard, you call member functions of the global @b wxTheClipboard
-    object.
+    To use the clipboard, you call member functions of the global
+    ::wxTheClipboard object.
 
-    See also the @ref overview_wxdataobjectoverview for further information.
+    See the @ref overview_dataobject for further information.
 
-    Call wxClipboard::Open to get ownership of the clipboard. If this operation
-    returns @true, you
-    now own the clipboard. Call wxClipboard::SetData to put data
-    on the clipboard, or wxClipboard::GetData to
-    retrieve data from the clipboard. Call wxClipboard::Close to close
-    the clipboard and relinquish ownership. You should keep the clipboard open only
-    momentarily.
+    Call wxClipboard::Open() to get ownership of the clipboard. If this
+    operation returns @true, you now own the clipboard. Call
+    wxClipboard::SetData() to put data on the clipboard, or
+    wxClipboard::GetData() to retrieve data from the clipboard. Call
+    wxClipboard::Close() to close the clipboard and relinquish ownership. You
+    should keep the clipboard open only momentarily.
 
     For example:
 
     @code
     // Write some text to the clipboard
-      if (wxTheClipboard-Open())
-      {
-        // This data objects are held by the clipboard,
+    if (wxTheClipboard->Open())
+    {
+        // This data objects are held by the clipboard, 
         // so do not delete them in the app.
-        wxTheClipboard-SetData( new wxTextDataObject("Some text") );
-        wxTheClipboard-Close();
-      }
-
-      // Read some text
-      if (wxTheClipboard-Open())
-      {
-        if (wxTheClipboard-IsSupported( wxDF_TEXT ))
+        wxTheClipboard->SetData( new wxTextDataObject("Some text") );
+        wxTheClipboard->Close();
+    }
+
+    // Read some text
+    if (wxTheClipboard->Open())
+    {
+        if (wxTheClipboard->IsSupported( wxDF_TEXT ))
         {
-          wxTextDataObject data;
-          wxTheClipboard-GetData( data );
-          wxMessageBox( data.GetText() );
-        }
-        wxTheClipboard-Close();
-      }
+            wxTextDataObject data;
+            wxTheClipboard->GetData( data );
+            wxMessageBox( data.GetText() );
+        }  
+        wxTheClipboard->Close();
+    }
     @endcode
 
     @library{wxcore}
     @category{dnd}
 
-    @seealso
-    @ref overview_wxdndoverview, wxDataObject
+    @see @ref overview_dnd, @ref overview_dataobject, wxDataObject
 */
 class wxClipboard : public wxObject
 {
 public:
     /**
-        Constructor.
+        Default constructor.
     */
     wxClipboard();
 
@@ -73,92 +74,106 @@ public:
     ~wxClipboard();
 
     /**
-        Call this function to add the data object to the clipboard. You may call
-        this function repeatedly after having cleared the clipboard using Clear().
-        After this function has been called, the clipboard owns the data, so do not
-        delete
-        the data explicitly.
-        
+        Call this function to add the data object to the clipboard. You may
+        call this function repeatedly after having cleared the clipboard using
+        Clear().
+
+        After this function has been called, the clipboard owns the data, so do
+        not delete the data explicitly.
+
         @see SetData()
     */
     bool AddData(wxDataObject* data);
 
     /**
-        Clears the global clipboard object and the system's clipboard if possible.
+        Clears the global clipboard object and the system's clipboard if
+        possible.
     */
     void Clear();
 
     /**
-        Call this function to close the clipboard, having opened it with Open().
+        Call this function to close the clipboard, having opened it with
+        Open().
     */
     void Close();
 
     /**
         Flushes the clipboard: this means that the data which is currently on
-        clipboard will stay available even after the application exits (possibly
-        eating memory), otherwise the clipboard will be emptied on exit.
-        Returns @false if the operation is unsuccessful for any reason.
+        clipboard will stay available even after the application exits
+        (possibly eating memory), otherwise the clipboard will be emptied on
+        exit.
+
+        @return @false if the operation is unsuccessful for any reason.
     */
     bool Flush();
 
     /**
-        Call this function to fill @a data with data on the clipboard, if available in
-        the required
-        format. Returns @true on success.
+        Call this function to fill @a data with data on the clipboard, if
+        available in the required format. Returns @true on success.
     */
     bool GetData(wxDataObject& data);
 
     /**
         Returns @true if the clipboard has been opened.
     */
-    bool IsOpened();
+    bool IsOpened() const;
 
     /**
-        Returns @true if there is data which matches the data format of the given data
-        object currently @b available (IsSupported sounds like a misnomer, FIXME: better deprecate this name?) on the clipboard.
+        Returns @true if there is data which matches the data format of the
+        given data object currently @b available on the clipboard.
+
+        @todo The name of this function is misleading. This should be renamed
+              to something that more accurately indicates what it does.
     */
     bool IsSupported(const wxDataFormat& format);
 
     /**
-        Returns @true if we are using the primary selection, @false if clipboard
-        one.
-        See @ref useprimary() UsePrimarySelection for more information.
+        Returns @true if we are using the primary selection, @false if
+        clipboard one.
+
+        @see UsePrimarySelection()
     */
-    bool IsUsingPrimarySelection();
+    bool IsUsingPrimarySelection() const;
 
     /**
-        Call this function to open the clipboard before calling SetData()
-        and GetData().
-        Call Close() when you have finished with the clipboard. You
-        should keep the clipboard open for only a very short time.
-        Returns @true on success. This should be tested (as in the sample shown above).
+        Call this function to open the clipboard before calling SetData() and
+        GetData().
+
+        Call Close() when you have finished with the clipboard. You should keep
+        the clipboard open for only a very short time.
+
+        @return @true on success. This should be tested (as in the sample
+                shown above).
     */
     bool Open();
 
     /**
-        Call this function to set the data object to the clipboard. This function will
-        clear all previous contents in the clipboard, so calling it several times
-        does not make any sense.
-        After this function has been called, the clipboard owns the data, so do not
-        delete
-        the data explicitly.
-        
+        Call this function to set the data object to the clipboard. This
+        function will clear all previous contents in the clipboard, so calling
+        it several times does not make any sense.
+
+        After this function has been called, the clipboard owns the data, so do
+        not delete the data explicitly.
+
         @see AddData()
     */
     bool SetData(wxDataObject* data);
 
     /**
         On platforms supporting it (all X11-based ports), wxClipboard uses the
-        CLIPBOARD X11 selection by default. When this function is called with @true
-        argument, all subsequent clipboard operations will use PRIMARY selection until
-        this function is called again with @false.
-        On the other platforms, there is no PRIMARY selection and so all clipboard
-        operations will fail. This allows to implement the standard X11 handling of the
-        clipboard which consists in copying data to the CLIPBOARD selection only when
-        the user explicitly requests it (i.e. by selection @c "Copy" menu
-        command) but putting the currently selected text into the PRIMARY selection
-        automatically, without overwriting the normal clipboard contents with the
-        currently selected text on the other platforms.
+        CLIPBOARD X11 selection by default. When this function is called with
+        @true, all subsequent clipboard operations will use PRIMARY selection
+        until this function is called again with @false.
+
+        On the other platforms, there is no PRIMARY selection and so all
+        clipboard operations will fail. This allows to implement the standard
+        X11 handling of the clipboard which consists in copying data to the
+        CLIPBOARD selection only when the user explicitly requests it (i.e. by
+        selecting the "Copy" menu command) but putting the currently selected
+        text into the PRIMARY selection automatically, without overwriting the
+        normal clipboard contents with the currently selected text on the other
+        platforms.
     */
     void UsePrimarySelection(bool primary = true);
 };
+