compilation fix for PCH-less build

[wxWidgets.git] / interface / clipbrd.h

diff --git a/interface/clipbrd.h b/interface/clipbrd.h
index 77e6dac9322124ceaa23b6a4570946a4e5b5110b..307793295c66e9d1a9bc3961823879d4cf4abdf3 100644 (file)
--- a/interface/clipbrd.h
+++ b/interface/clipbrd.h
@@ -6,63 +6,65 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    The backwards compatible access macro that returns the global clipboard
+    object pointer.
+*/
+#define wxTheClipboard
+

 /**
     @class wxClipboard
     @wxheader{clipbrd.h}
 
 /**
     @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
 
     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.
         // 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}
 
     @endcode
 
     @library{wxcore}
     @category{dnd}
 

-    @see @ref overview_wxdndoverview, wxDataObject
+    @see @ref overview_dnd, @ref overview_dataobject, wxDataObject

 */
 class wxClipboard : public wxObject
 {
 public:
     /**
 */
 class wxClipboard : public wxObject
 {
 public:
     /**

-        Constructor.
+        Default constructor.

     */
     wxClipboard();
 
     */
     wxClipboard();
 


@@ -72,38 +74,42 @@ public:
     ~wxClipboard();
 
     /**
     ~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);
 
     /**
         @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();
 
     /**
     */
     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
     */
     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();
 
     /**
     */
     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);
 
     */
     bool GetData(wxDataObject& data);
 


@@ -113,51 +119,60 @@ public:
     bool IsOpened() const;
 
     /**
     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);
 
     /**
     */
     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() const;
 
     /**
     */
     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();
 
     /**
     */
     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
         @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);
 };
     */
     void UsePrimarySelection(bool primary = true);
 };