Cosmos developer's guide
From WoWWiki
 |
WARNING - OUT OF DATE
|
| Cosmos |
|---|
|
Cosmos Patcher |
Contents |
Coding Standard
Cosmos has a coding standard: Cosmos Coding Standard. AddOns submitted to Cosmos are expected to follow this standard.
Cosmos Registration
By registering your mod functions with Cosmos, you will make it easier and faster to configure and save your Mod settings. Cosmos will handle all storing and reloading of Cosmos settings and give you an easy to use Configuration GUI.
Registering Configurations
Usage
Cosmos_RegisterConfiguration(
cos_variable -- the global var used and string for the CVar, must begin
--> with the string "COS_"
cos_type -- CHECKBOX, SLIDER, BOTH, BUTTON, SEPARATOR, or SECTION
cos_string -- Associated string
cos_description -- A three line max description of the variable for the users
--> sake
cos_handerfunction -- Function called with value as first parameter, and second
--> as toggle state when changed.
cos_defaultcheckedvalue -- 1 = Checked, 0 = Unchecked
cos_defaultvalue -- Default value returned when checked
cos_min -- Minimum slider value
cos_max -- Maximum slider value
cos_substring -- Slider or button text
cos_sliderstep -- Increments at which the slider may move
cos_slidervaluetexton -- Toggle for the exact value display of a slider
cos_slidervalueappend -- Whats added to the end of the number
cos_slidervaluemultiplier -- Whats the value multiplied by for display.
);
Screenshot
http://vjeux.grabu.free.fr/JolCosmos/Cosmos_Config.jpg
Example of Section
Cosmos_RegisterConfiguration( "COS_MY", -- prefix that all options that should go in this section have to start with "SECTION", -- Type "My Stuff", -- Section Label "Contains my new options!" -- Mouseover );
Example of Separator
Cosmos_RegisterConfiguration( "COS_CLOCK_SEPARATOR", -- Keyword "SEPARATOR", -- Type "Clock", -- Separator Label "These are my clock options!" -- Mouseover );
Example of CheckBox
Cosmos_RegisterConfiguration( "COS_COS_PLAYERHPMPXPTXT", -- CVar "CHECKBOX", -- Type TEXT(COSMOS_CONFIG_PLHPMPXP), -- Short description TEXT(COSMOS_CONFIG_PLHPMPXP_INFO), -- Long description Cosmos_TurnOnPlayerHP, -- Callback 0 -- Default Checked/Unchecked );
Example of Button
Cosmos_RegisterConfiguration( "COS_CLOCK_RESET_POSITION", -- CVar "BUTTON", -- Type CLOCK_OPTION_RESET_POSITION, -- Short description CLOCK_OPTION_RESET_POSITION_INFO, -- Long description ResetClockPosition, -- Callback 0, -- Useless 0, -- Useless 0, -- Useless 0, -- Useless CLOCK_OPTION_RESET_POSITION_NAME -- Button text );
Example of Slider
Cosmos_RegisterConfiguration( "COS_MAINMENUBARREPOSITIONER_POSITION", -- CVar "SLIDER", -- Type TEXT(MAINMENUBARREPOSITIONER_POSITION), -- Short description TEXT(MAINMENUBARREPOSITIONER_POSITION_INFO), -- Long description MainMenuBarRepositioner_Position_Change, -- Callback 1, -- Default Checked/Unchecked MainMenuBarRepositioner_Position, -- Default slider value MAINMENUBARREPOSITIONER_POSITION_MIN, -- Minimum slider value MAINMENUBARREPOSITIONER_POSITION_MAX, -- max value MAINMENUBARREPOSITIONER_POSITION_SLIDER, -- slider "header" text 1, -- Slider steps 0, -- Text on slider? "", -- slider text append 1 -- slider multiplier );
Example of combined Slider/Checkbox
Cosmos_RegisterConfiguration( "COS_ONSCREENALERT_PARTYHEALTH_NOTIFICATION", -- CVar "BOTH", -- Type TEXT(ONSCREENALERT_PARTYHEALTH_NOTIFICATION), -- Short description TEXT(ONSCREENALERT_PARTYHEALTH_NOTIFICATION_INFO), -- Long description OnScreenAlert_Toggle_PartyHealthNotification_NoChat, -- Callback OnScreenAlert_PartyHealthNotification, -- Default Checked/Unchecked ONSCREENALERT_PARTY_MEMBER_HEALTH_LIMIT, -- Default slider value 0, -- Minimum slider value 1, -- Maximum slider value ONSCREENALERT_PARTYHEALTH_NOTIFICATION_SUBSTRING, -- Substring 0.01, -- Slider steps 1, -- Text on slider? ONSCREENALERT_PARTYHEALTH_NOTIFICATION_APPEND, -- Text to append on slider 100 -- Multiplier for slider value );
Accessing Configuration Information
It is possible to access the state of the current Cosmos configuration via global variables associated with your AddOn. If you have created a Slider, a global variable with the name of cos_variable exists which contains the current slider value. If you have created a Checkbox, a global variable with the name of cos_variable.."_X" exists, containing 1 or 0. You can access the configuration information by reading these variables.
To change the configuration information, it is not possible to just set the value of the global variable. Instead, you must let Cosmos know about the change via the Cosmos_UpdateValue function. You also must call CosmosMaster_Save to force Cosmos to synchronize the new value across all its variables and to make sure the modified configuration information is saved.
Example
Create a checkbox using
Cosmos_RegisterConfiguration( "COS_MY_CHECKSTATE", -- CVar "CHECKBOX", -- Type TEXT(MYMOD_CONFIG), -- Short description TEXT(MYMOD_CONFIG_INFO), -- Long description MyMod_Callback, -- Callback 0 -- Default Checked/Unchecked );
You can now read the state of the checkbox by
CurrentState = COS_MY_CHECKSTATE_X; -- Note the _X at the end
You can change the state of the checkbox by
Cosmos_UpdateValue("COS_MY_CHECKSTATE",CSM_CHECKONOFF,1); -- turn checkbox on, note the lack of _X
CosmosMaster_Save(); -- synchronize and save the new value
Registering Slash Commands
Allows you to register an in-game chat command with Cosmos's simple registration system. It will also cause your command to be listed with the /help or /eshelp command locally.
Usage
Cosmos_RegisterChatCommand( GroupID, Array of commands, handler of 1 argument, chaining instructions );
Example
comlist = { "/cver", "/cversion" };
desc = "Shows the current revision number of Cosmos.";
id = "COSMOSVERSION";
func = function (msg) CosmosMaster_ChatVersionDisplay(); end
Cosmos_RegisterChatCommand ( id, comlist, func, desc, CSM_CHAINNONE );
Registering Chat Watches
Allows you to register a command to be called when a condition is met within a block of text in incoming chat messages.
Usage
Cosmos_RegisterChatWatch ( id, typearray, handlerfunction, description );
Example
Cosmos_RegisterChatWatch ( "NOYELLS", {"YELL"}, function (msg) return 0; end );
This would create a function which disables yells by returning a 0 (indicating to halt all commands) whenever a type 'YELL' is seen.
Description is entirely for debugging and observational purposes.
You can watch the cosmos channel, just use CHANNEL_COSMOS instead of the channel type.
You can watch the cosmos party channel, just use CHANNEL_PARTY instead of the channel type.
Registering Cosmos Buttons
Allow you to create a button of your mod in the Cosmos Features Frame.
http://vjeux.grabu.free.fr/JolCosmos/Cosmos_CosmosPanel.jpg
Usage
Cosmos_RegisterButton ( name, description, ToolTip_description, icon, callback, testfunction )
Example
Cosmos_RegisterButton (
"Name",
"Little Text",
"Long Tool Tip Text",
"Interface\\Icons\\Spell_Holy_BlessingOfStrength",
function()
if (GamesListFrame:IsVisible()) then
HideUIPanel(GamesListFrame);
else
ShowUIPanel(GamesListFrame);
end
end,
function()
if (UnitInParty("party1")) then
return true; -- The button is enabled
else
return false; -- The button is disabled
end
end
);
Description must not be more than 2 words, you should put a longer description in the tool tip.
Using the Cosmos Context Menu
The Cosmos Context Menu is a mouse-selected menu which can contain headers, buttons and up to 2 submenus.
Screenshot
http://vjeux.grabu.free.fr/ttrackaddition.JPG
Usage
CosmosMaster_MenuOpen( Menu, -- Table pointing to the menu Type, -- Menu Type (0 or 1) ParentName, -- The name of the frame to attach to X, -- X offset Y -- Y offset );
Usable Types
--[[ List of button attributes
======================================================
info.text = [STRING] -- The text of the button
info.func = [function()] -- The function that is called when you click the button
info.checked = [nil, 1] -- Check the button
info.isTitle = [nil, 1] -- If it's a title the button is disabled and the font color is set to
--> yellow
info.disabled = [nil, 1] -- Disable the button and show an invisible button that still traps the
--> mouseover event so menu doesn't time out
info.hasArrow = [nil, 1] -- Show the expand arrow for multilevel menus
info.hasColorSwatch = [nil, 1] -- Show color swatch or not, for color selection
info.r = [1 - 255] -- Red color value of the color swatch
info.g = [1 - 255] -- Green color value of the color swatch
info.b = [1 - 255] -- Blue color value of the color swatch
info.swatchFunc = [function()] -- Function called by the color picker on color change
info.hasOpacity = [nil, 1] -- Show the opacity slider on the colorpicker frame
info.opacity = [0.0 - 1.0] -- Percentatge of the opacity, 1.0 is fully shown, 0 is transparent
info.opacityFunc = [function()] -- Function called by the opacity slider when you change its value
info.cancelFunc = [function(previousValues)] -- Function called by the colorpicker when you click the
--> cancel button (it takes the previous values as its
--> argument)
info.notClickable = [nil, 1] -- Disable the button and color the font white
info.notCheckable = [nil, 1] -- Shrink the size of the buttons and don't display a check box
info.owner = [Frame] -- Dropdown frame that "owns" the current dropdownlist
info.keepShownOnClick = [nil, 1] -- Don't hide the dropdownlist after a button is clicked
]]--
--[[ Cosmos Only
info.hideParentOnClick = [nil, 1] -- hides the parent UI menu as well
info.hideAllParentsOnClick = [nil, 1] -- hides all parents of the current menu too.
]]--
Example
local info = { }
info[1] = { text = " TellTrack", isTitle = 1 };
info[2] = { text = "Whisper", func = TellTrack_Menu_Whisper };
info[2] = { text = "Who", func = TellTrack_Menu_Who };
info[3] = { text = "Groupe Invite", func = TellTrack_Menu_GroupeInvite };
info[4] = { text = "Add to Friend", func = TellTrack_Menu_AddToFriend };
info[5] = { text = "Delete", func = TellTrack_Menu_Delete };
info[6] = { text = "|cFFCCCCCC------------|r", disabled = 1, notClickable = 1 };
-- Submenu
info[7] = { text = "Options", hasArrow = 1,
[1] = { text = "Submenu Title", isTitle = 1 },
[2] = { text = "Submenu Action", func = function() end },
};
info[8] = { text = "Cancel", func = function () end };
CosmosMaster_MenuOpen(info, 0, this:GetName(), 0, 0);
Of course, in real code, you'd use TEXT(LOCALIZATION_REFERENCE) since you'd want people to find it easy to translate your AddOn. :) --Sarf
