plugin-api

r3

Source

Markup: *

== What is the Squared API? == Squared is designed to be modular, with the capability for external plugins to add functionality and options that might not be included in the base Squared addon. In order to facilitate this, Squared has an API interface that allows external plugins to more easily interact with Squared without having to manually hook its functions in ways that might cause issues if an internal Squared function were to change. == Basic Structure == Squared allows external plugins to registered two types of interactions: '''modes''' and '''event handlers'''. === Modes === Modes are entirely new unit logic - only one Squared mode is active at any given time (Squared has 5 default modes: 'default', 'group', 'warband', 'scenario', and 'disabled' - the last of which is a dummy mode). Registering new modes allows complete control over what units are displayed, how they're grouped, what shows in each frame, et cetera. If, for instance, you wanted to make Squared display all units in a warband as part of a single group (so as, perhaps, to have a layout similar to WoW's "PerfectRaid"), you could register a mode that provide such a layout of units. You'd also need to register an event handler to specify when your mode should be activated, as explained in the section about event handlers. === Event Handlers === If you don't want to completely redo a mode, but instead just want to add features or otherwise modify an existing one, you can do so using Squared's event handler system. This system allows you to register a function that will be called when a certain event happens within Squared, potentially allowing you to modify or alter existing data at that time. Currently, the following events are provided by Squared: * addunit * setname * layoutgroup * layoutgroups * cleargroups * changemode * unitlclick * unitrclick * unitmouseover * unitmouseout == Defining and Registering New Modes == As far as Squared is concerned, a valid mode object is a table (for the sake of example, we'll call it ModeObject) that defines the following member functions (neither of which take arguments): * ModeObject.OnLoad (called when the given mode is activated) * ModeObject.OnUnload (called when the given mode is deactivated) Mode objects can also ''optionally'' define any of the following member functions recognized by Squared: * ModeObject.UnitLClick (called for the active mode when a unit is left-clicked) *:4 paramaters passed - self, group#, member#, modifier key flags * ModeObject.UnitRClick (called for the active mode when a unit is right-clicked) *:4 paramaters passed - self, group#, member#, modifier key flags * ModeObject.UnitMouseOver (called when the mouse moves over a frame) *:3 parameters passed - self, group#, member# * ModeObject.UnitMouseOut (called when the mouse moves away from a frame after being over it) *:3 parameters passed - self, group#, member# * ModeObject.OnUpdate (called for the active mode every OnUpdate event) *: 1 paramater passed - time (in seconds) since last OnUpdate Once you've defined a mode object, you need to register it with Squared, by using the following call: :Squared.RegisterModeHandler("''modename''", ModeObject) (Note: attempting to register a mode with a name that is already registered will be ignored - if you want to override another mode, you'll need to register an event handler for the changemode event to redirect to the name of your mode, you can't just define your mode with the same name.) For examples of mode objects in action, simply look at the default ones provided with Squared (SquaredPlayer.lua, SquaredGroup.lua, SquaredWarband.lua and SquaredScenario.lua). == Using Event Handlers == Registering a basic event handler with Squared is quite simple: :Squared.RegisterEventHandler("eventname", ''function'') In this case, ''function'' can be either an inline function, like so: :Squared.RegisterEventHandler("eventname", function() ''...do stuff...'' end) or, it can be a reference to a function defined elsewhere: :function myObject.myFunc(param1, param2) : ''...do stuff...'' :end :Squared.RegisterEventHandler("eventname", myObject.myFunc) Event handlers can also be unregistered via Squared.UnregisterEventHandler, which takes the same arguments. Each event has its own set of arguments that it will pass to registered handlers, and its own expectations of what a function might (or might not) return, which are listed below. === Event Details === * addunit *: Supplied arguments: a table containing a SquaredUnitFrame object *: Expected returns: ''nil'' (to use the same object as was supplied to the handler) or a table containing a SquaredUnitFrame object to replace the one that was supplied to the handler. *: Description: This event is fired whenever Squared's AddUnit function is called to add a new unit box to its display. * setname *: Supplied arguments: a table containing a SquaredUnitFrame object *: Expected returns: none *: Description: This event is fired whenever a SquaredUnitFrame has its SetName() method called. * layoutgroup *: Supplied arguments: a table containing all of the unit objects for the group being laid out. *: Expected returns: ''nil'' (to use the same group table as was supplied) or a table to replace the one that was supplied. *: Description: This event is fired whenever Squared's ReanchorGroup function is called to set the layout of a single given group. * layoutgroups *: Supplied arguments: a table containing all of the group tables for the current layout. *: Expected returns: ''nil'' (to use the same groups table as was supplied) or a table to replace the one that was supplied. *: Description: This event is fired whenever Squared's ReanchorGroups function is called to lay out the entire current display. * changemode *: Supplied arguments: a string specifying the mode Squared "thinks" should be loaded. *: Expected returns: ''nil'' (to use the mode that Squared currently thinks should be loaded) or a string specifying the mode to use. *: Description: This event is fired whenever Squared is trying to make a decision about what mode to use. If you create a custom mode and want to specify when and where it should show up, you'll want to register a handler for this event and return the name of your custom mode whenever you detect that it should be loaded. (For instance, if you wanted to always display your mode instead of the scenario display, you could just use ''function(oldMode) if oldMode == "warband" then return "myNewMode" else return nil end end'' as your handler.) * unitlclick *: Supplied arguments: group #, member #, modifier key flags *: Expected returns: ''nil'' or ''false'' to continue processing the click, any true value to stop further processing of the click. *: Description: This event is fired whenever the left mouse button is pressed on one of Squared's unit frames. It supplies the group and member numbers for the clicked unit frame, as well as the number containing the flags for which modifier keys were held for the press. If you want to halt any further processing of the click, return something that evaluates to true (basically, anything that isn't ''false'' or ''nil''), and nothing else will be done with the click (no more event handlers will be called, nor will the current mode's UnitLClick be called). * unitrclick *: Supplied arguments: group #, member #, modifier key flags *: Expected returns: ''nil'' or ''false'' to continue processing the click, any true value to stop further processing of the click. *: Description: This event is fired whenever the right mouse button is pressed on one of Squared's unit frames. It supplies the group and member numbers for the clicked unit frame, as well as the number containing the flags for which modifier keys were held for the press. If you want to halt any further processing of the click, return something that evaluates to true (basically, anything that isn't ''false'' or ''nil''), and nothing else will be done with the click (no more event handlers will be called, nor will the current mode's UnitRClick be called). * unitmouseover *: Supplied arguments: group #, member # *: Expected returns: ''nil'' or ''false'' to continue processing the mouseover, anything else to stop processing the mouseover. *: Description: This event is fired whenever the mouse is moved over one of Squared's unit frames. It supplies the group and member numbers for the relevant unit frame. If you want to halt any further processing of the mouseover, return something that evaluates to true (basically, anything that isn't ''false'' or ''nil''), and nothing else will be done with the mouseover (no more event handlers will be called, nor will the current mode's UnitMouseOver be called). * unitmouseover *: Supplied arguments: group #, member # *: Expected returns: ''nil'' or ''false'' to continue processing the mouseout, anything else to stop processing the mouseout. *: Description: This event is fired whenever the mouse is moved away from one of Squared's unit frames. It supplies the group and member numbers for the relevant unit frame. If you want to halt any further processing of the mouseout, return something that evaluates to true (basically, anything that isn't ''false'' or ''nil''), and nothing else will be done with the mouseout (no more event handlers will be called, nor will the current mode's UnitMouseOut be called). * cleargroups *: Supplied arguments: the table containing groups information before it is cleared. *: Expected returns: none *: Description: This event fires right before Squared clears its group data (and thus invalidates any old references to unit objects). Any plugin that stores references to unit frame objects should register this to know when it needs to clear its cache of those references and start afresh. == Additional API Functions == In addition to the mode and event handler capabilities, Squared also provides some functions to get, set, and manipulate data. * Squared.GetSetting("''option-name''") *: Returns the value of the specified option. * Squared.SetSetting("''option-name''", ''value'') *: Assigns the specified value to an option. The type of ''value'' depends on the option being set. * Squared.ReanchorGroups() *: Tells Squared to re-layout the display. * Squared.ReanchorGroup(''group'') *: Tells Squared to re-layout the members of a specific group. * Squared.GetUnit(''group'', ''member'') *: Returns a table containing the SquaredUnitFrame object for the specified unit. * Squared.GetUnitByName(''name'') *: Returns a table containing the SquaredUnitFrame object for the unit with a name matching the specified string. * Squared.AddUnit(''group'', ''member'', ''show'') *: Adds a new unit at the specified location, and returns a table containing the SquaredUnitFrame object corresponding to the added unit. Will automatically add the specified group if it doesn't exist. * Squared.AddGroup(''group'') *: Adds the specified group to Squared's layout. Not really necessary to call outside of Squared most of the time given that AddUnit will automatically add the group if need be. Mostly useful if you want to move existing units to a new group. * Squared.GetGroup(''group'') *: Returns the group table containing all of the SquaredUnitFrame objects for that group. * Squared.ClearGroups() *: Tells Squared to reset its groups table to empty. * Squared.ResetMode() *: Forces a reset of the current mode - basically, calls the current mode's OnUnload and then calls its OnLoad again. * Squared.SetMode(''newMode'') *: Tells Squared to load a certain mode (and unload the current mode first) - but won't do anything it the specified mode is already loaded. * Squared.GetMode() *: Returns the name of the current mode (a string). * Squared.ChangeMode(''shouldReset'') *: Asks Squared to check and see if it should change modes. If ''shouldReset'' is a true value, it will unload the current mode and load whatever mode it decides should be loaded, even if that mode was already loaded. Otherwise, it'll only unload the current and load the new mode if it decides a different mode needs to be loaded than the currently active one.
Markup Type: *

The type of markup for this entry. Click here for details.