DragLib-1.0

From WowAce Wiki
Jump to: navigation, search

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)

How to ...

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.

Drag enable a data object

myobject.objectContainer = mycontainer
DragLib:DragEnable(myobject)

Drag enable a frame

myframe.data = myobject
DragLib:DragEnableFrame(myframe)

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.

Internals

Methods and values in objects

dragType

This gets set by :DragEnable()

object.dragType = "MyItemType"

objectContainer

Must be set by the addon

object.objectContainer = myContainingDataObject

AcceptObject

container.AcceptObject = function(self, object, 

RemoveObject

container.RemoveObject = function(self, objectRemoved)

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

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

What :DragEnable() actually does

  • set data.dragType
  • set data.dragAcceptHandler

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)


API Documentation

Note: This documentation is auto-generated. Please note that direct modifications may be overwritten on next autogenerate.

:CallAcceptHandler(container , object , how , ...)

Arguments

container
type - (needs documentation)
object
type - (needs documentation)
how
type - (needs documentation)
...
type - (needs documentation)


:CallRemoveHandler(container , object , ...)

Arguments

container
type - (needs documentation)
object
type - (needs documentation)
...
type - (needs documentation)


:DestinationIndicator(frame , where)

Arguments

frame
type - (needs documentation)
where
type - (needs documentation)


:DoDrag(object , destframe , testonly)

Arguments

object
type - (needs documentation)
destframe
type - (needs documentation)
testonly
type - (needs documentation)


:MethodIndicator(how)

Arguments

how
type - (needs documentation)


:activate(self , oldLib , oldDeactivate)

Arguments

self
type - (needs documentation)
oldLib
type - (needs documentation)
oldDeactivate
type - (needs documentation)