← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/dataobj.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/dataobj.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        dataobj.h
 
3
// Purpose:     interface of wx*DataObject
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: dataobj.h 71610 2012-05-30 19:21:42Z RD $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
 
 
10
/**
 
11
    @class wxDataFormat
 
12
 
 
13
    A wxDataFormat is an encapsulation of a platform-specific format handle
 
14
    which is used by the system for the clipboard and drag and drop operations.
 
15
    The applications are usually only interested in, for example, pasting data
 
16
    from the clipboard only if the data is in a format the program understands
 
17
    and a data format is something which uniquely identifies this format.
 
18
 
 
19
    On the system level, a data format is usually just a number (@c CLIPFORMAT
 
20
    under Windows or @c Atom under X11, for example) and the standard formats
 
21
    are, indeed, just numbers which can be implicitly converted to wxDataFormat.
 
22
    The standard formats are:
 
23
 
 
24
    @beginDefList
 
25
    @itemdef{wxDF_INVALID,
 
26
             An invalid format - used as default argument for functions taking
 
27
             a wxDataFormat argument sometimes.}
 
28
    @itemdef{wxDF_TEXT,
 
29
             Text format (wxString).}
 
30
    @itemdef{wxDF_BITMAP,
 
31
             A bitmap (wxBitmap).}
 
32
    @itemdef{wxDF_METAFILE,
 
33
             A metafile (wxMetafile, Windows only).}
 
34
    @itemdef{wxDF_FILENAME,
 
35
             A list of filenames.}
 
36
    @itemdef{wxDF_HTML,
 
37
             An HTML string. This is currently only valid on Mac and MSW.}
 
38
    @endDefList
 
39
 
 
40
    As mentioned above, these standard formats may be passed to any function
 
41
    taking wxDataFormat argument because wxDataFormat has an implicit
 
42
    conversion from them (or, to be precise from the type
 
43
    @c wxDataFormat::NativeFormat which is the type used by the underlying
 
44
    platform for data formats).
 
45
 
 
46
    Aside the standard formats, the application may also use custom formats
 
47
    which are identified by their names (strings) and not numeric identifiers.
 
48
    Although internally custom format must be created (or @e registered) first,
 
49
    you shouldn't care about it because it is done automatically the first time
 
50
    the wxDataFormat object corresponding to a given format name is created.
 
51
    The only implication of this is that you should avoid having global
 
52
    wxDataFormat objects with non-default constructor because their
 
53
    constructors are executed before the program has time to perform all
 
54
    necessary initialisations and so an attempt to do clipboard format
 
55
    registration at this time will usually lead to a crash!
 
56
 
 
57
    @library{wxbase}
 
58
    @category{dnd}
 
59
 
 
60
    @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject
 
61
*/
 
62
class wxDataFormat
 
63
{
 
64
public:
 
65
    /**
 
66
        Constructs a data format object for one of the standard data formats or
 
67
        an empty data object (use SetType() or SetId() later in this case).
 
68
 
 
69
        @beginWxPerlOnly
 
70
        In wxPerl use Wx::Bitmap->newNative(format).
 
71
        @endWxPerlOnly
 
72
    */
 
73
    wxDataFormat(wxDataFormatId format = wxDF_INVALID);
 
74
 
 
75
    /**
 
76
        Constructs a data format object for a custom format identified by its
 
77
        name @a format.
 
78
 
 
79
        @beginWxPerlOnly
 
80
        In wxPerl use Wx::Bitmap->newUser(format).
 
81
        @endWxPerlOnly
 
82
    */
 
83
    wxDataFormat(const wxString& format);
 
84
 
 
85
    /**
 
86
        Returns the name of a custom format (this function will fail for a
 
87
        standard format).
 
88
    */
 
89
    wxString GetId() const;
 
90
 
 
91
    /**
 
92
        Returns the platform-specific number identifying the format.
 
93
    */
 
94
    wxDataFormatId GetType() const;
 
95
 
 
96
    /**
 
97
        Sets the format to be the custom format identified by the given name.
 
98
    */
 
99
    void SetId(const wxString& format);
 
100
 
 
101
    /**
 
102
        Sets the format to the given value, which should be one of wxDF_XXX
 
103
        constants.
 
104
    */
 
105
    void SetType(wxDataFormatId type);
 
106
 
 
107
    /**
 
108
        Returns @true if the formats are different.
 
109
    */
 
110
    bool operator !=(const wxDataFormat& format) const;
 
111
 
 
112
    /**
 
113
        Returns @true if the formats are different.
 
114
    */
 
115
    bool operator !=(wxDataFormatId format) const;
 
116
 
 
117
    /**
 
118
        Returns @true if the formats are equal.
 
119
    */
 
120
    bool operator ==(const wxDataFormat& format) const;
 
121
 
 
122
    /**
 
123
        Returns @true if the formats are equal.
 
124
    */
 
125
    bool operator ==(wxDataFormatId format) const;
 
126
};
 
