Widget API: Frame:StartMoving

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

→ Methods

← Widget API ← Frame < StartMoving

Moves the frame-based object in relation to where the mouse is being moved.

frame:StartMoving()

Details

• Use this with the Frame:RegisterForDrag() function and the <OnDragStart>...</OnDragStart> event to allow your frame-based object to be moved by the user.
• Use the Frame:StopMovingOrSizing() function inside the <OnDragStop>...</OnDragStop> XML section to stop the moving process.
• Moving a frame using this function sets the user placed flag for the frame, making the client save its position and reposition the frame on reload. To avoid this behavior, you can call frame:SetUserPlaced(false) immediately after StopMovingOrSizing().
• For pixel-precise movements, you should instead use EnableMouse() and the <OnMouseDown>...</OnMouseDown> and <OnMouseUp>...</OnMouseUp> events (and probably also the <OnHide>...</OnHide> event).
• If the frame becomes stuck by any cause (see SetClampedToScreen()), the mouse and the frame will go out-of-sync.
• If you use the StartDrag/StopDrag events to initiate the dragging, be sure not to :Hide() the dragged frames during the process. A hidden frame will NOT receive its StopDrag event.
• This function together with StopMovingOrSizing() exhibit some "special" behavior that can cause problems when used with frames that are not anchored to UIParent (or some other full-screen frame).
  • Immediately upon calling StartMoving(), the frame will be de-anchored from any other frame it was previously anchored to, and instead anchored to the screen. For example, if MyFrame's TOPLEFT is anchored to MyParent's TOPLEFT at (5,-5), and MyParent's TOPLEFT is anchored to UIParent's TOPLEFT at (100,-100), then MyFrame:StartMoving() immediately re-anchors MyFrame's TOPLEFT to the screen's (nil anchor) TOPLEFT at (105,-105). The original anchor frame (MyParent) and offset will not be restored by StopMovingOrSizing().
  • Furthermore, StopMovingOrSizing() will identify the closest anchor point on the screen and re-anchor the frame once again to that closest point. For example, if MyFrame is dragged to (50,-600) (still relative to the screen), and has a height of 25, then MyFrame:StopMovingOrSizing() immediately re-anchors MyFrame's BOTTOMLEFT to the screen's BOTTOMLEFT at (50,143) (recall that the WoW UI always has height 768 regardless of resolution).
  • There does not appear to be any way to disable either of these behaviors. If you want your frame to end up anchored to the same frame it was anchored to initially, one way to work around this issue is to store the result of GetPoint() three times:
    • immediately before StartMoving(), to get the initial offset relative-to-frame
    • immediately after StartMoving(), to get the initial offset relative-to-screen
    • immediately before StopMovingOrSizing(), to get the final offset relative-to-screen, but before the anchor points are (potentially) changed
  • This way, you can subtract the second measurement from the third to get a "delta" (x,y) for the total movement, and then add that to the first measurement to get the appropriate final offset relative-to-frame. You can then manually re-anchor your frame to its appropriate parent, at its new offset -- but you must do so after calling StopMovingOrSizing() (and ClearAllPoints()).