home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / include / wx / dataobj.h < prev    next >
C/C++ Source or Header  |  2002-08-31  |  19KB  |  481 lines
  1. ///////////////////////////////////////////////////////////////////////////////
  2. // Name:        wx/dataobj.h
  3. // Purpose:     common data object classes
  4. // Author:      Vadim Zeitlin, Robert Roebling
  5. // Modified by:
  6. // Created:     26.05.99
  7. // RCS-ID:      $Id: dataobj.h,v 1.41 2002/08/31 11:29:09 GD Exp $
  8. // Copyright:   (c) wxWindows Team
  9. // Licence:     wxWindows license
  10. ///////////////////////////////////////////////////////////////////////////////
  11.  
  12. #ifndef _WX_DATAOBJ_H_BASE_
  13. #define _WX_DATAOBJ_H_BASE_
  14.  
  15. #if defined(__GNUG__) && !defined(__APPLE__)
  16.     #pragma interface "dataobjbase.h"
  17. #endif
  18.  
  19. // ----------------------------------------------------------------------------
  20. // headers
  21. // ----------------------------------------------------------------------------
  22.  
  23. #include "wx/defs.h"
  24. #include "wx/string.h"
  25. #include "wx/bitmap.h"
  26. #include "wx/list.h"
  27.  
  28. // ============================================================================
  29. /*
  30.    Generic data transfer related classes. The class hierarchy is as follows:
  31.  
  32.                                 - wxDataObject-
  33.                                /               \
  34.                               /                 \
  35.             wxDataObjectSimple                  wxDataObjectComposite
  36.            /           |      \
  37.           /            |       \
  38.    wxTextDataObject    |     wxBitmapDataObject
  39.                        |
  40.                wxCustomDataObject
  41.  
  42. */
  43. // ============================================================================
  44.  
  45. // ----------------------------------------------------------------------------
  46. // wxDataFormat class is declared in platform-specific headers: it represents
  47. // a format for data which may be either one of the standard ones (text,
  48. // bitmap, ...) or a custom one which is then identified by a unique string.
  49. // ----------------------------------------------------------------------------
  50.  
  51. /* the class interface looks like this (pseudo code):
  52.  
  53. class wxDataFormat
  54. {
  55. public:
  56.     typedef <integral type> NativeFormat;
  57.  
  58.     wxDataFormat(NativeFormat format = wxDF_INVALID);
  59.     wxDataFormat(const wxChar *format);
  60.  
  61.     wxDataFormat& operator=(NativeFormat format);
  62.     wxDataFormat& operator=(const wxDataFormat& format);
  63.  
  64.     bool operator==(NativeFormat format) const;
  65.     bool operator!=(NativeFormat format) const;
  66.  
  67.     void SetType(NativeFormat format);
  68.     NativeFormat GetType() const;
  69.  
  70.     wxString GetId() const;
  71.     void SetId(const wxChar *format);
  72. };
  73.  
  74. */
  75.  
  76. #if defined(__WXMSW__)
  77.     #include "wx/msw/ole/dataform.h"
  78. #elif defined(__WXMOTIF__)
  79.     #include "wx/motif/dataform.h"
  80. #elif defined(__WXGTK__)
  81.     #include "wx/gtk/dataform.h"
  82. #elif defined(__WXX11__)
  83.     #include "wx/x11/dataform.h"
  84. #elif defined(__WXMAC__)
  85.     #include "wx/mac/dataform.h"
  86. #elif defined(__WXPM__)
  87.     #include "wx/os2/dataform.h"
  88. #endif
  89.  
  90. // the value for default argument to some functions (corresponds to
  91. // wxDF_INVALID)
  92. extern WXDLLEXPORT const wxDataFormat& wxFormatInvalid;
  93.  
  94. // ----------------------------------------------------------------------------
  95. // wxDataObject represents a piece of data which knows which formats it
  96. // supports and knows how to render itself in each of them - GetDataHere(),
  97. // and how to restore data from the buffer (SetData()).
  98. //
  99. // Although this class may be used directly (i.e. custom classes may be
  100. // derived from it), in many cases it might be simpler to use either
  101. // wxDataObjectSimple or wxDataObjectComposite classes.
  102. //
  103. // A data object may be "read only", i.e. support only GetData() functions or
  104. // "read-write", i.e. support both GetData() and SetData() (in principle, it
  105. // might be "write only" too, but this is rare). Moreover, it doesn't have to
  106. // support the same formats in Get() and Set() directions: for example, a data
  107. // object containing JPEG image might accept BMPs in GetData() because JPEG
  108. // image may be easily transformed into BMP but not in SetData(). Accordingly,
  109. // all methods dealing with formats take an additional "direction" argument
  110. // which is either SET or GET and which tells the function if the format needs
  111. // to be supported by SetData() or GetDataHere().
  112. // ----------------------------------------------------------------------------
  113.  
  114. class WXDLLEXPORT wxDataObjectBase
  115. {
  116. public:
  117.     enum Direction
  118.     {
  119.         Get  = 0x01,    // format is supported by GetDataHere()
  120.         Set  = 0x02,    // format is supported by SetData()
  121.         Both = 0x03     // format is supported by both (unused currently)
  122.     };
  123.  
  124.     // this class is polymorphic, hence it needs a virtual dtor
  125.     virtual ~wxDataObjectBase();
  126.  
  127.     // get the best suited format for rendering our data
  128.     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
  129.  
  130.     // get the number of formats we support
  131.     virtual size_t GetFormatCount(Direction dir = Get) const = 0;
  132.  
  133.     // return all formats in the provided array (of size GetFormatCount())
  134.     virtual void GetAllFormats(wxDataFormat *formats,
  135.                                Direction dir = Get) const = 0;
  136.  
  137.     // get the (total) size of data for the given format
  138.     virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
  139.  
  140.     // copy raw data (in the specified format) to the provided buffer, return
  141.     // TRUE if data copied successfully, FALSE otherwise
  142.     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const = 0;
  143.  
  144.     // get data from the buffer of specified length (in the given format),
  145.     // return TRUE if the data was read successfully, FALSE otherwise
  146.     virtual bool SetData(const wxDataFormat& WXUNUSED(format),
  147.                          size_t WXUNUSED(len), const void * WXUNUSED(buf))
  148.     {
  149.         return FALSE;
  150.     }
  151.  
  152.     // returns TRUE if this format is supported
  153.     bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
  154. };
  155.  
  156. // ----------------------------------------------------------------------------
  157. // include the platform-specific declarations of wxDataObject
  158. // ----------------------------------------------------------------------------
  159.  
  160. #if defined(__WXMSW__)
  161.     #include "wx/msw/ole/dataobj.h"
  162. #elif defined(__WXMOTIF__)
  163.     #include "wx/motif/dataobj.h"
  164. #elif defined(__WXX11__)
  165.     #include "wx/x11/dataobj.h"
  166. #elif defined(__WXGTK__)
  167.     #include "wx/gtk/dataobj.h"
  168. #elif defined(__WXMAC__)
  169.     #include "wx/mac/dataobj.h"
  170. #elif defined(__WXPM__)
  171.     #include "wx/os2/dataobj.h"
  172. #elif defined(__WXSTUBS__)
  173.     #include "wx/stubs/dnd.h"
  174. #endif
  175.  
  176. // ----------------------------------------------------------------------------
  177. // wxDataObjectSimple is a wxDataObject which only supports one format (in
  178. // both Get and Set directions, but you may return FALSE from GetDataHere() or
  179. // SetData() if one of them is not supported). This is the simplest possible
  180. // wxDataObject implementation.
  181. //
  182. // This is still an "abstract base class" (although it doesn't have any pure
  183. // virtual functions), to use it you should derive from it and implement
  184. // GetDataSize(), GetDataHere() and SetData() functions because the base class
  185. // versions don't do anything - they just return "not implemented".
  186. //
  187. // This class should be used when you provide data in only one format (no
  188. // conversion to/from other formats), either a standard or a custom one.
  189. // Otherwise, you should use wxDataObjectComposite or wxDataObject directly.
  190. // ----------------------------------------------------------------------------
  191.  
  192. class WXDLLEXPORT wxDataObjectSimple : public wxDataObject
  193. {
  194. public:
  195.     // ctor takes the format we support, but it can also be set later with
  196.     // SetFormat()
  197.     wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid)
  198.         : m_format(format)
  199.         {
  200.         }
  201.  
  202.     // get/set the format we support
  203.     const wxDataFormat& GetFormat() const { return m_format; }
  204.     void SetFormat(const wxDataFormat& format) { m_format = format; }
  205.  
  206.     // virtual functions to override in derived class (the base class versions
  207.     // just return "not implemented")
  208.     // -----------------------------------------------------------------------
  209.  
  210.     // get the size of our data
  211.     virtual size_t GetDataSize() const
  212.         { return 0; }
  213.  
  214.     // copy our data to the buffer
  215.     virtual bool GetDataHere(void *WXUNUSED(buf)) const
  216.         { return FALSE; }
  217.  
  218.     // copy data from buffer to our data
  219.     virtual bool SetData(size_t WXUNUSED(len), const void *WXUNUSED(buf))
  220.         { return FALSE; }
  221.  
  222.     // implement base class pure virtuals
  223.     // ----------------------------------
  224.     virtual wxDataFormat GetPreferredFormat(wxDataObjectBase::Direction WXUNUSED(dir) = Get) const
  225.         { return m_format; }
  226.     virtual size_t GetFormatCount(wxDataObjectBase::Direction WXUNUSED(dir) = Get) const
  227.         { return 1; }
  228.     virtual void GetAllFormats(wxDataFormat *formats,
  229.                                wxDataObjectBase::Direction WXUNUSED(dir) = Get) const
  230.         { *formats = m_format; }
  231.     virtual size_t GetDataSize(const wxDataFormat& WXUNUSED(format)) const
  232.         { return GetDataSize(); }
  233.     virtual bool GetDataHere(const wxDataFormat& WXUNUSED(format),
  234.                              void *buf) const
  235.         { return GetDataHere(buf); }
  236.     virtual bool SetData(const wxDataFormat& WXUNUSED(format),
  237.                          size_t len, const void *buf)
  238.         { return SetData(len, buf); }
  239.  
  240. private:
  241.     // the one and only format we support
  242.     wxDataFormat m_format;
  243. };
  244.  
  245. // ----------------------------------------------------------------------------
  246. // wxDataObjectComposite is the simplest way to implement wxDataObject
  247. // supporting multiple formats. It contains several wxDataObjectSimple and
  248. // supports all formats supported by any of them.
  249. //
  250. // This class shouldn't be (normally) derived from, but may be used directly.
  251. // If you need more flexibility than what it provides, you should probably use
  252. // wxDataObject directly.
  253. // ----------------------------------------------------------------------------
  254.  
  255. WX_DECLARE_EXPORTED_LIST(wxDataObjectSimple, wxSimpleDataObjectList);
  256.  
  257. class WXDLLEXPORT wxDataObjectComposite : public wxDataObject
  258. {
  259. public:
  260.     // ctor
  261.     wxDataObjectComposite();
  262.  
  263.     // add data object (it will be deleted by wxDataObjectComposite, hence it
  264.     // must be allocated on the heap) whose format will become the preferred
  265.     // one if preferred == TRUE
  266.     void Add(wxDataObjectSimple *dataObject, bool preferred = FALSE);
  267.  
  268.     // implement base class pure virtuals
  269.     // ----------------------------------
  270.     virtual wxDataFormat GetPreferredFormat(wxDataObjectBase::Direction dir = Get) const;
  271.     virtual size_t GetFormatCount(wxDataObjectBase::Direction dir = Get) const;
  272.     virtual void GetAllFormats(wxDataFormat *formats, wxDataObjectBase::Direction dir = Get) const;
  273.     virtual size_t GetDataSize(const wxDataFormat& format) const;
  274.     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const;
  275.     virtual bool SetData(const wxDataFormat& format, size_t len, const void *buf);
  276.  
  277. protected:
  278.     // returns the pointer to the object which supports this format or NULL
  279.     wxDataObjectSimple *GetObject(const wxDataFormat& format) const;
  280. #if defined(__WXMSW__)
  281.     virtual const void* GetSizeFromBuffer( const void* buffer, size_t* size,
  282.                                            const wxDataFormat& format );
  283.     virtual void* SetSizeInBuffer( void* buffer, size_t size,
  284.                                    const wxDataFormat& format );
  285.     virtual size_t GetBufferOffset( const wxDataFormat& format );
  286. #endif
  287.  
  288. private:
  289.     // the list of all (simple) data objects whose formats we support
  290.     wxSimpleDataObjectList m_dataObjects;
  291.  
  292.     // the index of the preferred one (0 initially, so by default the first
  293.     // one is the preferred)
  294.     size_t m_preferred;
  295. };
  296.  
  297. // ============================================================================
  298. // Standard implementations of wxDataObjectSimple which can be used directly
  299. // (i.e. without having to derive from them) for standard data type transfers.
  300. //
  301. // Note that although all of them can work with provided data, you can also
  302. // override their virtual GetXXX() functions to only provide data on demand.
  303. // ============================================================================
  304.  
  305. // ----------------------------------------------------------------------------
  306. // wxTextDataObject contains text data
  307. // ----------------------------------------------------------------------------
  308.  
  309. class WXDLLEXPORT wxTextDataObject : public wxDataObjectSimple
  310. {
  311. public:
  312.     // ctor: you can specify the text here or in SetText(), or override
  313.     // GetText()
  314.     wxTextDataObject(const wxString& text = wxEmptyString)
  315.         : wxDataObjectSimple(wxUSE_UNICODE?wxDF_UNICODETEXT:wxDF_TEXT),
  316.           m_text(text)
  317.         {
  318.         }
  319.  
  320.     // virtual functions which you may override if you want to provide text on
  321.     // demand only - otherwise, the trivial default versions will be used
  322.     virtual size_t GetTextLength() const { return m_text.Len() + 1; }
  323.     virtual wxString GetText() const { return m_text; }
  324.     virtual void SetText(const wxString& text) { m_text = text; }
  325.  
  326.     // implement base class pure virtuals
  327.     // ----------------------------------
  328.     virtual size_t GetDataSize() const;
  329.     virtual bool GetDataHere(void *buf) const;
  330.     virtual bool SetData(size_t len, const void *buf);
  331.  
  332. private:
  333.     wxString m_text;
  334.  
  335.     // virtual function hiding supression
  336.     size_t GetDataSize(const wxDataFormat& format) const
  337.         { return(wxDataObjectSimple::GetDataSize(format)); }
  338.     bool GetDataHere(const wxDataFormat& format, void *pBuf) const
  339.         { return(wxDataObjectSimple::GetDataHere(format, pBuf)); }
  340.     bool SetData(const wxDataFormat& format, size_t nLen, const void* pBuf)
  341.         { return(wxDataObjectSimple::SetData(format, nLen, pBuf)); }
  342. };
  343.  
  344. // ----------------------------------------------------------------------------
  345. // wxBitmapDataObject contains a bitmap
  346. // ----------------------------------------------------------------------------
  347.  
  348. class WXDLLEXPORT wxBitmapDataObjectBase : public wxDataObjectSimple
  349. {
  350. public:
  351.     // ctor: you can specify the bitmap here or in SetBitmap(), or override
  352.     // GetBitmap()
  353.     wxBitmapDataObjectBase(const wxBitmap& bitmap = wxNullBitmap)
  354.         : wxDataObjectSimple(wxDF_BITMAP), m_bitmap(bitmap)
  355.         {
  356.         }
  357.  
  358.     // virtual functions which you may override if you want to provide data on
  359.     // demand only - otherwise, the trivial default versions will be used
  360.     virtual wxBitmap GetBitmap() const { return m_bitmap; }
  361.     virtual void SetBitmap(const wxBitmap& bitmap) { m_bitmap = bitmap; }
  362.  
  363. protected:
  364.     wxBitmap m_bitmap;
  365. };
  366.  
  367. // ----------------------------------------------------------------------------
  368. // wxFileDataObject contains a list of filenames
  369. //
  370. // NB: notice that this is a "write only" object, it can only be filled with
  371. //     data from drag and drop operation.
  372. // ----------------------------------------------------------------------------
  373.  
  374. class WXDLLEXPORT wxFileDataObjectBase : public wxDataObjectSimple
  375. {
  376. public:
  377.     // ctor: use AddFile() later to fill the array
  378.     wxFileDataObjectBase() : wxDataObjectSimple(wxDF_FILENAME) { }
  379.  
  380.     // get a reference to our array
  381.     const wxArrayString& GetFilenames() const { return m_filenames; }
  382.  
  383.     // the Get() functions do nothing for us
  384.     virtual size_t GetDataSize() const { return 0; }
  385.     virtual bool GetDataHere(void *WXUNUSED(buf)) const { return FALSE; }
  386.  
  387. protected:
  388.     wxArrayString m_filenames;
  389.  
  390. private:
  391.     // Virtual function hiding supression
  392.     size_t GetDataSize(const wxDataFormat& format) const
  393.         { return(wxDataObjectSimple::GetDataSize(format)); }
  394.     bool GetDataHere(const wxDataFormat& format, void* pBuf) const
  395.         { return(wxDataObjectSimple::GetDataHere(format, pBuf)); }
  396. };
  397.  
  398. // ----------------------------------------------------------------------------
  399. // wxCustomDataObject contains arbitrary untyped user data.
  400. //
  401. // It is understood that this data can be copied bitwise.
  402. // ----------------------------------------------------------------------------
  403.  
  404. class WXDLLEXPORT wxCustomDataObject : public wxDataObjectSimple
  405. {
  406. public:
  407.     // if you don't specify the format in the ctor, you can still use
  408.     // SetFormat() later
  409.     wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
  410.  
  411.     // the dtor calls Free()
  412.     virtual ~wxCustomDataObject();
  413.  
  414.     // you can call SetData() to set m_data: it will make a copy of the data
  415.     // you pass - or you can use TakeData() which won't copy anything, but
  416.     // will take ownership of data (i.e. will call Free() on it later)
  417.     void TakeData(size_t size, void *data);
  418.  
  419.     // this function is called to allocate "size" bytes of memory from
  420.     // SetData(). The default version uses operator new[].
  421.     virtual void *Alloc(size_t size);
  422.  
  423.     // this function is called when the data is freed, you may override it to
  424.     // anything you want (or may be nothing at all). The default version calls
  425.     // operator delete[] on m_data
  426.     virtual void Free();
  427.  
  428.     // get data: you may override these functions if you wish to provide data
  429.     // only when it's requested
  430.     virtual size_t GetSize() const { return m_size; }
  431.     virtual void *GetData() const { return m_data; }
  432.  
  433.     // implement base class pure virtuals
  434.     // ----------------------------------
  435.     virtual size_t GetDataSize() const;
  436.     virtual bool GetDataHere(void *buf) const;
  437.     virtual bool SetData(size_t size, const void *buf);
  438.  
  439. private:
  440.     size_t m_size;
  441.     void  *m_data;
  442.  
  443.     // virtual function hiding supression
  444.     size_t GetDataSize(const wxDataFormat& format) const
  445.         { return(wxDataObjectSimple::GetDataSize(format)); }
  446.     bool GetDataHere(const wxDataFormat& format, void* pBuf) const
  447.         { return(wxDataObjectSimple::GetDataHere(format, pBuf)); }
  448.     bool SetData(const wxDataFormat& format, size_t nLen, const void* pBuf)
  449.         { return(wxDataObjectSimple::SetData(format, nLen, pBuf)); }
  450. };
  451.  
  452. // ----------------------------------------------------------------------------
  453. // include platform-specific declarations of wxXXXBase classes
  454. // ----------------------------------------------------------------------------
  455.  
  456. #if defined(__WXMSW__)
  457.     #include "wx/msw/ole/dataobj2.h"
  458.  
  459.     // wxURLDataObject defined in msw/ole/dataobj2.h
  460. #else // !__WXMSW__
  461.     #if defined(__WXGTK__)
  462.         #include "wx/gtk/dataobj2.h"
  463.     #elif defined(__WXX11__)
  464.         #include "wx/x11/dataobj2.h"
  465.     #elif defined(__WXMAC__)
  466.         #include "wx/mac/dataobj2.h"
  467.     #elif defined(__WXPM__)
  468.         #include "wx/os2/dataobj2.h"
  469.     #endif
  470.  
  471.     // wxURLDataObject is simply wxTextDataObject with a different name
  472.     class WXDLLEXPORT wxURLDataObject : public wxTextDataObject
  473.     {
  474.     public:
  475.         wxString GetURL() const { return GetText(); }
  476.         void SetURL(const wxString& url) { SetText(url); }
  477.     };
  478. #endif // __WXMSW__/!__WXMSW__
  479.  
  480. #endif // _WX_DATAOBJ_H_BASE_
  481.