WindowLib-1.0

From WowAce Wiki
Jump to: navigation, search

WindowLib is a small library that takes care of standard "windowy" behavior used in the main frames of many addons, and attempt to do so in a smarter way than the average addon author would find time to do.

  • Save and restore positions: WindowLib will pick the attach point based on which quadrant of the screen the frame is in: top-left? bottom-right? center?
  • Handle window dragging
  • Only mouse enable the window while Alt is held
  • .. more will surely come


WindowLib-1.0 is discontinued. See LibWindow-1.1.

Example

win = AceLibrary("Window-1.0")
myframe = CreateFrame("Frame") 
win:RegisterConfig(myframe, self.db.profile)
win:RestorePosition(myframe)  -- restores scale also
win:MakeDraggable(myframe)
win:EnableMouseOnAlt(myframe)


API Documentation

:RegisterConfig(frame, storage[, names])

local win = AceLibrary("Window-1.0")

win:RegisterConfig(myframe, self.db.profile)

This call initializes a frame for use with WindowLib, and tells it where configuration data lives. Optionally, you can specify the exact names of the variables that will be saved.

Arguments

frame
the frame to enable positioning support for
storage
a table to store configuration in
names
(optional) a table specifying which names to store in the configuration - see below

Manual variable naming

The optional last argument to the function is a table containing name mappings and/or a prefix for all variable names.

Example use - manually specify all variable names:

names = {
  x = "posx",
  y = "posy",
  scale = "size",
  point = "whereToAttach",
}

Example use - just prefix most names, but hardcode one

names = {
  prefix = "myframe",  -- names become e.g. "myframex", "myframey"
  point = "gluemyframe",
}

:SavePosition(frame)

Computes which quadrant the frame lives in, and saves its position relative to the right corner.

myframe:SetScript("OnDragStop", 
  function() win:SavePosition(myframe) end
)

:RestorePosition(frame)

Restores position and scale from configuration data.

win:RestorePosition(myframe)

:SetScale(frame, scale)

Sets the scale of the frame (without causing it to move, of course)

win:SetScale(myframe, myscale)

:MakeDraggable(frame)

Adds drag handlers to the frame and makes it movable. Positioning information is automatically stored according to :RegisterConfig().

win:MakeDraggable(myframe)

:EnableMouseOnAlt(frame)

Makes the window mouse-disabled as long as [Alt] is not held.

win:EnableMouseOnAlt(myframe)

Notes

On positioning logic

WindowLib will pick the attach point based on which quadrant of the screen the frame is in: top-left? bottom-right? center?

  • This means that frames do NOT necessarily stay exactly in place when the UI is resized
  • This is a GOOD THING! Much better than static positioning (i.e. :GetLeft()*:GetEffectiveScale)
  • Two frames sitting next to eachother when the UI is resized, will keep sitting next to eachother with this relative positioning.

Adding WindowLib to an existing addon

You will likely have window positioning data saved in your database since before. This data will likely need to be converted before WindowLib will handle it well.

WindowLib remembers position in the parent's scale. Most addons translate to global scale and save that. This is not compatible unless your UIParent is scale 1.0.

Example old code:

function MyAddon:SavePosition(frame)
  local p = self.db.profile
  p.x = frame:GetLeft() / frame:GetEffectiveScale()
  p.y = frame:GetTop() / frame:GetEffectiveScale()


Example code to patch the scale for WindowLib use:

function MyAddon:OnProfileEnable()
  local p = self.db.profile
  if not p.wlconv then
    p.x = p.x / UIParent:GetScale()
    p.y = p.y / UIParent:GetScale()
    p.wlconv = true
  end
  -- now it's safe to let WindowLib handle positioning