CoreDispatcher CoreDispatcher CoreDispatcher Class

Provides the Windows Runtime core event message dispatcher. Instances of this type are responsible for processing the window messages and dispatching the events to the client.

Syntax

Declaration

public sealed class CoreDispatcherpublic sealed class CoreDispatcherPublic NotInheritable Class CoreDispatcher

Remarks

Instances of this type can be obtained from the CoreDispatcher property. The current CoreWindow instance can be obtained by calling GetForCurrentThread().

void MyCoreWindowEvents::Run() // this is an implementation of IFrameworkView::Run() used to show context. It is called by CoreApplication::Run().
{
    CoreWindow::GetForCurrentThread()->Activate();

    /...

    CoreWindow::GetForCurrentThread()->Dispatcher->ProcessEvents(CoreProcessEventsOption::ProcessUntilQuit);
}

Properties summary

Gets and sets the priority of the current task.

Gets a value that specifies whether the event dispatcher provided by this instance of CoreWindow has access to the current thread or not.

Methods summary

Starts the dispatcher processing the input event queue for this instance of CoreWindow.

Schedules the provided callback on the UI thread from a worker thread, and returns the results asynchronously.

Schedules a callback on the UI thread from a worker thread at idle priority, and returns the results asynchronously.

Queries whether the caller should yield if there are items in the task queue of higher priority than the current task.

Queries whether the caller should yield if there are items in the task queue of the specified priority or higher.

Stops the dispatcher from processing any queued events.

Attempts to schedule the provided callback on the UI thread from a worker thread, and returns the results asynchronously.

Attempts to schedule a callback on the UI thread from a worker thread at idle priority, and returns the results asynchronously.

Events summary

Fired when an accelerator key is activated (pressed or held down).

Properties

  • CurrentPriority
    CurrentPriority
    CurrentPriority
    CurrentPriority

    Gets and sets the priority of the current task.

    public CoreDispatcherPriority CurrentPriority { get; set; }public CoreDispatcherPriority CurrentPriority { get; set; }Public ReadWrite Property CurrentPriority As CoreDispatcherPriority

    Property Value

  • HasThreadAccess
    HasThreadAccess
    HasThreadAccess
    HasThreadAccess

    Gets a value that specifies whether the event dispatcher provided by this instance of CoreWindow has access to the current thread or not.

    public bool HasThreadAccess { get; }public bool HasThreadAccess { get; }Public ReadOnly Property HasThreadAccess As bool

    Property Value

    • bool
      bool
      bool

      True if the event dispatcher has thread access; false it does not.

