WoW:Making Draggable Frames

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ HOWTOs

← HOWTOs

Draggable frames can be moved by having the user hold down a mouse button over the frame, then move the mouse to reposition the frame. This HOWTO describes how to make a frame draggable.

Summary

To initiate dragging of a frame, call Frame:StartMoving(); to stop, call Frame:StopMovingOrSizing(). The frame must be flagged as movable (either through the movable attribute in its XML declaration or using Frame:SetMovable(isMovable).

While those functions can theoretically be called from anywhere, Frame:RegisterForDrag("button1", ...) allows the use of OnDragStart/OnDragStop widget handlers. Note that to receive mouse events (including dragging), the frame must be mouse enabled (either through the enableMouse attribute in its XML declaration or using Frame:EnableMouse(isEnabled)); buttons are mouse-enabled by default.

Using XML

The code below creates a draggable Frame widget and uses the Drag widget handlers to initiate dragging. Note the use of movable and enableMouse attributes:

<Frame name="DragFrame1" enableMouse="true" movable="true">
 <Scripts>
  <OnLoad>self:RegisterForDrag("LeftButton");</OnLoad>
  <OnDragStart>self:StartMoving();</OnDragStart>
  <OnDragStop>self:StopMovingOrSizing();</OnDragStop>
 </Scripts>
 <!-- Tags below add a visual element to the frame. -->
 <Layers>
  <Layer level="ARTWORK">
   <Texture setAllPoints="true">
    <Color r="1.0" g="0.5" b="0.0" a="0.5" />
   </Texture>
  </Layer>
 </Layers>
 <Size x="64" y="64" />
 <Anchors><Anchor point="CENTER" relativeTo="UIParent"/></Anchors>
</Frame>

Using OnMouseUp/OnMouseDown

The OnDrag* handlers typically require the mouse button to be held down for a small amount of time prior to enabling the mouse behavior, making them well suited for dragging widgets that normally respond to clicks. However, if the frame you wish to make draggable is not normally a button, you can use OnMouseUp/OnMouseDown to provide a more responsive experience.

The following snippet illustrates this concept, and should replace the <Scripts> block above:

<Scripts>
 <OnMouseDown>
  if button == "LeftButton" and not self.isLocked then
   self:StartMoving();
   self.isMoving = true;
  end
 </OnMouseDown>
 <OnMouseUp>
  if button == "LeftButton" and self.isMoving then
   self:StopMovingOrSizing();
   self.isMoving = false;
  end
 </OnMouseUp>
 <OnHide>
  if ( this.isMoving ) then
   this:StopMovingOrSizing();
   this.isMoving = false;
  end
 </OnHide>
</Scripts>

Note: this also adds a frame.isLocked boolean field to control whether the frame can be dragged or not. There's generally no limit to the amount of conditional logic you can insert prior to :StartMoving() -- for instance, requiring the user to hold down some modifier button is a possible alternative.

Using TitleRegion

Frames can have a TitleRegion object that handles dragging automatically -- as long as the mouse is held down within the TitleRegion, it'll allow the frame to be dragged.

The frame created below will be draggable by clicking on its top 20 pixels:

<Frame enableMouse="true">
 <Size x="100" y="100"/>
 <TitleRegion>
  <Size x="100" y="20"/>
  <Anchors><Anchor point="TOP"></Anchors>
 <TitleRegion>
 <!-- Tags below add a visual element to the frame. -->
 <Layers>
  <Layer level="ARTWORK">
   <Texture setAllPoints="true">
    <Color r="1.0" g="0.5" b="0.0" a="0.5" />
   </Texture>
  </Layer>
 </Layers>
 <Anchors><Anchor point="CENTER" relativeTo="UIParent"/></Anchors>
</Frame>

Using Lua

The code sample below illustrates the use of the Widget API to achieve the same results as the XML above:

local frame = CreateFrame("Frame", "DragFrame2", UIParent)
frame:SetMovable(true)
frame:EnableMouse(true)
frame:SetScript("OnMouseDown", frame.StartMoving)
frame:SetScript("OnMouseUp", frame.StopMovingOrSizing)
-- The code below makes the frame visible, and is not necessary to enable dragging.
frame:SetPoint("CENTER"); frame:SetWidth(64); frame:SetHeight(64);
local tex = frame:CreateTexture("ARTWORK");
tex:SetAllPoints();
tex:SetTexture(1.0, 0.5, 0); tex:SetAlpha(0.5);