127
 
 
128
 
 
129
const wxDataFormat wxFormatInvalid;
 
130
 
 
131
 
 
132
/**
 
133
    @class wxDataObject
 
134
 
 
135
    A wxDataObject represents data that can be copied to or from the clipboard,
 
136
    or dragged and dropped. The important thing about wxDataObject is that this
 
137
    is a 'smart' piece of data unlike 'dumb' data containers such as memory
 
138
    buffers or files. Being 'smart' here means that the data object itself
 
139
    should know what data formats it supports and how to render itself in each
 
140
    of its supported formats.
 
141
 
 
142
    A supported format, incidentally, is exactly the format in which the data
 
143
    can be requested from a data object or from which the data object may be
 
144
    set. In the general case, an object may support different formats on
 
145
    'input' and 'output', i.e. it may be able to render itself in a given
 
146
    format but not be created from data on this format or vice versa.
 
147
    wxDataObject defines the wxDataObject::Direction enumeration type which
 
148
    distinguishes between them.
 
149
 
 
150
    See wxDataFormat documentation for more about formats.
 
151
 
 
152
    Not surprisingly, being 'smart' comes at a price of added complexity. This
 
153
    is reasonable for the situations when you really need to support multiple
 
154
    formats, but may be annoying if you only want to do something simple like
 
155
    cut and paste text.
 
156
 
 
157
    To provide a solution for both cases, wxWidgets has two predefined classes
 
158
    which derive from wxDataObject: wxDataObjectSimple and
 
159
    wxDataObjectComposite. wxDataObjectSimple is the simplest wxDataObject
 
160
    possible and only holds data in a single format (such as HTML or text) and
 
161
    wxDataObjectComposite is the simplest way to implement a wxDataObject that
 
162
    does support multiple formats because it achieves this by simply holding
 
163
    several wxDataObjectSimple objects.
 
164
 
 
165
    So, you have several solutions when you need a wxDataObject class (and you
 
166
    need one as soon as you want to transfer data via the clipboard or drag and
 
167
    drop):
 
168
 
 
169
    -# Use one of the built-in classes.
 
170
        - You may use wxTextDataObject, wxBitmapDataObject wxFileDataObject,
 
171
          wxURLDataObject in the simplest cases when you only need to support
 
172
          one format and your data is either text, bitmap or list of files.
 
173
    -# Use wxDataObjectSimple
 
174
        - Deriving from wxDataObjectSimple is the simplest solution for custom
 
175
          data - you will only support one format and so probably won't be able
 
176
          to communicate with other programs, but data transfer will work in
 
177
          your program (or between different instances of it).
 
178
    -# Use wxDataObjectComposite
 
179
        - This is a simple but powerful solution which allows you to support
 
180
          any number of formats (either standard or custom if you combine it
 
181
          with the previous solution).
 
182
    -# Use wxDataObject directly
 
183
        - This is the solution for maximum flexibility and efficiency, but it
 
184
          is also the most difficult to implement.
 
185
 
 
186
    Please note that the easiest way to use drag and drop and the clipboard
 
187
    with multiple formats is by using wxDataObjectComposite, but it is not the
 
188
    most efficient one as each wxDataObjectSimple would contain the whole data
 
189
    in its respective formats. Now imagine that you want to paste 200 pages of
 
190
    text in your proprietary format, as well as Word, RTF, HTML, Unicode and
 
191
    plain text to the clipboard and even today's computers are in trouble. For
 
192
    this case, you will have to derive from wxDataObject directly and make it
 
193
    enumerate its formats and provide the data in the requested format on
 
194
    demand.
 
195
 
 
196
    Note that neither the GTK+ data transfer mechanisms for clipboard and drag
 
197
    and drop, nor OLE data transfer, @e copies any data until another application
 
198
    actually requests the data. This is in contrast to the 'feel' offered to
 
199
    the user of a program who would normally think that the data resides in the
 
200
    clipboard after having pressed 'Copy' - in reality it is only declared to
 
201
    be @e available.
 
202
 
 
203
    You may also derive your own data object classes from wxCustomDataObject
 
204
    for user-defined types. The format of user-defined data is given as a
 
205
    mime-type string literal, such as "application/word" or "image/png". These
 
206
    strings are used as they are under Unix (so far only GTK+) to identify a
 
207
    format and are translated into their Windows equivalent under Win32 (using
 
208
    the OLE IDataObject for data exchange to and from the clipboard and for
 
209
    drag and drop). Note that the format string translation under Windows is
 
210
    not yet finished.
 
211
 
 
212
    Each class derived directly from wxDataObject must override and implement
 
213
    all of its functions which are pure virtual in the base class. The data
 
214
    objects which only render their data or only set it (i.e. work in only one
 
215
    direction), should return 0 from GetFormatCount().
 
216
 
 
217
    @beginWxPerlOnly
 
218
    This class is not currently usable from wxPerl; you may use
 
219
    Wx::PlDataObjectSimple instead.
 
220
    @endWxPerlOnly
 
221
 
 
222
    @library{wxcore}
 
223
    @category{dnd}
 
224
 
 
225
    @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 
226
         wxTextDataObject, wxBitmapDataObject, wxCustomDataObject,
 
227
         wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget
 
228
*/
 
