InputPane InputPane InputPane InputPane Class

Definition

Enables an app to receive notifications when the docked touch keyboard, or Soft Input Panel (SIP), is about to be displayed or hidden, and to determine which portion of the application's window is obscured by the input pane.

Note

The InputPane APIs provide accurate occlusion information for a docked panel only. For Windows 10 Creators Fall Update and newer, we reccomend using the following APIs to handle occlusion by docked, undocked, moveable, and transitory input panes such as Soft Input Panels (SIP), Input Method Editor (IME) candidate windows, floating toolbars, and so on.

public : sealed class InputPane : IInputPane, IInputPane2, IInputPaneControl
public sealed class InputPane : IInputPane, IInputPane2, IInputPaneControl
Public NotInheritable Class InputPane Implements IInputPane, IInputPane2, IInputPaneControl
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The input pane appears when the user performs an action that requires them to enter information, such as selecting a text entry field. By default, Windows handles the input pane events and repositions content so that users can see where they are typing. If you set CoreTextEditContext.InputPaneDisplayPolicy to Manual in your app, you are responsible for showing and hiding the input pane using TryShow and TryHide. Use this class to override the default behavior and customize the input pane.

In some cases, overlay UI such as an InputPane is not fully supported. This includes:

Call GetForCurrentView to get an InputPane object.

After you register to receive input pane notifications, the system calls your event delegate whenever the input pane is shown or hidden for the window that was visible when you called the GetForCurrentView method.

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).

Properties

OccludedRect OccludedRect OccludedRect OccludedRect

Gets the region of the app window obscured by the input pane.

public : Rect OccludedRect { get; }
public Rect OccludedRect { get; }
Public ReadOnly Property OccludedRect As Rect
var rect = inputPane.occludedRect;
Value
Rect Rect Rect Rect

The rectangle, in client coordinates, representing the region of the app window hidden behind the input pane. Specified in device-independent pixel (DIP).

A top value of "0" indicates that the app window is not obstructed by the input pane. The input pane might still be visible.

A height value of "0", and width value equal to the width of the input pane, indicates that the input pane is floating, but not obstructing the app window.

Remarks

Universal apps should use this property, rather than Visible.

Visible Visible Visible Visible

Gets or sets a value that indicates whether the input pane is shown.

Important

Valid for Xbox device family only.

For universal apps, the OccludedRect property indicates the region of the app window obstructed by the input pane.

public : Platform::Boolean Visible { get; set; }
public bool Visible { get; set; }
Public ReadWrite Property Visible As bool
var bool = inputPane.visible;
inputPane.visible = bool;
Value
Platform::Boolean bool bool bool

true if the input pane is shown; otherwise, false.

See Also

Methods

GetForCurrentView() GetForCurrentView() GetForCurrentView() GetForCurrentView()

Gets the InputPane object associated with the application window that is currently visible.

public : static InputPane GetForCurrentView()
public static InputPane GetForCurrentView()
Public Static Function GetForCurrentView() As InputPane
var inputPane = Windows.UI.ViewManagement.InputPane.getForCurrentView();
Returns

Remarks

This method is the only way to get an input pane object; you can't use the new operator to get a new input pane object.

TryHide() TryHide() TryHide() TryHide()

Tries to hide the InputPane, if it is visible.

public : Platform::Boolean TryHide()
public bool TryHide()
Public Function TryHide() As bool
var bool = inputPane.tryHide();
Returns
Platform::Boolean bool bool bool

true if the request to hide the InputPane was accepted; otherwise false.

If this method is called from an app that is not in foreground, the request is rejected and false is returned.

Remarks

If you set CoreTextEditContext.InputPaneDisplayPolicy to Manual in your app, you are responsible for showing and hiding the input pane using TryShow and TryHide.

TryShow() TryShow() TryShow() TryShow()

Tries to show the InputPane, if it is hidden.

This method is a "best effort" and guarantees only that the user has a way to enter text in the focused control. The touch keyboard, or Soft Input Panel (SIP), is shown only if a hardware keyboard is not available.

public : Platform::Boolean TryShow()
public bool TryShow()
Public Function TryShow() As bool
var bool = inputPane.tryShow();
Returns
Platform::Boolean bool bool bool

true if the request to show the InputPane was accepted; otherwise false.

If this method is called from an app that is not in foreground, the request is rejected and false is returned.

Remarks

If you set CoreTextEditContext.InputPaneDisplayPolicy to Manual in your app, you are responsible for showing and hiding the input pane using TryShow and TryHide.

Events

Hiding Hiding Hiding Hiding

Occurs when the input pane starts sliding out of view.

public : event TypedEventHandler Hiding<InputPane, InputPaneVisibilityEventArgs>
public event TypedEventHandler Hiding<InputPane, InputPaneVisibilityEventArgs>
Public Event TypedEventHandler Hiding( Of ( Of InputPane ), ( Of InputPaneVisibilityEventArgs ))
function onHiding(eventArgs){/* Your code */}


inputPane.addEventListener("hiding", onHiding);
inputPane.removeEventListener("hiding", onHiding);

Remarks

The system associates the input pane with the application window that was visible when you called the GetForCurrentView method. This implies that you must create a new input pane object and register for the Showing event each time you create a new window. You can use the Hiding event to undo changes you may have made to your app's layout during the Showing event.

When the system calls your event handler, the input pane has not started to slide out of view. After your event handler returns, the input pane starts to slide out of view. If your event handler doesn't respond quickly enough (within 200 milliseconds), the input pane starts to slide out of view without waiting for your event handler to return.

If you create a custom user experience for the input pane, make sure to set the EnsuredFocusedElementInView property on the event arguments to notify the app framework that you have handled the input pane event and it should not try to do so for you.

You should minimize the amount of work you do while the input pane is being hidden because multiple animations and content resizes may be happening simultaneously. The more work you do during this period affects the overall system performance, causing a poor user experience.

Showing Showing Showing Showing

Occurs when the input pane starts sliding into view.

public : event TypedEventHandler Showing<InputPane, InputPaneVisibilityEventArgs>
public event TypedEventHandler Showing<InputPane, InputPaneVisibilityEventArgs>
Public Event TypedEventHandler Showing( Of ( Of InputPane ), ( Of InputPaneVisibilityEventArgs ))
function onShowing(eventArgs){/* Your code */}


inputPane.addEventListener("showing", onShowing);
inputPane.removeEventListener("showing", onShowing);

Remarks

The system associates the input pane with the application window that was visible when you called the GetForCurrentView method. This implies that you must create a new input pane object and register for the Showing event each time you create a new window.

When the system calls your event handler, the input pane has not started to slide into view. After your event handler returns, the input pane starts to slide into view. If your event handler doesn't respond quickly enough (within 200 milliseconds), the input pane starts to slide into view without waiting for your event handler to return.

You can use the Showing event to create a custom user experience when the input pane is displayed. For example, in an instant messenger app, you might want to resize the chat window and input box to fit above the input pane so that the user never has to scroll to see new messages. If you do create a custom user experience, make sure to set the EnsuredFocusedElementInView property on the event arguments to notify the app framework that you have handled the input pane event and it should not try to do so for you.

You should minimize the amount of work you do while the input pane is being shown because multiple animations and content resizes may be happening simultaneously. The more work you do during this period affects the overall system performance, causing a poor user experience.

See Also