PalmOS headers have ssize_t with no sign of it so we have to assume they are always...

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

diff --git a/wxPython/src/_clipbrd.i b/wxPython/src/_clipbrd.i
index d8d439d904a56fe0032d2717c88fea1d201f53e1..1c262b38884f324ae074584eef6fa4f717fa1a62 100644 (file)
--- a/wxPython/src/_clipbrd.i
+++ b/wxPython/src/_clipbrd.i
@@ -19,75 +19,156 @@
 %{
 %}
 
 %{
 %}
 

+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:
 class wxClipboard : public wxObject {
 public:

-    wxClipboard();
+    DocCtorStr(
+        wxClipboard(),
+        "", "");
+    

     ~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.", "");
+    
+
+    DocDeclStr(
+        virtual void , Close(),
+        "Closes the clipboard.", "");
+    

 
 

-    // query whether the clipboard is opened
-    virtual bool IsOpened() const;
+    DocDeclStr(
+        virtual bool , IsOpened() const,
+        "Query whether the clipboard is opened", "");
+    

 
 

-    // 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 );

 
 

-    // set the clipboard data, this is the same as Clear() followed by
-    // AddData()
-    virtual bool SetData( wxDataObject *data );
+    %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`", "");
+    

 
 

-    // ask if data in correct format is available
-    virtual bool IsSupported( const wxDataFormat& format );
+    DocDeclStr(
+        virtual bool , SetData( wxDataObject *data ),
+        "Set the clipboard data, this is the same as `Clear` followed by
+`AddData`.

 
 

-    // fill data with data on the clipboard (if available)
-    virtual bool GetData( wxDataObject& data );
+: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.", "");

 
 

-%immutable;
-wxClipboard* const wxTheClipboard;
-%mutable;

 
 

+    DocDeclStr(
+        static wxClipboard *, Get(),
+        "Returns global instance (wxTheClipboard) of the object.", "");
+    
+};
+
+
+// Previously we just declared wxTheClipboard as a global, but in C++
+// is has been changed to be a macro for wxClipboard::Get, but the
+// swig generated code will try to evaluate it when it assigns to the
+// swig wrapper var so this causes Get to be called too early on
+// wxGTK.  So instead we'll create a Python class that can delay the
+// Get until it is really needed, which is similar in effect to what
+// is really happening on the C++ side too.
+%pythoncode {
+    class _wxPyDelayedInitWrapper(object):
+        def __init__(self, initfunc, *args, **kwargs):
+            self._initfunc = initfunc
+            self._args = args
+            self._kwargs = kwargs
+            self._instance = None
+        def _checkInstance(self):
+            if self._instance is None:
+                self._instance = self._initfunc(*self._args, **self._kwargs)        
+        def __getattr__(self, name):
+            self._checkInstance()
+            return getattr(self._instance, name)
+        def __repr__(self):
+            self._checkInstance()
+            return repr(self._instance)
+    TheClipboard = _wxPyDelayedInitWrapper(Clipboard.Get)
+}

 
 
 //---------------------------------------------------------------------------
 
 
 
 
 //---------------------------------------------------------------------------
 
 

-// 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();
 
 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); }
     }
     %extend {
         bool __nonzero__()   { return !!(*self); }
     }