229
class wxDataObject
 
230
{
 
231
public:
 
232
    enum Direction
 
233
    {
 
234
        /** Format is supported by GetDataHere() */
 
235
        Get  = 0x01,
 
236
 
 
237
        /** Format is supported by SetData() */
 
238
        Set  = 0x02,
 
239
 
 
240
        /**
 
241
            Format is supported by both GetDataHere() and SetData()
 
242
            (unused currently)
 
243
         */
 
244
        Both = 0x03
 
245
    };
 
246
 
 
247
    /**
 
248
        Constructor.
 
249
    */
 
250
    wxDataObject();
 
251
 
 
252
    /**
 
253
        Destructor.
 
254
    */
 
255
    virtual ~wxDataObject();
 
256
 
 
257
    /**
 
258
        Copies all formats supported in the given direction @a dir to the array
 
259
        pointed to by @a formats.
 
260
        There must be enough space for GetFormatCount(dir) formats in it.
 
261
 
 
262
        @beginWxPerlOnly
 
263
        In wxPerl this method only takes the @a dir parameter.  In scalar
 
264
        context it returns the first format in the list, in list
 
265
        context it returns a list containing all the supported
 
266
        formats.
 
267
        @endWxPerlOnly
 
268
    */
 
269
    virtual void GetAllFormats(wxDataFormat* formats,
 
270
                               Direction dir = Get) const = 0;
 
271
 
 
272
    /**
 
273
        The method will write the data of the format @a format to the buffer
 
274
        @a buf.  In other words, copy the data from this object in the given
 
275
        format to the supplied buffer. Returns @true on success, @false on
 
276
        failure.
 
277
    */
 
278
    virtual bool GetDataHere(const wxDataFormat& format, void* buf) const = 0;
 
279
 
 
280
    /**
 
281
        Returns the data size of the given format @a format.
 
282
    */
 
283
    virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
 
284
 
 
285
    /**
 
286
        Returns the number of available formats for rendering or setting the
 
287
        data.
 
288
    */
 
289
    virtual size_t GetFormatCount(Direction dir = Get) const = 0;
 
290
 
 
291
    /**
 
292
        Returns the preferred format for either rendering the data (if @a dir
 
293
        is @c Get, its default value) or for setting it. Usually this will be
 
294
        the native format of the wxDataObject.
 
295
    */
 
296
    virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
 
297
 
 
298
    /**
 
299
        Set the data in the format @a format of the length @a len provided in
 
300
        the buffer @a buf.  In other words, copy length bytes of data from the
 
301
        buffer to this data object.
 
302
 
 
303
        @param format
 
304
            The format for which to set the data.
 
305
        @param len
 
306
            The size of data in bytes.
 
307
        @param buf
 
308
            Non-@NULL pointer to the data.
 
309
        @return
 
310
            @true on success, @false on failure.
 
311
    */
 
312
    virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
 
313
 
 
314
    /**
 
315
       Returns true if this format is supported.
 
316
    */
 
317
    bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
 
318
};
 
