Application Life-cycle Management in Windows 8

Activating

If the user “launches” the application using the Search contract, the application receives a call to the OnSearchActivated method, as you learned in Chapter 3. In this case, WinRT calls this procedure activation, as the name of the method implies. Activation is a more correct term, since the application is not launched by the user. The parameter args received by the OnLaunched method, as you learned in the preceding procedure, has a property called Kind that can assume the value of Search, but don’t be confused by this. When the user selects the target of a search, WinRT invokes the OnSearchActivated method on the App class and never invokes the OnLaunched events. Both event arguments, as well as other event args for other activation methods, implement a common interface; this explains why both of them have the same property. The following procedure clarifies these concepts.

Understand the OnSearchActivated method

In this procedure, you will modify the code for the App.xaml.cpp file to test the activation for search. You will use the Search Contract template from Visual Studio, which you learned about in Chapter 3.

1. Implement the Search contract by right-clicking the project in Solution Explorer and choosing Add New Item.

2. Scroll down in the Windows Store folder until you find the Search Contract item.

3. Click the Add button without changing the default name, and click Yes when the dialog box asks you to add the requested files.

   You will not implement a real search page in this procedure; you will just test the activation for searching.

   Adding the Search Contract item modifies the Package.appxmanifest file to declare the Search contract and adds the following line in the App.xaml.cpp file:

   void ALMEvents::App::OnSearchActivated(
      Windows::ApplicationModel::Activation::SearchActivatedEventArgs^ args)
   {
   
          // TODO: Register the Windows::ApplicationModel::Search::
          //   SearchPane::GetForCurrentView()->QuerySubmitted
          // event in OnWindowCreated to speed up searches once the
          // application is already running
   
           // If the app does not contain a top-level frame, it is possible that this
           // is the initial launch of the app. Typically this method and OnLaunched
           // in App.xaml.cpp can call a common method.
           auto previousContent = Window::Current->Content;
           auto rootFrame = dynamic_cast<Windows::UI::Xaml::Controls::Frame^>
               (previousContent);
           if (rootFrame == nullptr)
           {
                   // Create a Frame to act as the navigation context and associate it with
                   // a SuspensionManager key
                   rootFrame = ref new Frame();
                   Common::SuspensionManager::RegisterFrame(rootFrame, "AppFrame");
   
                   auto prerequisite = Concurrency::task<void>([](){});
                   if (args->PreviousExecutionState ==
                       ApplicationExecutionState::Terminated)
                   {
                           // Restore the saved session state only when appropriate,
                           // scheduling the final launch steps after the restore is
                           // complete
                           prerequisite = Common::SuspensionManager::RestoreAsync();
                   }
                   prerequisite.then([=](Concurrency::task<void> prerequisite)
                   {
                           try
                           {
                                   prerequisite.get();
                           }
                           catch (Platform::Exception^)
                           {
                                   // If restore fails, the app should proceed as though
                                   // there
                                   // was no restored state.
                           }
   
                           // TODO: Navigate to the initial landing page of the app as if
                           // it were launched. This allows the user to return to your app
                           // from the search results page by using the back button.
   
                           //Navigate to the search page
                           rootFrame->Navigate(TypeName(
                              SearchResultsPage::typeid), args->QueryText);
                           // Place the frame in the current Window
                           Window::Current->Content = rootFrame;
                           // Ensure the current window is active
                           Window::Current->Activate();
   
                   }, Concurrency::task_continuation_context::use_current());
           }
           else
           {
                   //Navigate to the search page
                   rootFrame->Navigate(TypeName(SearchResultsPage::typeid),
                       args->QueryText);
                   // Ensure the current window is active
                   Window::Current->Activate();
           }
   }

4. Add the following three bold lines just at the beginning of the OnSearchActivated method:

   void ALMEvents::App::OnSearchActivated(
        Windows::ApplicationModel::Activation::SearchActivatedEventArgs^ args)
   {
       Platform::String^ message = "App Activated by the Search Contract";
       auto dia = ref new Windows::UI::Popups::MessageDialog(message, "ALM Events");
       dia->ShowAsync();
   
       ...

5. Deploy the application. If you haven’t closed the application in the previous procedure yet, activate it and press the Close button or use Task Manager to kill the application.

6. Press Windows+Q, type something in the Search box, and select the ALMEvents application.

7. Verify that the dialog box displays the message “App Activated by the Search Contract.”

   You will not receive the dialog box for the application launching because the application was not launched by the user but activated for a search. Visual Basic, C#, and C++ application base classes expose different methods to respond to launch and search activations, while WinJS exposes just a generic activation function where you can test the activation kind property of the event args.

8. Close the application using Alt+F4.

If the user shares some content from another application, the target application receives a different activation called sharing target activation (OnSharingTargetActivated is the name of the corresponding method). You will learn about this kind of activation and the Sharing contract in Chapter 6.

There are other types of activation, each one corresponding to an operation done by the user. Table 4-1 summarizes the principal activation types.

Table 4-1 List of Windows Runtime activations

Since there are many types of activations, if you want to perform some action not related to a specific type of activation, you can override the OnInitialize method on the application class. This method is called from the runtime immediately after the creation of the application instance and before the specific method for a particular activation.