win8_appbar_add_element(type, icon, label, section, tooltip, callback);
|type||The type of element to add, either "button" or "separator".|
|icon||The icon name.|
|label||The icon label.|
|section||The section of the App Bar to add the element too. Either "selection" or "global".|
|tooltip||the tool-tip string to explain the button on hover|
|callback||The script to call when the element is used (-1 for no callback).|
This function will add an element to the App Bar for your game
(the App Bar is accessed by right clicking on your game, but
will only appear if you have enabled it using the function win8_appbar_enable). The
function will return a unique identifier as a string that you can
store to use in other functions later.
You must first choose whether to add a "button" or a "separator", and then pick an icon for it if it is a button (for a separator you should use an empty string "" for this). For a complete list of all icons available for the App Bar please see here.
Next you have the label which is a short name that will be placed beneath the icon (this can be an empty string "" if you wish), and then you should set the section of the App Bar that you want the element to be added to. The section string "global" maps to the right of the App Bar and "selection" maps to left in LTR (left-to-right) layouts (the opposite is true in RTL (right-to-left) layouts).
Finally you have to give it a tooltip so that when your player hovers the mouse over it they can get some information on what it does, and a callback script. The callback script will be run whenever the button is pressed (if it is a separator, or you do not wish to do anything, you can set this to -1).
elementId = win8_appbar_add_element("button", "repair", "Game Settings", "selection", "Change the global game settings", scr_Settings);
elementId = win8_appbar_add_element("button", "pause", "Pause/Unpause", "selection", "Pause or unpause the game", scr_PauseGame);
elementId = win8_appbar_add_element("button", "clear", "Quit", "global", "Quit to desktop", scr_QuitGame);
The above code will switch on the App Bar, then add three buttons to it. The first two are on the left and will run a script to change the game settings or pause/unpause the game, while the third will run a script to end the game. All three have their unique id stored in an array in case we need to access them later.