Indicator API

All of the default indicators use this API, and it is strongly recommended that plugins use it too. If you need working examples, see any of the files in the Indicators sub-folder, but be aware that some indicators like Alpha and Border may not be good examples since they don't actually create any objects. The Corner, Icon, and Text indicators are probably the best examples for building third-party indicators.

Registering an indicator

To add your indicator to Grid, call the RegisterIndicator method on the GridFrame module:

GridFrame:RegisterIndicator(id, name, newFunc, resetFunc, setFunc, clearFunc)

Arguments

1. id - string: a short identifier to be used internally to keep track of your indicator and which statuses the user has assigned to it between sessions. It must be unique.

2. name - string: a user-friendly name to be displayed in configuration menus. It should be unique to avoid confusing users. If you do not provide a name, the id value will be shown to the user.

3. newFunc - function/nil: a function that returns a new instance of the indicator, or nil if your indicator acts only on existing widgets and does not need to create any of its own. Functions will receive one argument, which is a reference to the frame the indicator is being created on.

4. resetFunc - function/nil: a function that configures the indicator, or nil if your indicator does not have any widgets of its own to configure. Functions will receive one argument, which is a reference to the indicator object being configured.

5. setFunc - function: a function that displays a given status on the indicator. It will receive a reference to the indicator object itself as the first argument, followed by additional arguments describing the display properties of the status. See below for a full list.

6. clearFunc - function: a function that removes all displayed statuses from the indicator and returns it to its default state. It will receive one argument, which is a reference to the indicator object being cleared.

New function

When a new unit frame is created, all indicators are created first, and then all indicators are reset. Your newFunc should not attempt to apply any settings, especially if it depends on the existence of other indicators, since it will almost certainly be called before all other indicators have been created.

The following keys will be added to the object returned by your newFunc:

• __id - the identifier for the indicator
• __owner - a reference to the frame to which the indicator is attached
• Reset - the resetFunc that you specified
• SetStatus - the setFunc that you specified
• Clear - the clearFunc that you specified

And a reference to the object will be available on the frame at frame.indicators[id].

Reset function

This function is attached to each instance of your indicator as a method.

This is where you should apply settings, re-parent your object to some other indicator's object if necessary, etc. You should not overwrite any status display properties, as the indicator may be displaying a status already. For example, if your indicator is a font string, your reset function should not change its color or text values.

SetStatus function

This function is attached to each instance of your indicator as a method.

This is where you actually display a status on your indicator. The function will receive the following arguments:

• self - a reference to the indicator object displaying the status
• color - table: the color for the status; contains r/g/b keys, and optionally "a" and "ignore" keys
• text - string: the text to be shown for the status
• value - number: the value for the status (eg. current health for the Unit Health status)
• maxValue - number: the maximum value for the status (eg. maximum health for the Unit Health status)
• texture - string/table: the path to the texture to show, or a table with r/g/b values for a solid color
• texCoords - table: contains the left/right/top/bottom coordinates for the texture
• count - number: the count for the status (eg. number of stacks for an aura status)
• startTime - number: the time at which the status began, relative to GetTime()
• duration - number: the total duration for the status, in seconds

Your indicator does not need to support all of these properties.

If your indicator requires certain properties (eg. a text indicator requires text do display) you should check for them and return out if they are not present; do not clear your indicator in this case, as it may still be displaying some other status with a lower priority that it does support.

Clear function

This function is attached to each instance of your indicator as a method.

This is called when your indicator is no longer displaying any statuses. In most cases, your indicator should simply hide itself. If it remains visible, it should be set to some sensible default appearance. For example, when the default Frame Alpha indicator is cleared, it resets the frame to 100% opacity.

Adding options

There is not (yet) any API for adding options specific to your indicator. If your indicator has options, you must manually insert them into Grid's options table. The recommended path is:

GridFrame.options.args[id] = { -- use your indicator's identifier
   name = L["Name"], -- use your indicator's display name
   type = "group",
   args = {
       -- add your options here
   }
}

This will add a new tab in the Frame section, next to the existing General, Bar, Text, and Icon tabs. If your plugin adds multiple indicators of the same type, you should only add one tab for the category, and use child groups to configure the individual indicators; an example of this might be a plugin that allows the user to create an arbitrary number of additional colored square indicators.

Saving settings

There is also no API (yet) for storing settings for third-party indicators. If your indicator has any settings of its own, you can either store them in your plugin's own saved variables using whatever method you prefer, or piggyback on Grid's saved variables by creating your plugin as a GridFrame sub-module:

local MyIndicatorPlugin = GridFrame:NewModule("MyIndicatorPlugin")

function MyIndicatorPlugin:Initialize()
   self.db = Grid.db:RegisterNamespace("MyIndicatorPlugin", {
      profile = {
         -- your settings here
      }
   }
end

If you're just hardcoding a single indicator, you can just register it in the main chunk. If you're creating dynamic indicators, you can register them at any time; indicators added later will be immediately created, reset, and updated on all existing frames.