From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/dnd.html | 367 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 367 insertions(+) create mode 100644 doc/html/dnd.html (limited to 'doc/html/dnd.html') diff --git a/doc/html/dnd.html b/doc/html/dnd.html new file mode 100644 index 000000000..16512c0db --- /dev/null +++ b/doc/html/dnd.html @@ -0,0 +1,367 @@ + + + + + +Drag and Drop + + + + + + + +

Drag and Drop

+ + + +

Drag and drop provides a simple visual mechanism which users can use +to transfer information between and within applications. (In the +literature this is referred to as a "direct manipulation model".) Drag +and drop is similar in function to the clipboard's cut-and-paste +mechanism. +

Dragging + +
Dropping + +
The Clipboard + +
Drag and Drop Actions + +
Adding New Drag and Drop Types + +
Advanced Drag-and-Drop + +
Inter-operating with Other Applications + +

+ + +

For drag and drop examples see (in increasing order of +sophistication): qt/examples/iconview/simple_dd, qt/examples/dragdrop and qt/examples/fileiconview. See also the +TQTextEdit widget source code. +

Dragging +

To start a drag, for example in a mouse motion event, create an object of the TQDragObject +subclass appropriate for your media, such as TQTextDrag for text and +TQImageDrag for images. Then call the drag() method. This is all you +need for simple dragging of existing types. +

For example, to start dragging some text from a widget: +

+void MyWidget::startDrag()
+{
+    TQDragObject *d = new TQTextDrag( myHighlightedText(), this );
+    d->dragCopy();
+    // do NOT delete d.
+}
+

+ +

Note that the TQDragObject is not deleted after the drag. The +TQDragObject needs to persist after the drag is apparently finished +since it may still be communicating with another process. Eventually +TQt will delete the object. If the widget owning the drag object is +deleted before then, any pending drop will be canceled and the drag +object deleted. For this reason, you should be careful what the object +references. +

Dropping +

To be able to receive media dropped on a widget, call +setAcceptDrops(TRUE) +for the widget (e.g. in its constructor), and override the +event handler methods +dragEnterEvent() and +dropEvent(). +For more sophisticated applications overriding +dragMoveEvent() and +dragLeaveEvent() will also be +necessary. +

For example, to accept text and image drops: +

+MyWidget::MyWidget(...) :
+    TQWidget(...)
+{
+    ...
+    setAcceptDrops(TRUE);
+}
+
+void MyWidget::dragEnterEvent(TQDragEnterEvent* event)
+{
+    event->accept(
+        TQTextDrag::canDecode(event) ||
+        TQImageDrag::canDecode(event)
+    );
+}
+
+void MyWidget::dropEvent(TQDropEvent* event)
+{
+    TQImage image;
+    TQString text;
+
+    if ( TQImageDrag::decode(event, image) ) {
+        insertImageAt(image, event->pos());
+    } else if ( TQTextDrag::decode(event, text) ) {
+        insertTextAt(text, event->pos());
+    }
+}
+

+ +

The Clipboard +

The TQDragObject, TQDragEnterEvent, TQDragMoveEvent, and TQDropEvent +classes are all subclasses of TQMimeSource: the class of objects which +provide typed information. If you base your data transfers on +TQDragObject, you not only get drag-and-drop, but you also get +traditional cut-and-paste for free. The TQClipboard has two functions: +

+    setData(TQMimeSource*)
+    TQMimeSource* data()const
+

+ +With these functions you can trivially put your drag-and-drop oriented +information on the clipboard: +

+void MyWidget::copy()
+{
+    TQApplication::clipboard()->setData(
+        new TQTextDrag(myHighlightedText()) );
+}
+
+void MyWidget::paste()
+{
+    TQString text;
+    if ( TQTextDrag::decode(TQApplication::clipboard()->data(), text) )
+        insertText( text );
+}
+

