FuBarPlugin-2.0

From WowAce Wiki
Jump to: navigation, search
Summary
Lib: FuBarPlugin-2.0
A library to provide a means create a FuBar-compatible plugin.
TOC 2.4 (20400)
Category Libraries
Author ckknight
Details
Version 2.0 $Revision$
OptionalDeps Ace2, FuBar
Links
Betas Ace SVN Zip
Changelog FishEye

Contents

Ability Vanish.png This addon page is not claimed.
Please see Unclaimed Addon Pages for more details.

Example

 ExampleFu = AceLibrary("AceAddon-2.0"):new("FuBarPlugin-2.0")
 
 function ExampleFu:IsValue()
   return self.value
 end
 
 function ExampleFu:ToggleValue()
   self.value = not self.value
   self:Update()
 end
 
 -- using an AceOptions data table
 ExampleFu.OnMenuRequest = {
   type = 'group',
   args = {
       value = {
           type = "toggle",
           name = "Value",
           desc = "Description",
           get = "IsValue",
           set = "ToggleValue",
       }
   }
 }
 
 ExampleFu.num = 0
 function ExampleFu:OnDataUpdate()
   self.num = self.num + 1
 end
 
 function ExampleFu:OnTextUpdate()
   self:SetText(string.format("Num: %d", self.num))
 end
 
 local tablet = AceLibrary("Tablet-2.0")
 function ExampleFu:OnTooltipUpdate()
   local cat = tablet:AddCategory(
       'text', "Alpha",
       'columns', 2,
       'child_textR', 1,
       'child_textG', 1,
       'child_textB', 0,
       'child_textR2', 1,
       'child_textG2', 1,
       'child_textB2', 1
   )
   
   cat:AddLine(
       'text', "Apple",
       'text2', "Banana"
   )
   
   cat:AddLine(
       'text', "Cookie",
       'text2', "Monster"
   )
   
   cat = tablet:AddCategory(
       'text', "Bravo",
       'columns', 2,
       'child_textR', 1,
       'child_textG', 1,
       'child_textB', 0,
       'child_textR2', 1,
       'child_textG2', 1,
       'child_textB2', 1
   )
   
   cat:AddLine(
       'text', "Dung",
       'text2', "Beetle"
   )
   
   cat:AddLine(
       'text', "Elephant",
       'text2', "Tamer"
   )
   
   tablet:SetHint("Click to do something")
   -- as a rule, if you have an OnClick or 
   -- OnDoubleClick or OnMouseUp or OnMouseDown, 
   -- you should set a hint.
 end
 
 function ExampleFu:OnClick()
   -- do something
 end

API - Automatically Provided

:GetTitle()

Returns the localized name of the plugin, not including the "FuBar - " part.

Returns

string - the localized name of the plugin, not including the "FuBar - " part.

Example

 local title = self:GetTitle()

:GetName()

Returns the name of the plugin.

Returns

string - name of the plugin.

Remarks

This is here for FuBar core to communicate properly.

Example

 local name = self:GetName()

:GetCategory()

Returns the category of the plugin.

Returns

string - category of the plugin.

Remarks

This is here for FuBar core to communicate properly.

Example

 local category = self:GetCategory()

:SetFontSize(size)

Changes the size and width of your plugin.

Args

size 
number - new font size

Example

 -- You should not call this manually.

:GetFrame()

Returns the frame for the plugin.

Returns

frame - frame for the plugin.

Remarks

This is here for FuBar core to communicate properly.

Example

 local frame = self:GetFrame()

:Show()

Shows the plugin, enables the plugin if previously disabled, and calls== :Update().

Example

 self:Show()

:Hide()

Hides the plugin, disables the plugin if cannot hide without standby.

Example

 self:Hide()

:GetPanel()

Returns the panel for the plugin.

Returns

object - panel for the plugin.

Remarks

This is here for FuBar core to communicate properly.

Example

 local panel = self:GetPanel()

:IsTextColored()

Returns whether the text has color applied.

Returns

boolean - whether the text has color applied.

Example

 local colored = self:IsTextColored()

:ToggleTextColored()

