MICROSOFT_PRESS_EBOOK_PROGRAMMING_WINDOWS_8_APPS_WITH_HTML_CSS_AND_JAVASCRIPT_PDF

There are two ways to implement this process in an app written in HTML and JavaScript: using WinRT
directly, or using the helpers in WinJS. Let’s look at these in turn for a simple Help command.
To know when the charm is invoked through WinRT, obtain the settings pane object through
Windows.UI.ApplicationSettings.SettingsPane.getForCurrentView and add a listener for its
commandsrequested event (this is a WinRT event, so be sure to remove the listener if necessary):
// The n variable here is a convenient shorthand
var n = Windows.UI.ApplicationSettings;
var settingsPane = n.SettingsPane.getForCurrentView();
settingsPane.addEventListener("commandsrequested", onCommandsRequested);
Within your event handler, create Windows.UI.ApplicationSettings.SettingsCommand objects for
each command, where each command has an id, a label, and an invoked function that’s called when
the command is tapped or clicked. These can all be specified in the constructor as shown below:
function onCommandsRequested(e) {
// n is still the shortcut variable to Windows.UI.ApplicationSettings
var commandHelp = new n.SettingsCommand("help", "Help", helpCommandInvoked);
e.request.applicationCommands.append(commandHelp);
}
The second line of code is where you then add these commands to the settings pane itself. You do
this by appending them to the e.request.applicationCommands object. This object is a WinRT
construct called a vector that manages a collection with commands like append and insertAt. In this
case we have a vector of SettingsCommand objects, and as you can see above, it’s easy enough to
append a command. You’d make such a call for each command, or you can pass an array of such
commands to the replaceAll method instead of append. What then happens within the invoked handler
for each command is the interesting part, and we’ll come back to that in the next section.
You can also prepopulate the applicationCommands vector outside of the commandsrequested event;
this is perfectly fine because your settings commands should be constant for the app. The Quickstart:
add app help topic shows an example of this, which I’ve modified here to show the use of replaceAll:
var n = Windows.UI.ApplicationSettings;
var settingsPane = n.SettingsPane.getForCurrentView();
var vector = settingsPane.applicationCommands;
//Ensure no settings commands are currently specified in the settings charm
vector.clear();
var commands = [ new settingsSample.SettingsCommand("Custom.Help", "Help", OnHelp),
new n.SettingsCommand("Custom.Parameters", "Parameters", OnParameters)];
vector.replaceAll(commands);
This way, you don’t actually need to register for or handle commandsrequested directly.
337