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
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.
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):
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:
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.