+ +You can even use TQDragObject subclasses as part of file IO. For +example, if your application has a subclass of TQDragObject that +encodes CAD designs in DXF format, your saving and loading code might +be: +

+void MyWidget::save()
+{
+    TQFile out(current_file_name);
+    if ( out.open(IO_WriteOnly) ) {
+        MyCadDrag tmp(current_design);
+        out.writeBlock( tmp->encodedData( "image/x-dxf" ) );
+    }
+}
+
+void MyWidget::load()
+{
+    TQFile in(current_file_name);
+    if ( in.open(IO_ReadOnly) ) {
+        if ( !MyCadDrag::decode(in.readAll(), current_design) ) {
+            TQMessageBox::warning( this, "Format error",
+                tr("The file \"%1\" is not in any supported format")
+                    .arg(current_file_name)
+            );
+        }
+    }
+}
+

+ +Note how the TQDragObject subclass is called "MyCadDrag", not +"MyDxfDrag": because in the future you might extend it to provide +DXF, DWG, SVF, WMF, or even TQPicture data to other applications. +

Drag and Drop Actions +

In the simpler cases, the target of a drag-and-drop receives a copy of +the data being dragged and the source decides whether to delete the +original. This is the "Copy" action in TQDropEvent. The target may also +choose to understand other actions, specifically the Move and Link +actions. If the target understands the Move action, the target is responsible for both the copy and delete operations and +the source will not attempt to delete the data itself. If the target +understands the Link, it stores its own reference to the original +information, and again the source does not delete the original. The +most common use of drag-and-drop actions is when performing a Move +within the same widget: see the Advanced +Drag-and-Drop section below. +

The other major use of drag actions is when using a reference type +such as text/uri-list, where the dragged data are actually references +to files or objects. +

Adding New Drag and Drop Types +

As suggested in the DXF example above, drag-and-drop is not limited to +text and images. Any information can be dragged and dropped. To drag +information between applications, the applications must be able to +indicate to each other which data formats they can accept and which +they can produce. This is achieved using MIME types: the drag +source provides a list of MIME types that it can produce (ordered from +most appropriate to least appropriate), and the drop target chooses +which of those it can accept. For example, TQTextDrag provides support +for the "text/plain" MIME type (ordinary unformatted text), and +the Unicode formats "text/utf16" and "text/utf8"; TQImageDrag +provides for "image/*", where * is any image format that +TQImageIO supports; and the TQUriDrag subclass provides +"text/uri-list", a standard format for transferring a list of +filenames (or URLs). +

To implement drag-and-drop of some type of information for which there +is no available TQDragObject subclass, the first and most important +step is to look for existing formats that are appropriate: the +Internet Assigned Numbers Authority (IANA) provides a hierarchical +list of MIME media types at the Information Sciences Institute +(ISI). Using standard MIME types +maximizes the inter-operability of your application with other +software now and in the future. +

To support an additional media type, subclass either TQDragObject or +TQStoredDrag. Subclass TQDragObject when you need to provide support for +multiple media types. Subclass the simpler TQStoredDrag when one type +is sufficient. +

Subclasses of TQDragObject will override the +const char* format(int i) const and +TQByteArray encodedData(const char* mimetype) const +members, and provide a set-method to encode the media data and static +members canDecode() and decode() to decode incoming data, similar to +bool canDecode(TQMimeSource*) const and +TQByteArray decode(TQMimeSource*) const +of TQImageDrag. +Of course, you can provide drag-only or drop-only support for a media +type by omitting some of these methods. +

Subclasses of TQStoredDrag provide a set-method to encode the media +data and the same static members canDecode() and decode() to decode +incoming data. +

Advanced Drag-and-Drop +

