Windows Phone 8 : Understanding the Application Execution Model - Running Under the Lock Screen - Lock Screen Management

Note

Running under the lock screen is not an alternative to implementing efficient transient state persistency. Recall that an app may still be tombstoned if the phone runs low on memory.

Tip

To engage the lock screen within the Windows Phone emulator, press F12 on the computer keyboard twice. F12 emulates the power button on the phone. Pressing it once locks the phone and turns off the display; twice turns the display on again with the lock screen engaged. The mouse can be used to disengage the lock screen by sliding the lock screen up.

To engage the lock screen when debugging on an actual device (or on the emulator), use the Simulation Dashboard, which can be opened by selecting Simulation Dashboard from the Tools menu in Visual Studio.

Lock Screen Management

I created a reusable class called LockScreenService that makes it easy to manage your app’s lock screen policy. The class implements a custom ILockScreenService interface that has the following three properties:

- RunningUnderLockScreen—Gets a value indicating whether the app is running under the lock screen

- RunningUnderLockScreenEnabled—Allows you to set whether the app is allowed to run under the lock screen

- UserPrompted—Allows your app to remember whether the user has been prompted to allow running under the lock screen

At your app’s first launch you query the UserPrompted property. If false, you present a dialog asking the user whether it is okay to run under the lock screen, and you set the RunningUnderLockScreenEnabled property accordingly. You subscribe to the PropertyChanged event of the LockScreenService, and when the RunningUnderLockScreen property changes, it indicates that the lock screen has been either engaged or disengaged. LockScreenService is a singleton and subclasses NotifyPropertyChangeBase for property change notification (see Listing 1). The private constructor attempts to retrieve the UserPrompted and RunningUnderLockScreenEnabled property values from isolated storage settings. It then subscribes to the PhoneApplicationFrame.Obscured and Unobscured events.

When the Obscured event is raised, the RunningUnderLockScreen property is set.

The LockScreenService class is located in the Shell directory of the WPUnleashed project.

LISTING 1. LockScreenService Class (excerpt)

public class LockScreenService : NotifyPropertyChangeBase, ILockScreenService
{
    static readonly string promptedKey
               = "UserPromptedToAllowRunningUnderLockScreen";
    static readonly string runningEnabledKey = "RunningUnderLockScreenEnabled";

    LockScreenService()
    {
        IsolatedStorageSettings settings
               = IsolatedStorageSettings.ApplicationSettings;
        bool prompted;
        if (settings.TryGetValue(promptedKey, out prompted))
        {
            UserPrompted = prompted;
        }

        bool enabledValue;
        if (settings.TryGetValue(runningEnabledKey, out enabledValue))
        {
            RunningUnderLockScreenEnabled = enabledValue;
        }

        var frame = (PhoneApplicationFrame)Application.Current.RootVisual;
        frame.Obscured += (o, args) => RunningUnderLockScreen = args.IsLocked;
        frame.Unobscured += (o, args) => RunningUnderLockScreen = false;
    }
    ...
}

When either of the UserPrompted or RunningUnderLockScreenEnabled properties is set, its new value is saved to isolated storage settings using a SaveSetting method, as shown:

void SaveSetting(string key, object value)
{
    IsolatedStorageSettings settings
        = IsolatedStorageSettings.ApplicationSettings;
    settings[key] = value;
    settings.Save();
}

When the RunningUnderLockScreenEnabled property is enabled, the idle detection mode is disabled, which allows the app to run under the lock screen. If disabled, the app must be restarted or deactivated before the idle detection mode can be enabled or an InvalidOperationException is raised. This is a limitation of the phone OS. See the following excerpt:

public bool RunningUnderLockScreenEnabled
{
    get
    {
        return runningUnderLockScreenEnabled;
    }
    set
    {
        var result = Assign(ref runningUnderLockScreenEnabled, value);

        if (result == AssignmentResult.Success)
        {
            if (runningUnderLockScreenEnabled)
            {
                PhoneApplicationService.Current.ApplicationIdleDetectionMode
                        = IdleDetectionMode.Disabled;
            }
            /* Idle detection mode cannot be enabled
               until the application is restarted. */

            SaveSetting(runningEnabledKey, runningUnderLockScreenEnabled);
        }
    }
}

The LockScreenView page and its associated LockScreenViewModel class demonstrate the use of the LockScreenService, and are located in the ExecutionModel directory of the WPUnleashed.Examples project. The LockScreenViewModel uses the MessageService to ask the user whether she wants to opt-in to running under the lock screen. When the manager’s RunningUnderLockScreen property changes, a string is written to the Visual Studio Output view (see Listing 2).

LISTING 2. LockScreenViewModel Class

public class LockScreenViewModel : ViewModelBase
{
    public LockScreenViewModel() : base("lock screen settings")
    {
        LockScreenService lockScreenService = LockScreenService.Instance;

        if (!lockScreenService.UserPrompted)
        {
            bool allow = MessageService.AskYesNoQuestion(
                "Is it OK to run under the phone's lock screen?");
            lockScreenService.RunningUnderLockScreenEnabled = allow;
            lockScreenService.UserPrompted = true;
        }

        lockScreenService.PropertyChanged
            += (o, args) =>
            {
                if (args.PropertyName == "RunningUnderLockScreen")
                {
                    Debug.WriteLine("RunningUnderLockScreen: "
                         + lockScreenService.RunningUnderLockScreen);
                }
            };
    }

    public bool RunningUnderLockScreenEnabled
    {
        get
        {
            return LockScreenService.Instance.RunningUnderLockScreenEnabled;
        }
        set
        {
            LockScreenService.Instance.RunningUnderLockScreenEnabled = value;
        }
    }
}

The LockScreenView XAML has a Windows Phone Toolkit ToggleSwitch control that is bound to the RunningUnderLockScreenEnabled viewmodel property, as shown in the following excerpt:

<StackPanel x:Name="ContentPanel">
    <toolkit:ToggleSwitch
        Header="run under lock screen"
        IsChecked="{Binding RunningUnderLockScreenEnabled, Mode=TwoWay}" />
</StackPanel>

Figure 1 shows the ToggleSwitch located on the LockScreenView page with the Run Under Lock Screen setting enabled.

FIGURE 1 LockScreenView page.

Running under the lock screen is the only way to allow your foreground app to run while the phone is idle. It should, however, be used with caution, because if an app continues to consume the device CPU, it may rapidly flatten the device battery.