DisplayRequest class

Applies to Windows and Windows Phone

Represents a display request.

Syntax


Public NotInheritable Class DisplayRequest

Attributes

[MarshalingBehavior(None)]
[Threading(STA)]
[Version(0x06020000)]

Members

The DisplayRequest class has these types of members:

Constructors

The DisplayRequest class has these constructors.

ConstructorDescription
DisplayRequest Creates an instance of the DisplayRequest class.

 

Methods

The DisplayRequest class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
RequestActive Activates a display request.
RequestRelease Deactivates a display request.

 

Remarks

To conserve power and extend battery life, the system reduces power to the computer if it does not detect any user activity for a certain amount of time. Depending on system power settings, the display may first be dimmed, a screen saver may be displayed, and eventually the display may be turned off as the system enters a low-power sleep state.

Apps that show video or run for extended periods without user input can request that the display remain on by calling DisplayRequest::RequestActive. When a display request is activated, the device's display remains on while the app is visible. When the user moves the app out of the foreground, the system deactivates the app's display requests and reactivates them when the app returns to the foreground.

Display requests are cumulative - each display request must be released with a separate call to DisplayRequest::RequestRelease. An app should keep track of the number of active display requests and make sure all are released (each with a corresponding call to DisplayRequest::RequestRelease) when the app no longer requires the display to remain on. For more information see:

Using display requests to keep the display on consumes a lot of power. Use these guidelines for best app behavior when using display requests.

  • Use display requests only when required, that is, times when no user input is expected but the display should remain on. For example, during full screen presentations or when the user is reading an e-book.
  • Release each display request as soon as it is no longer required.
  • Release all display requests when the app is suspended. If the display is still required to remain on, the app can create a new display request when it is reactivated.

Note  This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see Threading and Marshaling (C++/CX) and Using Windows Runtime objects in a multithreaded environment (.NET).

Windows Phone 8

This API is supported in native apps only.

Examples

The following code (taken from the display power state sample) shows how to activate, track, and release display requests.


''' <param name="sender"></param> 
''' <param name="e"></param> 
Private Sub Activate_Click(sender As Object, e As RoutedEventArgs) 
    ErrorTestBlock.Text = String.Empty 
    Dim b As Button = TryCast(sender, Button) 
    If b IsNot Nothing Then 
        Try 
            If g_DisplayRequest Is Nothing Then 
                ' This call creates an instance of the displayRequest object 
                g_DisplayRequest = New DisplayRequest() 
            End If 
        Catch ex As Exception 
            rootPage.NotifyUser("Error Creating Display Request: " & ex.Message, NotifyType.ErrorMessage) 
        End Try 
 
        If g_DisplayRequest IsNot Nothing Then 
            Try 
                ' This call activates a display-required request. If successful,  
                ' the screen is guaranteed not to turn off automatically due to user inactivity. 
                g_DisplayRequest.RequestActive() 
                drCount += 1 
                rootPage.NotifyUser("Display request activated (" & drCount & ")", NotifyType.StatusMessage) 
            Catch ex As Exception 
                rootPage.NotifyUser("Error:" & ex.Message, NotifyType.ErrorMessage) 
            End Try 
        End If 
    End If 
End Sub

''' <param name="sender"></param> 
''' <param name="e"></param> 
Private Sub Release_Click(sender As Object, e As RoutedEventArgs) 
    ErrorTestBlock.Text = String.Empty 
    Dim b As Button = TryCast(sender, Button) 
    If b IsNot Nothing Then 
        If g_DisplayRequest IsNot Nothing Then 
            Try 
                ' This call de-activates the display-required request. If successful, the screen 
                ' might be turned off automatically due to a user inactivity, depending on the 
                ' power policy settings of the system. The requestRelease method throws an exception  
                ' if it is called before a successful requestActive call on this object. 
                g_DisplayRequest.RequestRelease() 
                drCount -= 1 
                rootPage.NotifyUser("Display request released (" & drCount & ")", NotifyType.StatusMessage) 
            Catch ex As Exception 
                rootPage.NotifyUser("Error: " & ex.Message, NotifyType.ErrorMessage) 
            End Try 
        End If 
    End If 
End Sub 

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8

Namespace

Windows.System.Display
Windows::System::Display [C++]

Metadata

Windows.winmd

 

 

Show:
© 2014 Microsoft