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).
There are generally 2 methods that are used for moving a frame, by Dragging the frame (OnDragStart & OnDragStop Handlers) or Clicking the frame (OnMouseDown & OnMouseUp 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[]
Using OnDragStart / OnDragStop[]
The code below creates a draggable Frame widget and uses the OnDrag widget handlers to initiate dragging. Note the use of movable and enableMouse attributes:
<Ui>
<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>
</Ui>
Note the use of the OnLoad Script, In order to drag a frame it must register for drag via Frame:RegisterForDrag("button"). Above code edited to include the <Ui> </Ui> tags as it is .xml and won't work without this.
Using OnMouseUp/OnMouseDown[]
While 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.isMoving 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[]
Using OnDragStart OnDragStop[]
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:RegisterForDrag("LeftButton")
frame:SetScript("OnDragStart", frame.StartMoving)
frame:SetScript("OnDragStop", 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);
Using OnMouseDown / OnMouseUp[]
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", function(self, button)
if button == "LeftButton" and not self.isMoving then
self:StartMoving();
self.isMoving = true;
end
end)
frame:SetScript("OnMouseUp", function(self, button)
if button == "LeftButton" and self.isMoving then
self:StopMovingOrSizing();
self.isMoving = false;
end
end)
frame:SetScript("OnHide", function(self)
if ( self.isMoving ) then
self:StopMovingOrSizing();
self.isMoving = false;
end
end)
-- 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);
General Notes[]
The use of the OnHide Handler is not entirely necessary. However it is a good idea if your frames are being Hidden or Shown by running code and not the User.
The use of full functions is also not required in lua:
frame:SetScript("OnDragStart" frame.StartMoving)
frame:SetScript("OnDragStop" frame.StopMovingOrSizing)
frame:SetScript("OnMouseDown" frame.StartMoving)
frame:SetScript("OnMouseUp" frame.StopMovingOrSizing)
In XML all that is required is just the function:
<OnDragStart>self:StartMoving();</OnDragStart> <OnDragStop>self:StopMovingOrSizing();</OnDragStop>
<OnMouseDown>self:StartMoving();</OnMouseDown> <OnMouseUp>self:StopMovingOrSizing();</OnMouseUp>