[p3lim]

Upgrade Guide

Aside from other API changes from Blizzard themselves (such as deprecated API or backdrops now requiring a template/mixin),
and other changes not directly related to oUF, here are the headlines for what's coming to oUF version 10.0 and Shadowlands.

Version 10.x of oUF is not backwards compatible, and will only work in Shadowlands and the prepatch coming October 13th.
This guide is here to aid layout authors in updating before that release.

Version 10.0.0 will be tagged and released on October 12th, but feel free to test out your layouts from the master branch on the beta or PTR in the mean time.

Breaking changes

• AdditionalPower:
  • element:PostUpdate(unit, cur, max) callback signature changed to element:PostUpdate(cur, max)
  • element:UpdateColor(cur, max) override signature changed to element.UpdateColor(self, event, unit, powerType)
  • Removed support for automatically applying atlas as a widget texture
    • layouts can set these manually instead with element:SetStatusBarAtlas(atlas)
• AlternativePower:
  • Removed support for automatically applying atlas as a widget texture
    • layouts can set these manually instead with element:SetStatusBarAtlas(atlas)
• Castbar:
  • The entire element has been refactored, and callbacks have been merged and renamed:
    

    castbar:PostCastStart(unit, name)
    castbar:PostChannelStart(unit, name)
    => castbar:PostCastStart(unit)
    
    castbar:PostCastDelayed(unit, name)
    castbar:PostChannelUpdate(unit, name)
    => castbar:PostCastUpdate(unit)
    
    castbar:PostCastStop(unit, name)
    castbar:PostChannelStop(unit, name)
    => castbar:PostCastStop(unit, spellID)
    
    castbar:PostCastFailed(unit)
    castbar:PostChannelInterrupted(unit)
    => castbar:PostCastFail(unit, spellID)
    
    castbar:PostCastNotInterruptible(unit)
    castbar:PostCastInterruptible(unit)
    => castbar:PostCastInterruptible(unit)

  • The .Spark sub-widget is now no longer positioned by the element, the layout needs to position this itself.
    This can be accomplished easily in the layout, e.g. with this:
    

    Castbar.Spark:SetPoint("CENTER", Castbar:GetStatusBarTexture(), "RIGHT", 0, 0)

  • Castbars for *target units are no longer supported (e.g. for targettarget, focustarget, or raid14target),
    as they had no event-driven updates, requiring constant polling.
• Health:
  • element:UpdateColor(unit, cur, max) override signature changed to element.UpdateColor(self, event, unit)
• Power:
  • element:UpdateColor(unit, cur, min, max, displayType) override signature changed to element.UpdateColor(self, event, unit)
  • Deprecated altPowerColor option has been removed
    • override the color through element:GetAlternativeColor() instead
  • Removed support for automatically applying atlas as a widget texture
    • layouts can set these manually instead with element:SetStatusBarAtlas(atlas)
• Runes:
  • element:UpdateColor(runeID) override signature changed to element.UpdateColor(self, event, unit)
• Stagger:
  • element:UpdateColor(cur, max) override signature changed to element.UpdateColor(self, event, unit)
  • Element now only available to player units
• Tags:
  • The prefix and suffix delimiters have been changed from `>` and `<` into `$>` and `<$` respectively,
    allowing the `<` and `>` character to be used in prefixes and suffixes.

Non-breaking changes

• AdditionalPower:
  • New callback element:PostUpdateColor(r, g, b)
  • New callback element:PostVisibility(isVisible)
  • New method element:SetFrequentUpdates(state[, force]) to toggle the frequent updates
  • New option frequentUpdates to update the element more frequently
• AlternativePower:
  • Added multiple options for automatically updating the texture colors, alike health and power
  • New callback element:PostUpdateColor(unit, r, g, b)
  • New override element.UpdateColor(self, event, unit, ...)
• Castbar:
  • Added .hideTradeSkills option, which when set to true will no longer display tradeskill-related casts
  • The .SafeZone sub-widget now supports vertically-oriented castbars properly
• ClassPower:
  • New callback element:PostVisibility(isVisible)
  • New callback element:PostUpdateColor(r, g, b)
    • see the documentation for the details
  • Holy power is now available for all Paladin specializations
• Health:
  • New callback element:PostUpdateColor(unit, r, g, b)
  • New method element:SetColorDisconnected(state[, force]) to toggle disconnected color updates
  • New method element:SetColorSelection(state[, force]) to toggle target change color updates
  • New method element:SetColorTapping(state[, force]) to toggle tapped color updates
  • New method element:SetColorThreat(state[, force]) to toggle threat color updates
  • .frequentUpdates option was removed, as all health updates are "frequent" now
• HealthPrediction:
  • .frequentUpdates option was removed, as all health updates are "frequent" now
• PhaseIndicator:
  • Tooltip support, if the element is a Frame as opposed to a Texture
    • see the documentation for the details
• Power:
  • New callback element:PostUpdateColor(unit, r, g, b)
  • New method element:SetColorDisconnected(state[, force]) to toggle disconnected color updates
  • New method element:SetColorSelection(state[, force]) to toggle target change color updates
  • New method element:SetColorThreat(state[, force]) to toggle threat color updates
  • New override element:GetDisplayPower()
    • use this to override when the unit should show an alternate power type (e.g. Priest's insanity)
• Runes:
  • New callback element:PostUpdateColor(r, g, b)
• Stagger:
  • New callback element:PostUpdateColor(r, g, b)
• Tags:
  • Tags can now be passed arguments, e.g. [shortname(5)], which will be passed directly to the tag implementation, e.g:
    

    oUF.Tags.Methods['shortname'] = function(unit, realUnit, arg1)
        -- return the first N letters from the name, as provided by `arg1`
        -- if arg1 is not provided, return the full name
        return UnitName(realUnit or unit):sub(1, tonumber(arg1))
    end

    • You can add as many arguments as you want, separated by a single comma (e.g. [mytag(a,b,c,d)]).
    • Do not use spaces when separating the arguments (e.g. don't do this: [mytag(a, b, c, d)]).
• Threat:
  • Threat color can now be customized through the color table

For the full details of all the changes, see the commit log.

For any questions regarding this specific upgrade guide, please reply to this thread.
For any issues, please search the issues tracker or open a new issue.
For anything not related to the upgrade guide, please search for an existing thread on the subject or open a new thread.