DragLib-1.0

From WowAce Wiki

Summary
Lib: DragLib-1.0
A library that handles drag&drop actions for frames and data objects
TOC	2.1 (20100)
Category	Libraries
Author	Mikk
Details
OptionalDeps	Ace2
Links
Betas	Ace SVN Zip
Changelog	FishEye

DragLib is in early beta. This documentation is FAR from complete.

TODO: Docos on what "LINK" can mean
TODO: frame.dragTarget
TODO: .objectContainer can be a function (should be when in an SV)

[edit]

How to ...

[edit]

Setup a container object

Each draggable object needs to know where it lives, so that the library knows where to remove it from when it's being dragged somewhere.

mycontainer_RemoveObject = {
  ["*"] = function(container, object, testonly, destframe)
    if not (destframe:GetName() or ""):match("^MyAddOn_") then
      return "COPYORLINK"
    end
    return true
  end,
  MyItemType = function(container, object, testonly, destframe)
    if not testonly then
      -- some code that removes object from container
    end
    return true
  end,
} 

mycontainer.RemoveObject = mycontainer_RemoveObject

Instead of a table, RemoveObject can also be a single function that handles different object types by looking at object.dragType.

You should normally examine destframe, either in ["*"] or in the type handlers, to see if data is being dragged to another addon altogether. If it is, you'll normally want to return "COPYORLINK", unless it is ok with the data truly changing owner altogether.

Often, you can work off of the frame name, but it is certainly possible to use other data available in the frame, e.g. walking parents to see that the root window is a known one.

[edit]

Drag enable a data object

myobject.objectContainer = mycontainer
DragLib:DragEnable(myobject)

[edit]

Drag enable a frame

myframe.data = myobject
DragLib:DragEnableFrame(myframe)

[edit]

Make an object able to accept objects

MyContainer_AcceptObject = {
  MyItemType = {
    MOVE = function(container, object, how, testonly)
      if not testonly then
        tinsert(container, object)
        object.objectContainer = container
      end
      return true;
    end,
    COPY = function(container, object, how, testonly)
      if not testonly then
        local objectCopy
        -- code that makes a copy of object 
        object.objectContainer = container
        tinsert(container, objectCopy)
      end
      return true;
    end,
    LINK = function(container, object, how, testonly)
      if not testonly then
        local objectLink
        -- code that links data in object to data in objectLink
        object.objectContainer = container
        tinsert(container, objectCopy)
      end
      return true
    end,
    COPYORLINK = "COPY", -- not necessary, will default to copy
  } 
} 

mycontainer.AcceptObject = MyContainerType_AcceptObject

Instead of a table, AcceptObject can also be a single function that handles different object types by looking at object.dragType. When appropriate, it should return "COPY" or "LINK" as its third return value.

A LINK handler is not necessary; only use where it makes sense to actually link data between two objects.

If a MOVE handler is not given, DragLib will attempt COPY.

[edit]

Internals

[edit]

Methods and values in objects

[edit]

dragType

This gets set by :DragEnable()

object.dragType = "MyItemType"

[edit]

objectContainer

Must be set by the addon

object.objectContainer = myContainingDataObject

[edit]

AcceptObject

container.AcceptObject = function(self, object,

[edit]

RemoveObject

container.RemoveObject = function(self, objectRemoved)

objectRemoved.objectContainer will always be == self at the time of this call.

[edit]

Returns

 - false - refused to remove, don't drag the object
 - "COPYORLINK" - don't remove, either make a copy or a link in the new container
 - true - removed ok

[edit]

What :DragEnable() actually does

set data.dragType
set data.dragAcceptHandler

[edit]

What :DragEnableFrame() actually does

verify that frame.data exists and is a drag-enabled data object
set a drag handler on the frame, which will
- Make sure that frame.data.dragContainer.dragRemoveHandler exists before picking up
- For all destframes being moused over: test if destframe.data.dragAcceptHandler exists and call it
- On release, call:
  - frame.data.dragContainer.dragRemoveHandler(frame)
  - destframe.data.dragAcceptHandler(frame.data, true)

[edit]