319
 
 
320
 
 
321
/**
 
322
    @class wxCustomDataObject
 
323
 
 
324
    wxCustomDataObject is a specialization of wxDataObjectSimple for some
 
325
    application-specific data in arbitrary (either custom or one of the
 
326
    standard ones). The only restriction is that it is supposed that this data
 
327
    can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to
 
328
    make it contain a C++ object (though C struct is fine).
 
329
 
 
330
    By default, wxCustomDataObject stores the data inside in a buffer. To put
 
331
    the data into the buffer you may use either SetData() or TakeData()
 
332
    depending on whether you want the object to make a copy of data or not.
 
333
 
 
334
    This class may be used as is, but if you don't want store the data inside
 
335
    the object but provide it on demand instead, you should override GetSize(),
 
336
    GetData() and SetData() (or may be only the first two or only the last one
 
337
    if you only allow reading/writing the data).
 
338
 
 
339
    @library{wxcore}
 
340
    @category{dnd}
 
341
 
 
342
    @see wxDataObject
 
343
*/
 
344
class wxCustomDataObject : public wxDataObjectSimple
 
345
{
 
346
public:
 
347
    /**
 
348
        The constructor accepts a @a format argument which specifies the
 
349
        (single) format supported by this object. If it isn't set here,
 
350
        wxDataObjectSimple::SetFormat() should be used.
 
351
    */
 
352
    wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
 
353
 
 
354
    /**
 
355
        The destructor will free the data held by the object. Notice that
 
356
        although it calls the virtual Free() function, the base class version
 
357
        will always be called (C++ doesn't allow calling virtual functions from
 
358
        constructors or destructors), so if you override Free(), you should
 
359
        override the destructor in your class as well (which would probably
 
360
        just call the derived class' version of Free()).
 
361
    */
 
362
    virtual ~wxCustomDataObject();
 
363
 
 
364
    /**
 
365
        This function is called to allocate @a size bytes of memory from
 
366
        SetData(). The default version just uses the operator new.
 
367
    */
 
368
    virtual void* Alloc(size_t size);
 
369
 
 
370
    /**
 
371
        This function is called when the data is freed, you may override it to
 
372
        anything you want (or may be nothing at all). The default version calls
 
373
        operator delete[] on the data.
 
374
    */
 
375
    virtual void Free();
 
376
 
 
377
    /**
 
378
        Returns a pointer to the data.
 
379
    */
 
380
    virtual void* GetData() const;
 
381
 
 
382
    /**
 
383
        Returns the data size in bytes.
 
384
    */
 
385
    virtual size_t GetSize() const;
 
386
 
 
387
    /**
 
388
        Set the data. The data object will make an internal copy.
 
389
    */
 
390
    virtual bool SetData(size_t size, const void* data);
 
391
 
 
392
    /**
 
393
        Like SetData(), but doesn't copy the data - instead the object takes
 
394
        ownership of the pointer.
 
395
    */
 
396
    void TakeData(size_t size, void* data);
 
397
};
 