In the clipboard model, the user can cut or copy the source +information, then later paste it. Similarly in the drag-and-drop +model, the user can drag a copy of the information or they can drag +the information itself to a new place (moving it). The +drag-and-drop model however has an additional complication for the +programmer: the program doesn't know whether the user wants to cut or +copy until the drop (paste) is done! For dragging between +applications, it makes no difference, but for dragging within an +application, the application must take a little extra care not to +tread on its own feet. For example, to drag text around in a document, +the drag start point and the drop event might look like this: +

+void MyEditor::startDrag()
+{
+    TQDragObject *d = new TQTextDrag(myHighlightedText(), this);
+    if ( d->drag() && d->target() != this )
+        cutMyHighlightedText();
+}
+
+void MyEditor::dropEvent(TQDropEvent* event)
+{
+    TQString text;
+
+    if ( TQTextDrag::decode(event, text) ) {
+        if ( event->source() == this && event->action() == TQDropEvent::Move ) {
+            // Careful not to tread on my own feet
+            event->acceptAction();
+            moveMyHighlightedTextTo(event->pos());
+        } else {
+            pasteTextAt(text, event->pos());
+        }
+    }
+}
+

+ +

Some widgets are more specific than just a "yes" or "no" response when +data is dragged onto them. For example, a CAD program might only +accept drops of text onto text objects in the view. In these cases, +the dragMoveEvent() is used and +an area is given for which the drag is accepted or ignored: +

+void MyWidget::dragMoveEvent(TQDragMoveEvent* event)
+{
+    if ( TQTextDrag::canDecode(event) ) {
+        MyCadItem* item = findMyItemAt(event->pos());
+        if ( item )
+            event->accept();
+    }
+}
+

+ +If the computations to find objects are particularly slow, you might +achieve improved performance if you tell the system an area for which +you promise the acceptance persists: +

+void MyWidget::dragMoveEvent(TQDragMoveEvent* event)
+{
+    if ( TQTextDrag::canDecode(event) ) {
+        MyCadItem* item = findMyItemAt(event->pos());
+        if ( item ) {
+            TQRect r = item->areaRelativeToMeClippedByAnythingInTheWay();
+            if ( item->type() == MyTextType )
+                event->accept( r );
+            else
+                event->ignore( r );
+        }
+    }
+}
+

+ +

The dragMoveEvent() can also be used if you need to give visual +feedback as the drag progresses, to start timers, to scroll the +window, or whatever is appropriate (don't forget to stop the scrolling +and timers in a dragLeaveEvent() though). +

The TQApplication object (available as the qApp global) also +provides some drag and drop related functions: +TQApplication::setStartDragTime(), +TQApplication::setStartDragDistance(), and their corresponding +getters, TQApplication::startDragTime() and +TQApplication::startDragDistance(). +

Inter-operating with Other Applications +

On X11, the public XDND protocol is +used, while on Windows TQt uses the OLE standard, and TQt/Mac uses the +Carbon Drag Manager. On X11, XDND uses MIME, so no translation is +necessary. The TQt API is the same regardless of the platform. On +Windows, MIME-aware applications can communicate by using clipboard +format names that are MIME types. Already some Windows applications +use MIME naming conventions for their clipboard formats. Internally, +TQt has facilities for translating proprietary clipboard formats to and +from MIME types. This interface will be made public at some time, but +if you need to do such translations now, contact your TQt Technical +Support service. +

On X11, TQt also supports drops via the Motif Drag&Drop Protocol. The +implementation incorporates some code that was originally written by +Daniel Dardailler, and adapted for TQt by Matt Koss <koss@napri.sk> +and Trolltech. Here is the original copyright notice: +

Permission to use, copy, modify, distribute, and sell this software +for any purpose is hereby granted without fee, provided that the above +copyright notice appear in all copies and that both that copyright +notice and this permission notice appear in supporting documentation, +and that the name of Daniel Dardailler not be used in advertising or +publicity pertaining to distribution of the software without specific, +written prior permission. Daniel Dardailler makes no representations +about the suitability of this software for any purpose. It is +provided "as is" without express or implied warranty. +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1