Charms

Article
10/14/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Here's an introduction to Windows 8 charms, the controls available on the side of the screen for every Windows Store app.

When you swipe the screen from the right, or press the Windows key and C, or move your mouse pointer to the bottom right, the charms appear. This happens in every app automatically: you don’t need to write any code to make it appear. The nearest equivalent on iOS would be the UIActivityViewController.

Charms provide a consistent, system-wide menu for common tasks, including Searching, Sharing, Devices (which usually refers to printing, but is also used for streaming and other activities which require extra hardware), and Settings.

Although your app isn’t required to make use of charms, there are advantages to supporting it. Not only do charms provide an expected way of interacting with your app, but they also allow your app to share data. You may have used URL Schemes in iOS to share data between apps, in Windows 8 you use a concept called contracts: your app agrees to provide or accept data. You can pass images between different paint apps, or email information from a train timetable app – all possible thanks to the Share charm. Your app can also provide terms which will show up in Search, even when invoked from within other apps, and the Settings charm can be used create a location for your app preference controls (seeLoading and Saving Settings).

Example

Here's a C# example which uses the Share charm to accept text shared from other apps. If a block of text is selected in an app, this project will appear in the share list and will receive the text. First you must change the app manifest to use the share contract, and then you can add code that receives the text.

Writing an app that accepts shared text

First, create a new C# Windows Store app using the Blank App (XAML) project type.
Open the Package.appxmanifest file, and select Declarations.
From the Available Declarations pull-down, select Share Target.
Under Data Formats, enter Text.

Under Supported Filetypes, enter .txt.

Edit the file App.xaml.cs, and add the following method:

protected override async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
        {

// Add: using Windows.ApplicationModel.DataTransfer;
// Add: using System.Diagnostics;

            var data = args.ShareOperation.Data;
            var title = data.Properties.Title;
            var description = data.Properties.Description;

            String text;

            if (data.Contains(StandardDataFormats.Text)) 
            {
                text = await data.GetTextAsync();

                Debug.WriteLine("Text: " + text);       
                Debug.WriteLine("Title: " + title);
                Debug.WriteLine("Description: " + description);
            }
        }

Compile and run the project, and then switch to a different app, for example, Internet Explorer. Highlight some text, and open the charms. If you select the Share charm, you will see your app listed as a target. When you select it, your app will be launched and the text will be displayed in the Output window (press Ctrl and W, followed by O if the Output window is not currently visible).

Topics for iOS devs

Resources for iOS devs

Windows 8 controls for iOS devs

Windows 8 cookbook for iOS devs

Search

Guidelines and checklist for search (Windows Store apps)

Quickstart: Adding search to an app (Windows Store apps using C#/VB/C++ and XAML)

Quickstart: Adding search to an app (Windows Store apps using JavaScript and HTML)

Share

Guidelines for sharing content (Windows Store apps)

Sharing and exchanging data (Windows Store apps using C#/VB/C++ and XAML)

Sharing and receiving content (Windows Store apps using JavaScript and HTML)