Updated layout test

[wxWidgets.git] / wxPython / src / _clipbrd.i

diff --git a/wxPython/src/_clipbrd.i b/wxPython/src/_clipbrd.i
index d8d439d904a56fe0032d2717c88fea1d201f53e1..7fd9be453453cedbe48854eac984b727c6b0c814 100644 (file)
--- a/wxPython/src/_clipbrd.i
+++ b/wxPython/src/_clipbrd.i
@@ -19,53 +19,104 @@
 %{
 %}
 
+DocStr(wxClipboard,
+"wx.Clipboard represents the system clipboard and provides methods to
+copy data to it or paste data from it.  Normally, you should only use
+``wx.TheClipboard`` which is a reference to a global wx.Clipboard
+instance.
+
+Call ``wx.TheClipboard``'s `Open` method to get ownership of the
+clipboard. If this operation returns True, you now own the
+clipboard. Call `SetData` to put data on the clipboard, or `GetData`
+to retrieve data from the clipboard.  Call `Close` to close the
+clipboard and relinquish ownership. You should keep the clipboard open
+only momentarily.
+
+:see: `wx.DataObject`
+");
+
 
 
-// wxClipboard represents the system clipboard. Normally, you should use
-// wxTheClipboard which is a global pointer to the (unique) clipboard.
-//
-// Clipboard can be used to copy data to/paste data from. It works together
-// with wxDataObject.
 class wxClipboard : public wxObject {
 public:
-    wxClipboard();
+    DocCtorStr(
+        wxClipboard(),
+        "");
+    
     ~wxClipboard();
 
-    // open the clipboard before Add/SetData() and GetData()
-    virtual bool Open();
 
-    // close the clipboard after Add/SetData() and GetData()
-    virtual void Close();
+    DocDeclStr(
+        virtual bool , Open(),
+        "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.");
+    
 
-    // query whether the clipboard is opened
-    virtual bool IsOpened() const;
+    DocDeclStr(
+        virtual void , Close(),
+        "Closes the clipboard.");
+    
 
-    // add to the clipboard data
-    //
-    // NB: the clipboard owns the pointer and will delete it, so data must be
-    //     allocated on the heap
-    virtual bool AddData( wxDataObject *data );
+    DocDeclStr(
+        virtual bool , IsOpened() const,
+        "Query whether the clipboard is opened");
+    
 
-    // set the clipboard data, this is the same as Clear() followed by
-    // AddData()
-    virtual bool SetData( wxDataObject *data );
 
-    // ask if data in correct format is available
-    virtual bool IsSupported( const wxDataFormat& format );
+    %apply SWIGTYPE *DISOWN { wxDataObject *data };
+    
+    DocDeclStr(
+        virtual bool , AddData( wxDataObject *data ),
+        "Call this function to add the data object to the clipboard. You may
+call this function repeatedly after having cleared the clipboard.
+After this function has been called, the clipboard owns the data, so
+do not delete the data explicitly.
+
+:see: `wx.DataObject`");
+    
 
-    // fill data with data on the clipboard (if available)
-    virtual bool GetData( wxDataObject& data );
+    DocDeclStr(
+        virtual bool , SetData( wxDataObject *data ),
+        "Set the clipboard data, this is the same as `Clear` followed by
+`AddData`.
+
+:see: `wx.DataObject`");
     
-    // clears wxTheClipboard and the system's clipboard if possible
-    virtual void Clear();
 
-    // 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
-    virtual bool Flush();
+    %clear wxDataObject *data;
+    
+    DocDeclStr(
+        virtual bool , IsSupported( const wxDataFormat& format ),
+        "Returns True if the given format is available in the data object(s) on
+the clipboard.");
+
+    DocDeclStr(
+        virtual bool , GetData( wxDataObject& data ),
+        "Call this function to fill data with data on the clipboard, if
+available in the required format. Returns true on success.");
+    
+    
+    DocDeclStr(
+        virtual void , Clear(),
+        "Clears data from the clipboard object and also the system's clipboard
+if possible.");
+    
 
-    // X11 has two clipboards which get selected by this call. Empty on MSW.
-    virtual void UsePrimarySelection( bool primary = FALSE );
+    DocDeclStr(
+        virtual bool , Flush(),
+        "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 unsuccesful for any reason.");
+    
+
+    DocDeclStr(
+        virtual void , UsePrimarySelection( bool primary = True ),
+        "On platforms supporting it (the X11 based platforms), selects the
+so called PRIMARY SELECTION as the clipboard as opposed to the
+normal clipboard, if primary is True.");
 };
 
 
@@ -78,16 +129,19 @@ wxClipboard* const wxTheClipboard;
 //---------------------------------------------------------------------------
 
 
-// helpful class for opening the clipboard and automatically closing it when
-// the locker is destroyed
+DocStr(wxClipboardLocker,
+"A helpful class for opening the clipboard and automatically
+closing it when the locker is destroyed.");
+
 class wxClipboardLocker
 {
 public:
     wxClipboardLocker(wxClipboard *clipboard = NULL);
     ~wxClipboardLocker();
 
-    //bool operator!() const;
-
+    DocStr(__nonzero__,
+           "A ClipboardLocker instance evaluates to True if the clipboard was
+successfully opened.")
     %extend {
         bool __nonzero__()   { return !!(*self); }
     }