seesaw.dnd — seesaw 1.5.0

Functions for dealing with drag and drop and data transfer.

default-transfer-handler clj

(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. A handler is either

a function: (fn [data] ...process drop...)  
or a map  : {:on-drop   (fn [data] ...process drop...)
             :can-drop? (fn [data] ...check drop is allowed...)}

if a map is provided :on-drop is mandatory, :can-drop? is optional, defaulting to (constantly true)

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 clj

(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 clj

(everything-transfer-handler handler)

Handler that accepts all drops. For debugging.

file-list-flavor clj

Flavor for a list of java.io.File objects

Flavorful clj protocol

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).

to-local clj

(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 clj

(to-raw-flavor this)

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

to-remote clj

(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.

html-flavor clj

Flavor for HTML text

image-flavor clj

Flavor for images as java.awt.Image

local-object-flavor clj

(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 clj

(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)

normalise-import-pairs clj

(normalise-import-pairs import-pairs)

string-flavor clj

Flavor for raw text

to-transfer-handler clj

(to-transfer-handler v)

uri-list-flavor clj

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

validate-import-pairs clj

(validate-import-pairs import-pairs)