Toggles whether the text has color applied

Example

 self:ToggleTextColored()

:IsMinimapAttached()

Returns whether the plugin is attached to the minimap.

Returns

boolean - whether the plugin is attached to the minimap.

Example

 local attached = self:IsMinimapAttached()

:ToggleMinimapAttached()

Toggles whether the plugin is attached to the minimap.

Example

 self:ToggleMinimapAttached()

:Update()

Calls :UpdateData(), :UpdateText(), and :UpdateTooltip(), in that order.

Example

 self:Update()

:UpdateDisplay()

Calls :UpdateText() and :UpdateTooltip(), in that order.

Example

 self:UpdateDisplay()

:UpdateData()

Calls :OnDataUpdate() if it is available and the plugin is not disabled.

Example

 self:UpdateData()

:UpdateText()

Calls== :OnTextUpdate() if it is available and the plugin is not disabled.

Example

 self:UpdateText()

:UpdateTooltip()

Calls :OnTooltipUpdate() if it is available, the plugin is not disabled, and the tooltip is shown.

Example

 self:UpdateTooltip()

:SetIcon("path" or default)

Sets the path to the icon for the plugin.

Args

"path" 
string - The path to the icon.
default 
boolean - Set to "icon.blp" or "icon.tga"

Example

 self:SetIcon("Interface\\AddOns\\" .. self.folderName .. "\\otherIcon")

:GetIcon()

Returns the path to the icon for the plugin, or nil if plugin has no icon.

Returns

string - The path to the icon for the plugin. nil - no icon

Example

 local path = self:GetIcon()

:CheckWidth([force])

Checks the current width of the icon and text, then updates frame to expand/shrink to it if necessary.

Args

force 
boolean - if true, Shrink/expand no matter what, otherwise if the width is less than 8 pixels smaller, don't shrink.

Example

 self:CheckWidth(true)

:SetText("text")

Sets the text of the plugin. Should only be called from within== :OnTextUpdate()

Args

"text" 
string - text to set the plugin to. If not given, set to title.

Example

 function myAddon:OnTextUpdate()
   self:SetText("Hello")
 end

:GetText()

Returns the current text of the plugin.

Returns

string - The current text of the plugin.

Example

 local text = self:GetText()

:IsIconShown()

Returns whether the icon for the plugin is showing.

Returns

boolean - whether the icon for the plugin is showing.

Example

 local isIconShowing = self:IsIconShown()

:ToggleIconShown()

Toggles whether the icon for the plugin is showing.

Example

 self:ToggleIconShown()

:ShowIcon()

Shows the icon of the plugin if hidden.

Example

 self:ShowIcon()

:HideIcon()

Hides the icon of the plugin if shown.

Example

 self:HideIcon()

:IsTextShown()

Returns whether the text for the plugin is showing.

Returns

boolean - whether the text for the plugin is showing.

Example

 local isTextShowing = self:IsTextShown()

:ToggleTextShown()

Toggles whether the text for the plugin is showing.

Example

 self:ToggleTextShown()

:ShowText()

Shows the text of the plugin if hidden.

Example

 self:ShowText()

:HideText()

Hides the text of the plugin if shown.

Example

 self:HideText()

:IsTooltipDetached()

Returns whether the tooltip is detached.

Returns

boolean - Whether the tooltip is detached.

Example

 local detached = self:IsTooltipDetached()

:ToggleTooltipDetached()

Toggles whether the tooltip is detached.

Example

 self:ToggleTooltipDetached()

:DetachTooltip()

Detaches the tooltip from the plugin.

Remarks

This does nothing if already detached.

Example

 self:DetachTooltip()

:ReattachTooltip()

Reattaches the tooltip to the plugin.

Remarks

This does nothing if already attached.

Example

 self:ReattachTooltip()

:GetDefaultPosition()

Returns the default position of the plugin.

Returns

string - default position of the plugin.

Remarks

This is here for FuBar core to communicate properly.

Example

 local pos = self:GetDefaultPosition()

:SetPanel(panel)

Sets the current panel to the one provided.

Args

panel 
object - FuBar-style panel

Remarks

