WoW:API Region SetPoint: Difference between revisions

← Older edit

WoW:API Region SetPoint (source)

Revision as of 04:47, 15 August 2023

1,610 bytes added , 15 August 2023

m

Move page script moved page API Region SetPoint to WoW:API Region SetPoint without leaving a redirect

Anonymous user

Move page script

@@ Line 1: / Line 1: @@
 {{widgetmethod}}
+Sets an attachment point of an UI component.
+ obj:SetPoint(point, relativeFrame, relativePoint, ofsx, ofsy);
+ obj:SetPoint(point, relativeFrame, relativePoint);
+ obj:SetPoint(point, ofsx, ofsy);
+ obj:SetPoint(point);
-Sets the current attachment point of an UI component.
+== Arguments ==
+; point : String - Point of the object to adjust based on the anchor.
+; relativeFrame : String/Widget - Name or reference to a frame to attach obj to. If omitted or nil, it typically defaults to the object's parent. However, if relativePoint is also not defined, relativeFrame will default to UIParent.
+; relativePoint : String - point of the relativeFrame to attach point of obj to. If not specified, defaults to the value of point.
+; ofsx : Number - x-offset (negative values will move ''obj'' left, positive values will move ''obj'' right), defaults to 0 if not specified.
+; ofsy : Number - y-offset (negative values will move ''obj'' down, positive values will move ''obj'' up), defaults to 0 if not specified.
-obj:SetPoint(point [, frame] [, relativePoint] [, x [, y]]);
+=== Points ===
+There are nine valid point values:
-== Parameters ==
+* "TOP", "RIGHT" "BOTTOM" "LEFT": the center-points of the respective sides.
-=== Arguments ===
+* "TOPRIGHT", "TOPLEFT", "BOTTOMLEFT", "BOTTOMRIGHT": corners of the frame rectangle.
-; point : The point on your object to use for attaching the obj (see [[API Positions]])  (i.e.  bind the left side of your frame)
+* "CENTER": the center point of the frame rectangle.
-; frame : Name of, or reference to, a frame to attach obj to; or nil to anchor relative to obj's parent (if no parent exists, anchor reative to the whole screen).
-; relativePoint : The relative point of ''frame'' to attach ''obj'' to (see [[API Positions]]); if not specified, defaults to the value of ''point'' when not specified.
-; x : x-offset (negative values will move ''obj'' left, positive values will move ''obj'' right), defaults to 0 if not specified.
-; y : y-offset (negative values will move ''obj'' down, positive values will move ''obj'' up), defaults to 0 if not specified.
 == Examples ==
@@ Line 25: / Line 31: @@
 == Details ==
+* Behavior of this function with multiple anchors is complex. Generally, you can override points by setting them again (so repeated assignment to the "TOPLEFT" point of a frame would move the frame, unless other anchor points interfere). If you're repositioning a frame, call <code>obj:[[API Region ClearAllPoints|ClearAllPoints]]()</code> to eliminate unwanted interactions.
+* Offset units are relative to the screen's effective scale. WoW's screen always has a height of 768 units, while screen width varies with aspect ratio.
+* <tt>ofsx</tt> and <tt>ofsy</tt> must both be passed as arguments for either to take effect; they default to 0 only when neither is given.  That is, <tt>foo:SetPoint(bar, 40)</tt> will ignore the 40 rather than treat it as (+40,+0).
+* Secure frames will silently ignore calls to this function if the relative frame is a [[API FontString|FontString]].
-* You will have to do a <code>obj:[[API Region ClearAllPoints|ClearAllPoints]]()</code> before using obj:SetPoint(...), if you expect the frame to actually move. -- [[User:Maisha|Maisha]]
+=== Edge definitions ===
+The edge "points" (TOP, RIGHT, BOTTOM, LEFT) are not actual points, but... edges. To fully define a region position using edges alone, you will need to define all four (as opposed to using corners, where you only need two) edges.
-* x and y units are relative to the screen's effective scale. WoW's screen always has a height of 768 units, width varies with aspect ratio.
+Therefore, defining an edge does not necessarily place a region relative to the center of that edge (For example, if you define TOP and RIGHT, the region will be placed at the TOPRIGHT corner). However, by default a region is "pulled" to the center if the number of points defined is insufficient.
-* As of 1.11 or so, there seems to be an [[API Region SetPoint/Exponential time|exponential-time increase]] if you anchor chains of objects with more than one point.
+Example:
+ Region:ClearAllPoints();
+ Region:SetPoint("TOP", relativeframe);
+ Region:SetWidth(100);
+ Region:SetHeight(100);
+will place ''Region'' to the top center of the ''relativeframe'' while adding a
+ Region:SetPoint("RIGHT", relativeframe);
+will place ''Region'' in the top right corner and now ''Region'' is fully defined.