Table of Contents

Flavorful

Protocol for abstracting DataFlavor including automatic conversion from
external/native representations (e.g. uri-list) to friendlier internal 
representations (e.g. list of java.net.URI).

default-transfer-handler

Usage: (default-transfer-handler & {:keys [import export], :as opts})

Create a transfer handler for drag and drop operations. Take a list
of key/value option pairs as usual. The following options are supported:

  :import - A vector of flavor/handler pairs used when a drop/paste occurs
            (see below)
  :export - A map of options used when a drag/copy occurs (see below)

Data Import

  The :import option specifies a vector of flavor/handler pairs. When
  a drop/paste occurs, the handler for the first matching flavor is called
  with a map with the following keys:

    :target        The widget that's the target of the drop
    :data          The data, type depends on flavor
    :drop?         true if this is a drop operation, otherwise it's a paste
    :drop-location Map of drop location info or nil if drop? is false. See 
                   below.
    :support       Instance of javax.swing.TransferHandler$TransferSupport
                   for advanced use.

  The handler must return truthy if the drop is accepted, falsey otherwise.

  If :drop? is true, :drop-location will be non-nil and include the following
  keys, depending on the type of the drop target:

    All types:

      :point    [x y] vector

    listbox 

      :index    The index for the drop
      :insert?  True if it's an insert, i.e. "between" entries

    table 

      :column         The column for the drop
      :row            The row for the drop
      :insert-column? True if it's an insert, i.e. "between" columns.
      :insert-row?    True if it's an insert, i.e. "between" rows 

    tree 

      :index  The index of the drop point 
      :path   TreePath of the drop point

    Text Components

      :bias   No idea what this is
      :index  The insertion index

Data Export

  The :export option specifies the behavior when a drag or copy is started
  from a widget. It is a map with the following keys:

    :actions A function that takes a widget and returns a keyword indicating
             supported actions. Defaults to :move. Can be any of :move, :copy, 
             :copy-or-move, :link, or :none.
    :start   A function that takes a widget and returns a vector of flavor/value
             pairs to be exported. Required.
    :finish  A function that takes a map of values. It's called when the drag/paste
             is completed. The map has the following keys:
              :source The widget from which the drag started
              :action The action, :move, :copy, or :link.
              :data   A Transferable

Examples:


  (default-transfer-handler
    ; Allow either strings or lists of files to be dropped
    :import [string-flavor    (fn [{:keys [data]}] ... data is a string ...)
             file-list-flavor (fn [{:keys [data]}] ... data is a *list* of files ...)]
    
    :export {
      :actions (fn [_] :copy)
      :start   (fn [w] [string-flavor (seesaw.core/text w)])
      :finish  (fn [_] ... do something when drag is finished ...) })

See:

  http://download.oracle.com/javase/6/docs/api/javax/swing/TransferHandler.html

default-transferable

Usage: (default-transferable pairs)

Constructs a transferable given a vector of alternating flavor/value pairs.
If a value is a function, i.e. (fn? value) is true, then then function is 
called with no arguments when the value is requested for its corresponding 
flavor. This way calculation of the value can be deferred until drop time. 

Each flavor must be unique and it's assumed that the flavor and value agree.

Examples:

  ; A transferable holding String or File data where the file calc is
  ; deferred
  (default-transferable [string-flavor    "/home/dave"
                         file-list-flavor #(vector (java.io.File. "/home/dave"))])

everything-transfer-handler

Usage: (everything-transfer-handler handler)

Handler that accepts all drops. For debugging.

file-list-flavor

Flavor for a list of java.io.File objects

html-flavor

Flavor for HTML text

image-flavor

Flavor for images as java.awt.Image

local-object-flavor

Usage: (local-object-flavor class-or-value)

Creates a flavor for moving raw Java objects between components within a
single JVM instance. class-or-value is either the class of data, or an
example value from which the class is taken.

Examples:

  ; Move Clojure vectors
  (local-object-flavor [])

make-flavor

Usage: (make-flavor mime-type rep-class)

Construct a new data flavor with the given mime-type and representation class.

Notes:

  Run seesaw.dnd-explorer to experiment with flavors coming from
  other apps.

Examples:

  ; HTML as a reader
  (make-flavor "text/html" java.io.Reader)

string-flavor

Flavor for raw text

to-local

Usage: (to-local this value)

Given an incoming value convert it to the expected local format. For example, a uri-list
would return a vector of URI.

to-raw-flavor

Usage: (to-raw-flavor this)

Return an instance of java.awt.datatransfer.DataFlavor for this.

to-remote

Usage: (to-remote this value)

Given an outgoing value, convert it to the appropriate remote format.
For example, a vector of URIs would be serialized as a uri-list.

uri-list-flavor

Flavor for a list of java.net.URI objects. Note it's URI, not URL.
With just java.net.URL it's possible to drop non-URL links, e.g. "about:config".