This is here for FuBar core to communicate properly.

Example

 -- you would never call this manually

:IsLoadOnDemand()

Returns whether the plugin is LoadOnDemand.

Example

 local lod = self:IsLoadOnDemand()

:IsDisabled()

Returns whether the plugin is disabled.

Remarks

This is a subversive checking of== :IsActive()

Example

 local disabled = self:IsDisabled()

:CreateBasicPluginFrame(["name"])

Returns a frame set up and ready to customize.

Args

["name"] 
string - name of the frame

Returns

frame - a frame with the basic scripts to be considered a plugin frame.

Example

 MyPlugin.frame = MyPlugin:CreateBasicPluginFrame("FuBar_MyPluginFrame")

:CreatePluginChildFrame("frameType" [, "name"] [, parent])

Returns a child frame for your plugin's custom frame to use.

Args

"frameType" 
string - type of the frame, e.g. "Frame", "Button", etc.
["name"] 
string - name of the frame
[parent] 
frame - parent frame

Returns

frame - a child frame

Example

 local child = self:CreatePluginChildFrame("Frame", nil, self.frame)

:OpenMenu()

Opens the dewdrop menu.

Example

 self:OpenMenu()

:AddImpliedMenuOptions([level])

This is called during the menu creation phase. Can be added within== :OnMenuRequest().

Args

[level] 
number - Current level in the dropdown tree. If not given, 1 (toplevel) is assumed.

Remarks

This is only needed if .overrideMenu is set to true.

Example

 function MyPlugin:OnMenuRequest()
   self:AddImpliedMenuOptions()
 end

.frame

frame - This is automatically created if not set. It is a basic plugin frame, plus text and an icon.

.textFrame

frame - The frame which hold the text portion. Not created if .frame is custom-created

.iconFrame

frame - The frame which hold the icon portion. Not created if .frame is custom-created

API - User-defined

.title