398
 
 
399
 
 
400
 
 
401
/**
 
402
    @class wxDataObjectComposite
 
403
 
 
404
    wxDataObjectComposite is the simplest wxDataObject derivation which may be
 
405
    used to support multiple formats. It contains several wxDataObjectSimple
 
406
    objects and supports any format supported by at least one of them. Only one
 
407
    of these data objects is @e preferred (the first one if not explicitly
 
408
    changed by using the second parameter of Add()) and its format determines
 
409
    the preferred format of the composite data object as well.
 
410
 
 
411
    See wxDataObject documentation for the reasons why you might prefer to use
 
412
    wxDataObject directly instead of wxDataObjectComposite for efficiency
 
413
    reasons.
 
414
 
 
415
    This example shows how a composite data object capable of storing either
 
416
    bitmaps or file names (presumably of bitmap files) can be initialized and
 
417
    used:
 
418
 
 
419
    @code
 
420
    MyDropTarget::MyDropTarget()
 
421
    {
 
422
        wxDataObjectComposite* dataobj = new wxDataObjectComposite();
 
423
        dataobj->Add(new wxBitmapDataObject(), true);
 
424
        dataobj->Add(new wxFileDataObject());
 
425
        SetDataObject(dataobj);
 
426
    }
 
427
 
 
428
    wxDragResult MyDropTarget::OnData(wxCoord x, wxCoord y,
 
429
                                      wxDragResult defaultDragResult)
 
430
    {
 
431
        wxDragResult dragResult = wxDropTarget::OnData(x, y, defaultDragResult);
 
432
        if ( dragResult == defaultDragResult )
 
433
        {
 
434
            wxDataObjectComposite *
 
435
                dataobjComp = static_cast<wxDataObjectComposite *>(GetDataObject());
 
436
 
 
437
            wxDataFormat format = dataObjects->GetReceivedFormat();
 
438
            wxDataObject *dataobj = dataobjComp->GetObject(format);
 
439
            switch ( format.GetType() )
 
440
            {
 
441
                case wxDF_BITMAP:
 
442
                    {
 
443
                        wxBitmapDataObject *
 
444
                            dataobjBitmap = static_cast<wxBitmapDataObject *>(dataobj);
 
445
 
 
446
                        ... use dataobj->GetBitmap() ...
 
447
                    }
 
448
                    break;
 
449
 
 
450
                case wxDF_FILENAME:
 
451
                    {
 
452
                        wxFileDataObject *
 
453
                            dataobjFile = static_cast<wxFileDataObject *>(dataobj);
 
454
 
 
455
                        ... use dataobj->GetFilenames() ...
 
456
                    }
 
457
                    break;
 
458
 
 
459
                default:
 
460
                    wxFAIL_MSG( "unexpected data object format" );
 
461
            }
 
462
        }
 
463
 
 
464
        return dragResult;
 
465
    }
 
466
    @endcode
 
467
 
 
468
    @library{wxcore}
 
469
    @category{dnd}
 
470
 
 
471
    @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 
472
         wxTextDataObject, wxBitmapDataObject
 
473
*/
 
474
class wxDataObjectComposite : public wxDataObject
 
475
{
 
476
public:
 
477
    /**
 
478
        The default constructor.
 
479
    */
 
480
    wxDataObjectComposite();
 
481
 
 
482
    /**
 
483
        Adds the @a dataObject to the list of supported objects and it becomes
 
484
        the preferred object if @a preferred is @true.
 
485
    */
 
486
    void Add(wxDataObjectSimple* dataObject, bool preferred = false);
 
487
 
 
488
    /**
 
489
        Report the format passed to the SetData() method.  This should be the
 
490
        format of the data object within the composite that received data from
 
491
        the clipboard or the DnD operation.  You can use this method to find
 
492
        out what kind of data object was received.
 
493
    */
 
494
    wxDataFormat GetReceivedFormat() const;
 
495
 
 
496
    /**
 
497
        Returns the pointer to the object which supports the passed format for
 
498
        the specified direction.
 
499
 
 
500
        @NULL is returned if the specified @a format is not supported for this
 
501
        direction @a dir. The returned pointer is owned by wxDataObjectComposite
 
502
        itself and shouldn't be deleted by caller.
 
503
 
 
504
        @since 2.9.1
 
505
    */
 
506
    wxDataObjectSimple *GetObject(const wxDataFormat& format,
 
507
                                  wxDataObject::Direction dir = wxDataObject::Get) const;
 
508
};
 
