Eclipse (library)
From WoWWiki
Visibility Options, also known as Eclipse, allows users the ability to hide frames, autohide frames that don't have the mouse over them, and to change the transparency of frames. It consists of four parts, the main addon, Eclipse, and three libraries:
Each of the three libraries have a function that allows a developer to register a frame that they want to be autohidden, hidden on transpertized. Simply calling one of these functions with the appropriate parameters will add both a GUI and a slash command based configuration option for the frame.
Look into each library for full information on its usage.
VisibilityOptions is a rather complex system so let me try to give you a run down of how things work. First of all the system needs to periodically check that the registered frames meet the setting that have been passed. This is because other frames throught the UI may hide, show or adjust the transparency of items, so that they are no longer what the VO requested settings are.
The main part of the Addon, Eclipse, handles this funcionality by maintaining a list of all frames that need to be hidden/shown, and transparentized. It checks each frame periodically to ensure that the settings are met.
Because Eclipse has no way of knowing if a frame that it has hidden should be showing or not, it allows frames to be setup with a list of requirements that can determine how it should noramally behave. (Ex. if the pet bar has been hidden, then if hiding of the bar is disabled, it should be shown, but only if the player has a pet. In this case Eclipse needs to know that if the player has no pet it should not show the bar)
Eclipse also keeps up with whether or not the mouse is hovering of a frame(if needed). This can be somewhat complicated as well. There is no way to simply ask each frame politely if the mouse is in the area above it, especially when the frame is hidden. So Eclipse needs to know the dimensions of each frame it checks, which it typically takes from the actaul dimensions of the checked frame. However, it's not this simple for all frames, as an example the Buffs frame is not actually one single frame, it's actually some 24 buttons. In this case we need to check the area starting at the top left of the top left button, and bottom right of the bottom right button. Eclipse provides several methods of specifying the dimensions of a frame. Including manually choose the sides of the frame, setting padding to be added to the sides of the frames, choosing a frame to use to determine each side of the frame, passing a variable to check for the sides, and passing a function to use to determine the side.
To give Eclipse the info it needs to appropriately handle a frame you should call the SetFrame function, see it's comments for further details.
Each update cycle, Eclipse first checks the requirements for all frames, then it checks all frames for the mouse(ones that don't meet requirements are considered to not have the mouse then it calls Lunar's update function to let Lunar deal with autohiding, finally it runs its own function to handle the actual updating of hiding/showing and transparency fo frames.
Eclipse Functions
Quick Tutorial
Registering a frame with Eclipse can be anything from very easy, to very complex. For most functions you will want to perform, it will be very easy. Eclipse uses a mentality that you should be able to provide as little information as you want, and that it can then make assumptions based on that.
Here is the most simplistic example:
Eclipse.registerForVisibility( {
name = "FrameName"; --The name of the config, in this case also the name of the frame
} );
This will register the frame with the name "FrameName" to be hideable, auto-hideable, and transparentizeable. It will show up in Khaos as "FrameName" and will have a description of for example "Check this to hide the FrameName". It will be placed in the Visibility Options section, and will have a slash command of /hide framename.
But you can customize these things, by providing more information to Eclipse:
Eclipse.registerForVisibility( {
name = "FrameName"; --The name of the config, in this case also the name of the frame
uiname = "Frame Name"; --This is the base name of this reg to display in the description and ui
slashcom = { "framename", "fn" }; --These are the slash commands
} );
Now in this case, we will have the display name be "Frame Name" instead of "FrameName", and we have the slash command be either "/hide framename" or "/hide fn", you can provide the slash command as either a string, or a table of as many strings as you want to register slash command aliases.
The Eclipse.registerForVisibility function is for the most part just a wrapper that calls "Eclipse.Lunar.registerForAutohide", "Eclipse.Solar.registerForTransparency", and "Eclipse.Total.registerForHide". Any data you pass to registerForVisibility will be passed on to all three of these functions. So to see the data that you can supply, you should look at the three functions.
There are only three options for registerForVisibility iteself, "nototal", "nolunar", and "nosolar", put simply if you set one of them to true, then the frame will not be registered with that function. nototal for hiding, nolunar for autohiding, and nosolar for transparentizing.
Example:
Eclipse.registerForVisibility( {
name = "FrameName"; --The name of the config, in this case also the name of the frame
uiname = "Frame Name"; --This is the base name of this reg to display in the description and ui
slashcom = { "framename", "fn" }; --These are the slash commands
nototal = true; --Don't register this for hiding
} );
Typically you would only want to prevent registration for one of the three methods if it was already being implemented in some other way. Like if you had an option in your addon to disable a frame, which would hide it, then it is not necessary to have Eclipse do the hiding.
In some cases you may want a single option that modifies an entire set of frames, this is done quite simply:
Eclipse.registerForVisibility( {
name = "FrameName"; --The name of the config, in this case also the name of the frame
frames = {"FrameName", "FrameNameHippo", "FrameNameMonkey"};
uiname = "Frame Name"; --This is the base name of this reg to display in the description and ui
slashcom = { "framename", "fn" }; --These are the slash commands
} );
You can even specify a numbered list, the following example will register "FrameName1", "FrameName2", and "FrameName3":
Eclipse.registerForVisibility( {
name = "FrameName"; --The name of the config, in this case also the name of the frame
frames = {name="PartyFrame", min=1, max=4};
uiname = "Frame Name"; --This is the base name of this reg to display in the description and ui
slashcom = { "framename", "fn" }; --These are the slash commands
} );
If necessary you can pass a format string in the name to get more control of how the characters are passed, and you can combine all the methods at once:
Eclipse.registerForVisibility( {
name = "FrameName"; --The name of the config, in this case also the name of the frame
frames = { {name="PartyFrame", min=1, max=4}, "MonkeyFrame", {name="Hippo%dFrame", min=2, max=10} };
uiname = "Frame Name"; --This is the base name of this reg to display in the description and ui
slashcom = { "framename", "fn" }; --These are the slash commands
} );
Another option that you may wish to consider using, is the "uisec" option. This determines what section the options should be put in for Khaos, you could for instance pass uisec as the id you passed when registering your Khaos option set. This would mean that the options would show up, under the same section as the rest of your addon's options. The step isn't necessary, but I recommend it, to help users find the options they want, and to help keep the Visibility Options section from getting too full of options.
Eclipse.registerForVisibility( {
name = "FrameName"; --The name of the config, in this case also the name of the frame
uisec = "AddonSetName"; --The id of the section/set in Khaos that you want your addons added to
uiname = "Frame Name"; --This is the base name of this reg to display in the description and ui
slashcom = { "framename", "fn" }; --These are the slash commands
} );
One other things you may need to watch for is the initial visibility state of frames. When you fisrt register a frame for auto/hiding Eclipse looks at the current state of the frame, is it hidden, is it transparent, and records this state. The main thing that can happen is that if the frame is the child of a hidden frame, it will seem to be hidden itself. In this case you may need to set the state.show value to true, so that Eclipse knows that though it seems to be hidden, it really isn't. Another way to achieve the same task is to call the Show function on your frame.
If there is something you need to do, such as specify the area to be used for mousing over an autohidden frame, or make the frame only show under certain conditions, or set initial transparency levels, then you should have a look at the registration functions for the Lunar, Solar, and Total.
A lot of the more advanced behaviors are achieved by calling Eclipse.SetFrame which is used to register a frame to be controlled by Eclipse, and tells it important things such as the initial state of the frame, the autohide demensions, and any requirements that have to be met for it to be shown. The registration functions call SetFrame on the frame or frames you pass when you register with them. And these functions in turn have a few options you can pass that will be passed on to SetFrame. You can actually achieve the same behavior by calling SetFrame first. You likely will never need to call SetFrame manually, but there are some cases where you may find it necessary, such as if you need to setup a requirement that uses a dynamically created function on a set of frames.
