win8_secondarytile_pin

Pin a secondary Live Tile for your game to the Windows 8 UI.

Syntax:

GML Code Example

win8_secondarytile_pin(tile_id, short_name, display_name, cmd_line_args, ds_list_options, image, wide_image, text_col);


Argument Description
tile_id A string that will uniquely identify the tile.
short_name A short name to display directly on the tile (a string).
display_name A name that is displayed in the tile's tooltip and when showing small tiles (a string).
cmd_line_args The command line arguments that will be added to the tile (as a string).
ds_list_options A ds_list that controls whether to show the game name or not on different sized tiles.
image An image for the normal (square) Live Tile.
wide_image An image for the wide Live Tile.
text_col the text colour (either "dark" or "light").


Returns: N/A


Description

This function will pin a secondary tile to the start menu of the Windows 8 UI associated with your game. These secondary tiles are designed to start your game from a certain point, like a save game or a store page. you must give the tile a tile_id string (which will then be used in the other secondary tile functions) and two names, the display name and the short name. The short name is a short string to be displayed directly on the tile (if chosen to do so from the ds_list options, explained below), and the display name is a generally longer descriptive string that will be shown as a "tooltip" when your Live Tile is set to small by the user.

The command line arguments are used to tell the game where to start when launched from the secondary tile, and follow the http format of "value&value". These values will then be parsed using the GML parameter_count and parameter_string functions.

The options to use when pinning a secondary tile must be added first into a ds_list and the index for the ds_list passed through to the function. These options control whether to show the game name on the tile or not and can only be "None" (for no text on either tile), or "ShowNameOnLogo" and "ShowNameOnWideLogo" to show the name on both tiles (you cannot show on one and not the other). These strings are added to the ds_list and the list index used in the function (as shown below).

Finally you need to add in the images that are going to be used for the tile notification, with one image for each of the two sizes (square and wide). These images can be either from a local source (in which case the directory to get the file from must be preceded by ms-appx:///. See the example given below) or from a URL. You can also define the text colour, although the Windows 8 UI limits this to simply "light" or "dark" for the text, with the colour itself being chosen by Windows based on the user settings.


Extended Example:

This extended example provides a brief overview of how you would detect the command line parameters for the pinned secondary tile and make your game react accordingly. The first thing you would need to do is create and pin the Live Tile to the Windows 8 UI using the following code (note that the function arguments are spread over several lines - this is done to make the example legible but it will work fine in GameMaker: Studio, although normally you would have all the arguments on one line):

GML Code Example

var optionsList = ds_list_create();
 ds_list_add(optionsList, "None");
 win8_secondarytile_pin(
    "Store.Tile",
    "MacSweeney Store",
    "The MacSweeney Game Store",
    "store=true&appBar=true",
    optionsList,
    "ms-appx:///" + working_directory + "MacSweeneyStoreTile.png",
    "ms-appx:///" + working_directory + "MacSweeneyStoreWideTile.png",
    "dark");
 

This code defines and pins a secondary Live Tile, with the parameters "store" and "appbar" set to true. When the user opens your game using this secondary tile, it will use the command line parameters that you have set, which means that you will need to have an instance in the first room of the game (on loading) to parse the parameters and setup the game accordingly. The following code in an example of how this can be achieved:

GML Code Example

for (var i = 0; i < parameter_count(); i ++;)
    {
    var param = parameter_string(i);
    if param == "appBar=enable")
       {
       win8_appbar_enable(true);
       }
    if (param == "store=true")
       {
       room_goto(rm_Store);
       }
    }
 

The above code will loop through all the available parameters and setup your game accordingly, in this case by activating the Windows 8 app bar and going to the specified room.





No Examples Submitted

Does this page need better examples? Be the first to Submit

No Edits Suggested

Is this page unclear or not descriptive enough? Suggest an edit to the page and with enough upvotes your changes will be made.

No Questions Have Been Ask

Do you have a question about this page? Ask it Here