509
 
 
510
 
 
511
 
 
512
/**
 
513
    @class wxDataObjectSimple
 
514
 
 
515
    This is the simplest possible implementation of the wxDataObject class.
 
516
    The data object of (a class derived from) this class only supports
 
517
    <strong>one format</strong>, so the number of virtual functions to
 
518
    be implemented is reduced.
 
519
 
 
520
    Notice that this is still an abstract base class and cannot be used
 
521
    directly, it must be derived. The objects supporting rendering the data
 
522
    must override GetDataSize() and GetDataHere() while the objects which may
 
523
    be set must override SetData(). Of course, the objects supporting both
 
524
    operations must override all three methods.
 
525
 
 
526
    @beginWxPerlOnly
 
527
    In wxPerl, you need to derive your data object class from
 
528
    Wx::PlDataObjectSimple.
 
529
    @endWxPerlOnly
 
530
 
 
531
    @library{wxcore}
 
532
    @category{dnd}
 
533
 
 
534
    @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 
535
         wxTextDataObject, wxBitmapDataObject
 
536
*/
 
537
class wxDataObjectSimple : public wxDataObject
 
538
{
 
539
public:
 
540
    /**
 
541
        Constructor accepts the supported format (none by default) which may
 
542
        also be set later with SetFormat().
 
543
    */
 
544
    wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 
545
 
 
546
    /**
 
547
        Copy the data to the buffer, return @true on success.
 
548
        Must be implemented in the derived class if the object supports rendering
 
549
        its data.
 
550
    */
 
551
    virtual bool GetDataHere(void* buf) const;
 
552
 
 
553
    /**
 
554
        Gets the size of our data. Must be implemented in the derived class if
 
555
        the object supports rendering its data.
 
556
    */
 
557
    virtual size_t GetDataSize() const;
 
558
 
 
559
    /**
 
560
        Returns the (one and only one) format supported by this object.
 
561
        It is assumed that the format is supported in both directions.
 
562
    */
 
563
    const wxDataFormat& GetFormat() const;
 
564
 
 
565
    /**
 
566
        Copy the data from the buffer, return @true on success.
 
567
        Must be implemented in the derived class if the object supports setting
 
568
        its data.
 
569
    */
 
570
    virtual bool SetData(size_t len, const void* buf);
 
571
 
 
572
    /**
 
573
        Sets the supported format.
 
574
    */
 
575
    void SetFormat(const wxDataFormat& format);
 
576
};
 
577
 
 
578
 
 
579
 
 
580
/**
 
581
    @class wxBitmapDataObject
 
582
 
 
583
    wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It
 
584
    can be used without change to paste data into the wxClipboard or a
 
585
    wxDropSource. A user may wish to derive a new class from this class for
 
586
    providing a bitmap on-demand in order to minimize memory consumption when
 
587
    offering data in several formats, such as a bitmap and GIF.
 
588
 
 
589
    This class may be used as is, but GetBitmap() may be overridden to increase
 
590
    efficiency.
 
591
 
 
592
    @library{wxcore}
 
593
    @category{dnd}
 
594
 
 
595
    @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 
596
         wxTextDataObject, wxDataObject
 
597
*/
 
598
class wxBitmapDataObject : public wxDataObjectSimple
 
599
{
 
600
public:
 
601
    /**
 
602
        Constructor, optionally passing a bitmap (otherwise use SetBitmap()
 
603
        later).
 
604
    */
 
605
    wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap);
 