string - The title of your plugin (May start with "FuBar - ", which'll be truncated out). This is required for== :GetTitle() to work properly.

Note: This is automatically provided if you use AceAddon-2.0

.name

string - A unique identifier for your plugin (likely your addon's folder name)

Note: This is automatically provided if you use AceAddon-2.0

.category

string - An Ace2 Category

Note: This is automatically provided if you use AceAddon-2.0

.frame (Optional)

frame - If set, it will replace the standard frame.

.hasNoText

boolean - If set to true, then it will be a text-less frame.

.hasIcon

boolean 
If set to true, uses the "icon.tga" or "icon.blp" in the plugin's folder.
string 
path to the icon.

.hasNoColor

boolean - If set to true, then it is assumed that no color will be in the text (and thus not show the menu item)

.cannotHideText

boolean - If set to true, then the menu item to hide text will not be shown.

.overrideMenu

boolean - If set to true, then the menu will not show any of the standard menu items

Remarks

This only applies if .OnMenuRequest is a method.

.hideMenuTitle

boolean - If set to true, the plugins name will not be added to the top of the menu as a header.

.defaultPosition

string -

"LEFT" 
show on the left. (default if not given)
"CENTER" 
show in the center.
"RIGHT" 
show on the right.
"MINIMAP" 
show on the minimap.

.defaultMinimapPosition

number - Angle on the minimap, in degrees. [0, 360)

.clickableTooltip

boolean - Whether you can drag your mouse onto the tooltip and click a line

.tooltipHiddenWhenEmpty

boolean - Whether the detached tooltip is hidden when it is empty.

.cannotDetachTooltip

boolean - Whether the tooltip cannot be detached from the plugin text.

Remarks

Normally, a tooltip can detach. This should be set if there is no relevant data in the tooltip.

.independentProfile

boolean - If set to true, then the profile setting will not be stripped from .OnMenuRequest, and FuBar will not set the plugin's profile when it changes.

Remarks

non-FuBar-centric plugins should set this to true.

.hideWithoutStandby

boolean - If set to true, the plugin will be able to be hidden without putting the entire addon into standby.

Remarks

non-FuBar-centric plugins should set this to true.

.OnMenuRequest or :OnMenuRequest(level, value, inTooltip, valueN_1, valueN_2, valueN_3, valueN_4)

table 
AceOptions data table. If this is provided, the default menu options are injected in.
function 
Gives the info for the Dewdrop-2.0 menu of the addon.

Args

level 
number - The depth of the menu. 1 means toplevel, 2 means 2nd level, etc
value 
string - The value provided from your last expanding button
inTooltip 
boolean - Whether the right click initiated from a detached tooltip.
valueN_1 
string - The value provided from your level N-1, where N is the current level.
valueN_2 
string - The value provided from your level N-2.
valueN_3 
string - The value provided from your level N-3.
valueN_4 
string - The value provided from your level N-4.

Remarks

If you set .overrideMenu to true, be sure to call== :AddImplicitMenuOptions([level]).

You only need to check for inTooltip if you set .canDetachTooltip to true.

It is much more recommended to use an AceOptions data table rather than straight Dewdrop coding.

Example

 local Dewdrop = AceLibrary("Dewdrop-2.0")
 function MyAddon:OnMenuRequest(level, value, inTooltip)
   if not inTooltip then
       Dewdrop:AddLine(
           'text', "Good",
           'arg1', self,
           'func', "ToggleGoodness",
           'checked',  self:IsGood(),
           'tooltipTitle', "Good",
           'tooltipText', "Toggle the goodness factor"
       )
   end
 end
 -- or, with an AceOptions data table
 MyAddon.OnMenuRequest = {
   type = 'group',
   === Args === = {
       good = {
           type = 'toggle',
           name = "Good",
           desc = "Toggle the goodness factor",
           get = "IsGoodness",
           set = "ToggleGoodness"
       }
   }
 }

:OnDataUpdate()

Called when data should be updated.

Remarks

Do not call this on your own, instead call== :UpdateData()

Example

 function MyAddon:OnDataUpdate()
   self.num = self.num + 1
 end

:OnTextUpdate()

Called when text should be updated.

Remarks

Do not call this on your own, instead call== :UpdateText()

Example

 function MyAddon:OnTextUpdate()
   self:SetText("Num: " .. self.num)
 end

:OnTooltipUpdate()

Called when tooltip should be updated.

Remarks

Do not call this on your own, instead call== :UpdateTooltip()

This uses Tablet-2.0 to create the tooltip. Refer to it for more in-depth information.

Example

 local Tablet = AceLibrary("Tablet-2.0")
 function MyAddon:OnTooltipUpdate()
   local cat = Tablet:AddCategory(
       'columns', 2
   )
   
   cat:AddLine(
       'text', "Hello",
       'text2', "there,"
   )
   
   cat:AddLine(
       'text', "old",
       'text2', "friend!"
   )
 end

:OnClick("button")

Called when the plugin is clicked by the user.

Args

button 
string - the button clicked. Either "LeftButton", "RightButton", "MiddleButton", "MouseButton4", "MouseButton5", or so on.

Remarks

This only catches left-button clicks by default. To register for more clicks, use self.frame:RegisterForClicks("LeftButton", "RightButton") and so forth.

Example

 function MyAddon:OnClick()
   self:DoSomething()
 end

:OnDoubleClick("button")

Called when the plugin is double-clicked by the user.

Args

button 
string - the button clicked. Either "LeftButton", "RightButton", "MiddleButton", "MouseButton4", "MouseButton5", or so on.

Example

 function MyAddon:OnDoubleClick()
   self:DoSomethingElse()
 end

:OnMouseDown("button")

Called when the mouse is pressed on the plugin. (click, but not un-click)

Args

button 
string - the button clicked. Either "LeftButton", "RightButton", "MiddleButton", "MouseButton4", "MouseButton5", or so on.

Example

 function MyAddon:OnMouseDown(button)
   if (button == "LeftButton") then
       self:DoSomethingImportant()
   end
 end

:OnReceiveDrag()

Called when an item is dragged to the plugin.

Remarks

When this is dragged to the plugin, the item should still be in the cursor.

Example

 function MyAddon:OnReceiveDrag()
   self:DoSomethingReallyImportant()
 end