Methods

  • ProcessEvents(Windows.UI.Core.CoreProcessEventsOption)
    ProcessEvents(Windows.UI.Core.CoreProcessEventsOption)
    ProcessEvents(Windows.UI.Core.CoreProcessEventsOption)
    ProcessEvents(Windows.UI.Core.CoreProcessEventsOption)

    Starts the dispatcher processing the input event queue for this instance of CoreWindow.

    public void ProcessEvents(Windows.UI.Core.CoreProcessEventsOption options)public void ProcessEvents(Windows.UI.Core.CoreProcessEventsOption options)Public Function ProcessEvents(options As Windows.UI.Core.CoreProcessEventsOption) As void

    Parameters

    Remarks

    This method is called from the main app loop defined in the IFrameworkView method you implemented on your view provider. Typically, you call it once on each iteration of the loop. If you are creating a Windows Store app using DirectX with C++, call this method with CoreProcessEventsOption.

    If you are using another app model, such as XAML or JavaScript, you do not need to call this method. To avoid reentrancy scenarios in your Windows Store app using C++, C#, or Visual Basic with XAML, use the types and methods in the provided XAML namespaces, which call this method in the appropriate context.

    Also, this method fails if called recursively. When it fails, call RoOriginateError to obtain the error and the message supplied to an attached debugger.

  • RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)
    RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)
    RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)
    RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)

    Schedules the provided callback on the UI thread from a worker thread, and returns the results asynchronously.

    public IAsyncAction RunAsync(Windows.UI.Core.CoreDispatcherPriority priority,Windows.UI.Core.DispatchedHandler agileCallback)public IAsyncAction RunAsync(Windows.UI.Core.CoreDispatcherPriority priority,Windows.UI.Core.DispatchedHandler agileCallback)Public Function RunAsync(priority As Windows.UI.Core.CoreDispatcherPriority,agileCallback As Windows.UI.Core.DispatchedHandler) As IAsyncAction

    Parameters

    Returns

    Remarks

    If you are on a worker thread and want to schedule work on the UI thread, use RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler). Always set the priority to CoreDispatcherPriority or CoreDispatcherPriority, and ensure that any chained callbacks also use CoreDispatcherPriority or CoreDispatcherPriority.

    Note

    Callbacks scheduled with CoreDispatcherPriority priority are called when there are no pending input events. Use the CoreDispatcherPriority priority to make your app UI more responsive. To schedule background tasks, use RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler).

    To spin off a worker thread from the UI thread, do not use this method (RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) ). Instead, use one of the RunAsync(Windows.System.Threading.WorkItemHandler,Windows.System.Threading.WorkItemPriority) method overloads.

    Await a UI task sent from a background thread

    When you update your UI from a background thread by calling RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler), it schedules the work on the UI thread and returns control to the caller immediately. If you need to wait for async work to complete before returning, for example, waiting for user input in a dialog box, do not use RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) alone. RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) also does not provide a way for the task to return a result to the caller.

    In this example, RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) returns without waiting for the user input from the dialog box. (RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) returns as soon as the code in the lambda expression begins executing.)

    //DO NOT USE THIS CODE.
    
    await dispatcher.RunAsync(CoreDispatcherPriority.Normal, async () =>
    {
       await signInDialog.ShowAsync(); 
    });
    // Execution continues here before the call to ShowAsync completes.
    

    In this case, you need to use a TaskCompletionSource in combination with RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) to return a Task that you can await from your background thread, thereby pausing execution until the UI task completes. We recommend that you use the RunTaskAsync extension method from our task snippet library for this. It provides a robust solution that enables code running on a background thread to await a task that must run on the UI thread. See the Await a UI task sent from a background thread page for the code and example usage.

    Porting from .NET

    If you are porting from .NET code and using Dispatcher.BeginInvoke and Dispatcher.Invoke methods, note that RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) is asynchronous. There is no synchronous version. After you change Dispatcher.Invoke to RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler), your code must support the Windows Runtimeasync pattern and use the specific lambda syntax for your chosen language.

    Examples

    The following examples demonstrate the use of RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) to schedule work on the main UI thread using the CoreWindow 's event dispatcher.

    
    // 
    _dispatcher->RunAsync(Windows::UI::Core::CoreDispatcherPriority::Normal, 
                         ref new Windows::UI::Core::DispatchedHandler([this]()
    {
      _count++;
      TimerTextBlock->Text = "Total Running Time: " + _count.ToString() + " Seconds";
    }));
    
    
    // using CallbackContext::Any
    void Playback::DisplayStatus(Platform::String^ text)
    {
      _dispatcher->RunAsync(Windows::UI::Core::CoreDispatcherPriority::Normal, 
                            ref new Windows::UI::Core::DispatchedHandler([=]()
      {
        _OutputStatus->Text += text + "\n";
      }, CallbackContext::Any)); 
    }
    
    await dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
       rootPage.NotifyUser("The toast encountered an error", NotifyType.ErrorMessage);
    });
    
    var ignored = dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
       Scenario3OutputText.Text += outputText;
    });
    
  • RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)
    RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)
    RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)
    RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)

    Schedules a callback on the UI thread from a worker thread at idle priority, and returns the results asynchronously.

    public IAsyncAction RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler agileCallback)public IAsyncAction RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler agileCallback)Public Function RunIdleAsync(agileCallback As Windows.UI.Core.IdleDispatchedHandler) As IAsyncAction

    Parameters

    Returns

    Remarks

    The RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler) method is very similar to RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler), except that it always schedules the work item at CoreDispatcherPriority priority. When you schedule a work item by calling RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler) from a worker thread, the work item is processed only when there are no event messages pending in the queue. This allows your app to perform tasks such as spell check or other discrete processing while the system is idle. If the IdleDispatchedHandler delegate returned by the callback has the IsDispatcherIdle property set to false, the work item immediately exits background processing until the event queue is empty again.

    However, while your app is processing a background task, it can continue processing as long as there are no event messages pending in the CoreDispatcher event message queue. If your app receives an event message in the queue, then it must break out of the background processing. To determine when your app must exit background processing, access the IsDispatcherIdle property on the IdleDispatchedHandlerArgs object returned by the IdleDispatchedHandler callback you provided to RunIdleAsync(Windows.UI.Core.IdleDispatchedHandler). If there is a message, exit background processing and set the priority to CoreDispatcherPriority. Otherwise, if the callback continues to run without checking the dispatcher status, it could lead to input starvation.

  • ShouldYield()
    ShouldYield()
    ShouldYield()
    ShouldYield()

    Queries whether the caller should yield if there are items in the task queue of higher priority than the current task.

    public bool ShouldYield()public bool ShouldYield()Public Function ShouldYield() As bool

    Returns

    • bool
      bool
      bool

      true if the current work item should yield to higher priority work; false if it should not.

  • ShouldYield(Windows.UI.Core.CoreDispatcherPriority)
    ShouldYield(Windows.UI.Core.CoreDispatcherPriority)
    ShouldYield(Windows.UI.Core.CoreDispatcherPriority)
    ShouldYield(Windows.UI.Core.CoreDispatcherPriority)

    Queries whether the caller should yield if there are items in the task queue of the specified priority or higher.

    public bool ShouldYield(Windows.UI.Core.CoreDispatcherPriority priority)public bool ShouldYield(Windows.UI.Core.CoreDispatcherPriority priority)Public Function ShouldYield(priority As Windows.UI.Core.CoreDispatcherPriority) As bool

    Parameters

    Returns

    • bool
      bool
      bool

      true if the current work item should yield to higher priority work; false if it should not.

  • StopProcessEvents()
    StopProcessEvents()
    StopProcessEvents()
    StopProcessEvents()

    Stops the dispatcher from processing any queued events.

    public void StopProcessEvents()public void StopProcessEvents()Public Function StopProcessEvents() As void
  • TryRunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)
    TryRunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)
    TryRunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)
    TryRunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler)

    Attempts to schedule the provided callback on the UI thread from a worker thread, and returns the results asynchronously.

    public IAsyncOperation<bool> TryRunAsync(Windows.UI.Core.CoreDispatcherPriority priority,Windows.UI.Core.DispatchedHandler agileCallback)public IAsyncOperation<bool> TryRunAsync(Windows.UI.Core.CoreDispatcherPriority priority,Windows.UI.Core.DispatchedHandler agileCallback)Public Function TryRunAsync(priority As Windows.UI.Core.CoreDispatcherPriority,agileCallback As Windows.UI.Core.DispatchedHandler) As IAsyncOperation( Of bool )

    Parameters

    Returns

    • The asynchronous operation.

  • TryRunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)
    TryRunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)
    TryRunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)
    TryRunIdleAsync(Windows.UI.Core.IdleDispatchedHandler)

    Attempts to schedule a callback on the UI thread from a worker thread at idle priority, and returns the results asynchronously.

    public IAsyncOperation<bool> TryRunIdleAsync(Windows.UI.Core.IdleDispatchedHandler agileCallback)public IAsyncOperation<bool> TryRunIdleAsync(Windows.UI.Core.IdleDispatchedHandler agileCallback)Public Function TryRunIdleAsync(agileCallback As Windows.UI.Core.IdleDispatchedHandler) As IAsyncOperation( Of bool )

    Parameters

    Returns

    • The asynchronous operation.

Events

  • AcceleratorKeyActivated
    AcceleratorKeyActivated
    AcceleratorKeyActivated
    AcceleratorKeyActivated

    Fired when an accelerator key is activated (pressed or held down).

    public event TypedEventHandler AcceleratorKeyActivatedpublic event TypedEventHandler AcceleratorKeyActivatedPublic Event AcceleratorKeyActivated

    Remarks

    ** behavior**

    XAML processes CTRL+TAB or CTRL+SHIFT+TAB key presses for tab navigation, and apps do not get a chance to handle them from the AcceleratorKeyActivated event. Starting in Windows 8.1, we will allow the tab navigation processing with CTRL+TAB or ALT+TAB or SHIFT+TAB.

    If you handled the AcceleratorKeyActivated event in Windows 8 to do special processing, the event will get fired for Tab keys when invoked with CTRL, ALT, or SHIFT modifiers in Windows 8.1. Verify tab navigation with CTRL+TAB or ALT+TAB or SHIFT+TAB keys.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Core.dll