606
 
 
607
    /**
 
608
        Returns the bitmap associated with the data object. You may wish to
 
609
        override this method when offering data on-demand, but this is not
 
610
        required by wxWidgets' internals. Use this method to get data in bitmap
 
611
        form from the wxClipboard.
 
612
    */
 
613
    virtual wxBitmap GetBitmap() const;
 
614
 
 
615
    /**
 
616
        Sets the bitmap associated with the data object. This method is called
 
617
        when the data object receives data. Usually there will be no reason to
 
618
        override this function.
 
619
    */
 
620
    virtual void SetBitmap(const wxBitmap& bitmap);
 
621
};
 
622
 
 
623
 
 
624
 
 
625
/**
 
626
    @class wxURLDataObject
 
627
 
 
628
    wxURLDataObject is a wxDataObject containing an URL and can be used e.g.
 
629
    when you need to put an URL on or retrieve it from the clipboard:
 
630
 
 
631
    @code
 
632
    wxTheClipboard->SetData(new wxURLDataObject(url));
 
633
    @endcode
 
634
 
 
635
    @note This class is derived from wxDataObjectComposite on Windows rather
 
636
          than wxTextDataObject on all other platforms.
 
637
 
 
638
    @library{wxcore}
 
639
    @category{dnd}
 
640
 
 
641
    @see @ref overview_dnd, wxDataObject
 
642
*/
 
643
class wxURLDataObject: public wxTextDataObject
 
644
{
 
645
public:
 
646
    /**
 
647
        Constructor, may be used to initialize the URL. If @a url is empty,
 
648
        SetURL() can be used later.
 
649
    */
 
650
    wxURLDataObject(const wxString& url = wxEmptyString);
 
651
 
 
652
    /**
 
653
        Returns the URL stored by this object, as a string.
 
654
    */
 
655
    wxString GetURL() const;
 
656
 
 
657
    /**
 
658
        Sets the URL stored by this object.
 
659
    */
 
660
    void SetURL(const wxString& url);
 
661
};
 
662
 
 
663
 
 
664
/**
 
665
    @class wxTextDataObject
 
666
 
 
667
    wxTextDataObject is a specialization of wxDataObjectSimple for text data.
 
668
    It can be used without change to paste data into the wxClipboard or a
 
669
    wxDropSource. A user may wish to derive a new class from this class for
 
670
    providing text on-demand in order to minimize memory consumption when
 
671
    offering data in several formats, such as plain text and RTF because by
 
672
    default the text is stored in a string in this class, but it might as well
 
673
    be generated when requested. For this, GetTextLength() and GetText() will
 
674
    have to be overridden.
 
675
 
 
676
    Note that if you already have the text inside a string, you will not
 
677
    achieve any efficiency gain by overriding these functions because copying
 
678
    wxStrings is already a very efficient operation (data is not actually
 
679
    copied because wxStrings are reference counted).
 
680
 
 
681
    @library{wxcore}
 
682
    @category{dnd}
 
683
 
 
684
    @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 
685
         wxBitmapDataObject
 
686
*/
 
687
class wxTextDataObject : public wxDataObjectSimple
 
