]> git.saurik.com Git - wxWidgets.git/blobdiff - wxPython/src/_dataobj.i
Update ReST docs
[wxWidgets.git] / wxPython / src / _dataobj.i
index cf6baf07ef77ae11778a4fe0b080003e47c83503..a0c3428c20b11e66e21897c120ff2df8e8fc4a21 100644 (file)
@@ -71,7 +71,7 @@ The standard format IDs are:
                         Windows and non-unicode builds
     ================    =====================================
 
-Aside the standard formats, the application may also use custom
+Besies the standard formats, the application may also use custom
 formats which are identified by their names (strings) and not numeric
 identifiers. Although internally custom format must be created (or
 registered) first, you shouldn\'t care about it because it is done
@@ -122,6 +122,9 @@ standard format).", "");
     DocDeclStr(
         void , SetId(const wxString& format),
         "Sets the format to be the custom format identified by the given name.", "");    
+
+    %property(Id, GetId, SetId, doc="See `GetId` and `SetId`");
+    %property(Type, GetType, SetType, doc="See `GetType` and `SetType`");
 };
 
 
@@ -230,26 +233,22 @@ data.", "");
     
 
 
-    // return all formats in the provided array (of size GetFormatCount())
-    //virtual void GetAllFormats(wxDataFormat *formats,
-    //                           Direction dir = Get) const;
-    DocAStr(GetAllFormats,
-            "GetAllFormats(self, int dir=Get) -> [formats]",
-            "Returns a list of all the wx.DataFormats that this dataobject supports
-in the given direction.", "");
     %extend {
+        DocAStr(GetAllFormats,
+                "GetAllFormats(self, int dir=Get) -> [formats]",
+                "Returns a list of all the wx.DataFormats that this dataobject supports
+in the given direction.", "");
         PyObject* GetAllFormats(Direction dir = Get) {
             size_t count = self->GetFormatCount(dir);
             wxDataFormat* formats = new wxDataFormat[count];
             self->GetAllFormats(formats, dir);
 
-            bool blocked = wxPyBeginBlockThreads();
+            wxPyBlock_t blocked = wxPyBeginBlockThreads();
             PyObject* list = PyList_New(count);
             for (size_t i=0; i<count; i++) {
                 wxDataFormat* format = new wxDataFormat(formats[i]);
-                PyObject* obj = wxPyConstructObject((void*)format, wxT("wxDataFormat"), True);
-                PyList_Append(list, obj);
-                Py_DECREF(obj);
+                PyObject* obj = wxPyConstructObject((void*)format, wxT("wxDataFormat"), true);
+                PyList_SET_ITEM(list, i, obj); // PyList_SET_ITEM steals a reference
             }            
             wxPyEndBlockThreads(blocked);
             delete [] formats;
@@ -263,16 +262,15 @@ in the given direction.", "");
     // True if data copied successfully, False otherwise
     // virtual bool GetDataHere(const wxDataFormat& format, void *buf) const;
 
-    DocAStr(GetDataHere,
-            "GetDataHere(self, DataFormat format) -> String",
-            "Get the data bytes in the specified format, returns None on failure.
-", "
-:todo: This should use the python buffer interface isntead...");
     %extend {
+        DocAStr(GetDataHere,
+                "GetDataHere(self, DataFormat format) -> String",
+                "Get the data bytes in the specified format, returns None on failure.", "
+:todo: This should use the python buffer interface isntead...");
         PyObject* GetDataHere(const wxDataFormat& format) {
             PyObject* rval = NULL;
             size_t size = self->GetDataSize(format);            
-            bool blocked = wxPyBeginBlockThreads();
+            wxPyBlock_t blocked = wxPyBeginBlockThreads();
             if (size) {
                 char* buf = new char[size];
                 if (self->GetDataHere(format, buf)) 
@@ -301,20 +299,25 @@ in the given direction.", "");
     %extend {
         bool SetData(const wxDataFormat& format, PyObject* data) {
             bool rval;
-            bool blocked = wxPyBeginBlockThreads();
+            wxPyBlock_t blocked = wxPyBeginBlockThreads();
             if (PyString_Check(data)) {
                 rval = self->SetData(format, PyString_Size(data), PyString_AsString(data));
             }
             else {
                 // raise a TypeError if not a string
                 PyErr_SetString(PyExc_TypeError, "String expected.");
-                rval = False;
+                rval = false;
             }
             wxPyEndBlockThreads(blocked);
             return rval;
         }
     }
     
+    %property(AllFormats, GetAllFormats, doc="See `GetAllFormats`");
+    %property(DataHere, GetDataHere, doc="See `GetDataHere`");
+    %property(DataSize, GetDataSize, doc="See `GetDataSize`");
+    %property(FormatCount, GetFormatCount, doc="See `GetFormatCount`");
+    %property(PreferredFormat, GetPreferredFormat, doc="See `GetPreferredFormat`");
 
 };
 
@@ -354,16 +357,16 @@ assumed that the format is supported in both directions.", "");
 
 
     
-    DocAStr(GetDataHere,
-            "GetDataHere(self) -> String",
-            "Returns the data bytes from the data object as a string, returns None
+    %extend {
+        DocAStr(GetDataHere,
+                "GetDataHere(self) -> String",
+                "Returns the data bytes from the data object as a string, returns None
 on failure.  Must be implemented in the derived class if the object
 supports rendering its data.", "");
-    %extend {
         PyObject* GetDataHere() {
             PyObject* rval = NULL;
             size_t size = self->GetDataSize();            
-            bool blocked = wxPyBeginBlockThreads();
+            wxPyBlock_t blocked = wxPyBeginBlockThreads();
             if (size) {
                 char* buf = new char[size];
                 if (self->GetDataHere(buf)) 
@@ -380,28 +383,29 @@ supports rendering its data.", "");
     }
 
     
-    DocAStr(SetData,
-            "SetData(self, String data) -> bool",
-            "Copy the data value to the data object.  Must be implemented in the
+    %extend {
+        DocAStr(SetData,
+                "SetData(self, String data) -> bool",
+                "Copy the data value to the data object.  Must be implemented in the
 derived class if the object supports setting its data.
 ", "");
-    %extend {
         bool SetData(PyObject* data) {
             bool rval;
-            bool blocked = wxPyBeginBlockThreads();
+            wxPyBlock_t blocked = wxPyBeginBlockThreads();
             if (PyString_Check(data)) {
                 rval = self->SetData(PyString_Size(data), PyString_AsString(data));
             }
             else {
                 // raise a TypeError if not a string
                 PyErr_SetString(PyExc_TypeError, "String expected.");
-                rval = False;
+                rval = false;
             }
             wxPyEndBlockThreads(blocked);
             return rval;
         }
     }
     
+    %property(Format, GetFormat, SetFormat, doc="See `GetFormat` and `SetFormat`");
 };
 
 
@@ -415,7 +419,7 @@ public:
 
     DEC_PYCALLBACK_SIZET__const(GetDataSize);
     bool GetDataHere(void *buf) const;
-    bool SetData(size_t len, const void *buf) const;
+    bool SetData(size_t len, const void *buf);
     PYPRIVATE;
 };
 
@@ -427,8 +431,8 @@ bool wxPyDataObjectSimple::GetDataHere(void *buf) const {
     // return either a string or None and then act appropriately with the
     // C++ version.
 
-    bool rval = False;
-    bool blocked = wxPyBeginBlockThreads();
+    bool rval = false;
+    wxPyBlock_t blocked = wxPyBeginBlockThreads();
     if (wxPyCBH_findCallback(m_myInst, "GetDataHere")) {
         PyObject* ro;
         ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("()"));
@@ -443,11 +447,11 @@ bool wxPyDataObjectSimple::GetDataHere(void *buf) const {
     return rval;
 }
 
-bool wxPyDataObjectSimple::SetData(size_t len, const void *buf) const{
+bool wxPyDataObjectSimple::SetData(size_t len, const void *buf) {
     // For this one we simply need to make a string from buf and len
     // and send it to the Python method.
-    bool rval = False;
-    bool blocked = wxPyBeginBlockThreads();
+    bool rval = false;
+    wxPyBlock_t blocked = wxPyBeginBlockThreads();
     if (wxPyCBH_findCallback(m_myInst, "SetData")) {
         PyObject* data = PyString_FromStringAndSize((char*)buf, len);
         rval = wxPyCBH_callCallback(m_myInst, Py_BuildValue("(O)", data));
@@ -521,14 +525,23 @@ class wxDataObjectComposite : public wxDataObject {
 public:
     wxDataObjectComposite();
 
-    %apply SWIGTYPE *DISOWN { wxDataObjectSimple *dataObject };
+    %disownarg( wxDataObjectSimple *dataObject );
     
     DocDeclStr(
-        void , Add(wxDataObjectSimple *dataObject, bool preferred = False),
+        void , Add(wxDataObjectSimple *dataObject, bool preferred = false),
         "Adds the dataObject to the list of supported objects and it becomes
 the preferred object if preferred is True.", "");
     
-    %clear wxDataObjectSimple *dataObject;
+    %cleardisown( wxDataObjectSimple *dataObject );
+
+    DocDeclStr(
+        wxDataFormat , GetReceivedFormat() const,
+        "Report the format passed to the `SetData` method.  This should be the
+format of the data object within the composite that recieved data from
+the clipboard or the DnD operation.  You can use this method to find
+out what kind of data object was recieved.", "");
+    
+    %property(ReceivedFormat, GetReceivedFormat, doc="See `GetReceivedFormat`");
 };
 
 //---------------------------------------------------------------------------
@@ -572,6 +585,8 @@ text into the member variable. If you want to process the text on the
 fly you may wish to override this function (via
 `wx.PyTextDataObject`.)", "");
     
+    %property(Text, GetText, SetText, doc="See `GetText` and `SetText`");
+    %property(TextLength, GetTextLength, doc="See `GetTextLength`");
 };
 
 
@@ -646,6 +661,7 @@ internals. Use this method to get data in bitmap form from the
 when the data object receives data. Usually there will be no reason to
 override this function.", "");
     
+    %property(Bitmap, GetBitmap, SetBitmap, doc="See `GetBitmap` and `SetBitmap`");
 };
 
 
@@ -665,7 +681,7 @@ public:
 
 wxBitmap wxPyBitmapDataObject::GetBitmap() const {
     wxBitmap* rval = &wxNullBitmap;
-    bool blocked = wxPyBeginBlockThreads();
+    wxPyBlock_t blocked = wxPyBeginBlockThreads();
     if (wxPyCBH_findCallback(m_myInst, "GetBitmap")) {
         PyObject* ro;
         wxBitmap* ptr;
@@ -681,9 +697,9 @@ wxBitmap wxPyBitmapDataObject::GetBitmap() const {
 }
  
 void wxPyBitmapDataObject::SetBitmap(const wxBitmap& bitmap) {
-    bool blocked = wxPyBeginBlockThreads();
+    wxPyBlock_t blocked = wxPyBeginBlockThreads();
     if (wxPyCBH_findCallback(m_myInst, "SetBitmap")) {
-        PyObject* bo = wxPyConstructObject((void*)&bitmap, wxT("wxBitmap"), False);
+        PyObject* bo = wxPyConstructObject((void*)&bitmap, wxT("wxBitmap"), false);
         wxPyCBH_callCallback(m_myInst, Py_BuildValue("(O)", bo));
         Py_DECREF(bo);
     }
@@ -717,13 +733,7 @@ file names. The program works with it just as if it were a list of
 absolute file names, but internally it uses the same format as
 Explorer and other compatible programs under Windows or GNOME/KDE
 filemanager under Unix which makes it possible to receive files from
-them using this class.
-
-:Warning: Under all non-Windows platforms this class is currently
-    \"input-only\", i.e. you can receive the files from another
-    application, but copying (or dragging) file(s) from a wxWidgets
-    application is not currently supported.
-", "");
+them using this class.", "");
 
 class wxFileDataObject : public wxDataObjectSimple
 {
@@ -741,6 +751,7 @@ public:
         void , AddFile(const wxString &filename),
         "Adds a file to the list of files represented by this data object.", "");
     
+    %property(Filenames, GetFilenames, doc="See `GetFilenames`");
 };
 
 //---------------------------------------------------------------------------
@@ -754,23 +765,30 @@ data object.", "");
 
 class wxCustomDataObject : public wxDataObjectSimple {
 public:
-    wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
-
+    %nokwargs wxCustomDataObject;
+    wxCustomDataObject(const wxDataFormat& format);
+    %extend {
+        wxCustomDataObject(const wxString& formatName) {
+            return new wxCustomDataObject(wxDataFormat(formatName));
+        }
+    }
+    wxCustomDataObject();
+    
     
-    DocAStr(SetData,
-            "SetData(self, String data) -> bool",
-            "Copy the data value to the data object.", "");
     %extend {
+        DocAStr(SetData,
+                "SetData(self, String data) -> bool",
+                "Copy the data value to the data object.", "");
         bool SetData(PyObject* data) {
             bool rval;
-            bool blocked = wxPyBeginBlockThreads();
+            wxPyBlock_t blocked = wxPyBeginBlockThreads();
             if (PyString_Check(data)) {
                 rval = self->SetData(PyString_Size(data), PyString_AsString(data));
             }
             else {
                 // raise a TypeError if not a string
                 PyErr_SetString(PyExc_TypeError, "String expected.");
-                rval = False;
+                rval = false;
             }
             wxPyEndBlockThreads(blocked);
             return rval;
@@ -783,17 +801,22 @@ public:
         "Get the size of the data.", "");
     
 
-    DocAStr(GetData,
-            "GetData(self) -> String",
-            "Returns the data bytes from the data object as a string.", "");
     %extend {
+        DocAStr(GetData,
+                "GetData(self) -> String",
+                "Returns the data bytes from the data object as a string.", "");
         PyObject* GetData() {
             PyObject* obj;
-            bool blocked = wxPyBeginBlockThreads();
+            wxPyBlock_t blocked = wxPyBeginBlockThreads();
             obj = PyString_FromStringAndSize((char*)self->GetData(), self->GetSize());
-            wxPyEndBlockThreads(blocked);      
+            wxPyEndBlockThreads(blocked);
+            return obj;
         }
     }
+
+    %property(Data, GetData, SetData, doc="See `GetData` and `SetData`");
+    %property(Size, GetSize, doc="See `GetSize`");
+
 };
 
 
@@ -802,9 +825,9 @@ public:
 DocStr(wxURLDataObject,
 "This data object holds a URL in a format that is compatible with some
 browsers such that it is able to be dragged to or from them.", "");
-class wxURLDataObject : public wxDataObjectComposite {
+class wxURLDataObject : public wxDataObject/*Composite*/ {
 public:
-    wxURLDataObject();
+    wxURLDataObject(const wxString& url = wxPyEmptyString);
 
     DocDeclStr(
         wxString , GetURL(),
@@ -814,6 +837,7 @@ public:
         void , SetURL(const wxString& url),
         "Set the URL.", "");
     
+    %property(URL, GetURL, SetURL, doc="See `GetURL` and `SetURL`");
 };
 
 //---------------------------------------------------------------------------