688
{
 
689
public:
 
690
    /**
 
691
        Constructor, may be used to initialise the text (otherwise SetText()
 
692
        should be used later).
 
693
    */
 
694
    wxTextDataObject(const wxString& text = wxEmptyString);
 
695
 
 
696
    /**
 
697
        Returns the text associated with the data object. You may wish to
 
698
        override this method when offering data on-demand, but this is not
 
699
        required by wxWidgets' internals. Use this method to get data in text
 
700
        form from the wxClipboard.
 
701
    */
 
702
    virtual wxString GetText() const;
 
703
 
 
704
    /**
 
705
        Returns the data size. By default, returns the size of the text data
 
706
        set in the constructor or using SetText(). This can be overridden to
 
707
        provide text size data on-demand. It is recommended to return the text
 
708
        length plus 1 for a trailing zero, but this is not strictly required.
 
709
    */
 
710
    virtual size_t GetTextLength() const;
 
711
 
 
712
    /**
 
713
        Returns 2 under wxMac and wxGTK, where text data coming from the
 
714
        clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text
 
715
        (@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1).
 
716
 
 
717
        Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode
 
718
        (@c wxUSE_UNICODE==0).
 
719
    */
 
720
    virtual size_t GetFormatCount(wxDataObject::Direction dir = wxDataObject::Get) const;
 
721
 
 
722
    /**
 
723
        Returns the preferred format supported by this object.
 
724
 
 
725
        This is @c wxDF_TEXT or @c wxDF_UNICODETEXT depending on the platform
 
726
        and from the build mode (i.e. from @c wxUSE_UNICODE).
 
727
    */
 
728
    const wxDataFormat& GetFormat() const;
 
729
 
 
730
    /**
 
731
        Returns all the formats supported by wxTextDataObject.
 
732
 
 
733
        Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
 
734
        under other ports returns only one of the two, depending on the build mode.
 
735
    */
 
736
    virtual void GetAllFormats(wxDataFormat* formats,
 
737
                               wxDataObject::Direction dir = wxDataObject::Get) const;
 
738
 
 
739
    /**
 
740
        Sets the text associated with the data object. This method is called
 
741
        when the data object receives the data and, by default, copies the text
 
742
        into the member variable. If you want to process the text on the fly
 
743
        you may wish to override this function.
 
744
    */
 
745
    virtual void SetText(const wxString& strText);
 
746
};
 
747
 
 
748
 
 
749
 
 
750
/**
 
751
    @class wxFileDataObject
 
752
 
 
753
    wxFileDataObject is a specialization of wxDataObject for file names. The
 
754
    program works with it just as if it were a list of absolute file names, but
 
755
    internally it uses the same format as Explorer and other compatible
 
756
    programs under Windows or GNOME/KDE filemanager under Unix which makes it
 
757
    possible to receive files from them using this class.
 
758
 
 
759
    @warning Under all non-Windows platforms this class is currently
 
760
             "input-only", i.e. you can receive the files from another
 
761
             application, but copying (or dragging) file(s) from a wxWidgets
 
762
             application is not currently supported. PS: GTK2 should work as
 
763
             well.
 
764
 
 
765
    @library{wxcore}
 
766
    @category{dnd}
 
767
 
 
768
    @see wxDataObject, wxDataObjectSimple, wxTextDataObject,
 
769
         wxBitmapDataObject, wxDataObject
 
770
*/
 
771
class wxFileDataObject : public wxDataObjectSimple
 
772
{
 
773
public:
 
774
    /**
 
775
        Constructor.
 
776
    */
 
777
    wxFileDataObject();
 
778
 
 
779
    /**
 
780
        Adds a file to the file list represented by this data object (Windows only).
 
781
    */
 
782
    void AddFile(const wxString& file);
 
783
 
 
784
    /**
 
785
        Returns the array of file names.
 
786
    */
 
787
    const wxArrayString& GetFilenames() const;
 
788
};
 
789
 
 
790
/**
 
791
    @class wxHTMLDataObject
 
792
 
 
793
    wxHTMLDataObject is used for working with HTML-formatted text.
 
794
    
 
795
    @library{wxcore}
 
796
    @category{dnd}
 
797
 
 
798
    @see wxDataObject, wxDataObjectSimple
 
799
*/
 
800
class wxHTMLDataObject : public wxDataObjectSimple
 
801
{
 
802
public:
 
803
    /**
 
804
        Constructor.
 
805
    */
 
806
    wxHTMLDataObject(const wxString& html = wxEmptyString);
 
807
 
 
808
    /**
 
809
        Returns the HTML string.
 
810
    */
 
811
    virtual wxString GetHTML() const;
 
812
    
 
813
    /**
 
814
        Sets the HTML string.
 
815
    */
 
816
    virtual void SetHTML(const wxString& html);
 
817
};