IXRUIElement (Compact 2013)

Article
04/19/2017

3/28/2014

This C++ class is the base class for most objects in XAML for Windows Embedded that are graphical and can process basic user input.

Syntax

class IXRUIElement : public IXRDependencyObject

Inheritance Hierarchy

IXRUIElement

Methods

Method	Description
IXRUIElement::AddGestureEventHandler	Attaches a delegate to the Gesture event for this UI element. When the UI element raises the Gesture event, this delegate is invoked.
IXRUIElement::AddGotFocusEventHandler	Attaches a delegate to the GotFocus event for this UI element. When the UI element raises the GotFocus event, this delegate is invoked.
IXRUIElement::AddKeyDownEventHandler	Attaches a delegate to the KeyDown event for this UI element. When the UI element raises the KeyDown event, this delegate is invoked.
IXRUIElement::AddKeyUpEventHandler	Attaches a delegate to the KeyUp event for this UI element. When the UI element raises the KeyUp event, this delegate is invoked.
IXRUIElement::AddLostFocusEventHandler	Attaches a delegate to the LostFocus event for this UI element. When the UI element raises the LostFocus event, this delegate is invoked.
IXRUIElement::AddLostMouseCaptureEventHandler	Attaches a delegate to the LostMouseCapture event for this UI element. When the element raises the LostMouseCapture event, this delegate is invoked.
IXRUIElement::AddMouseEnterEventHandler	Attaches a delegate to the MouseEnter event for this UI element. When the UI element raises the MouseEnter event, this delegate is invoked.
IXRUIElement::AddMouseLeaveEventHandler	Attaches a delegate to the MouseLeave event for this UI element. When the UI element raises the MouseLeave event, this delegate is invoked.
IXRUIElement::AddMouseLeftButtonDownEventHandler	Attaches a delegate to the MouseLeftButtonDown event for this UI element. When the UI element raises the MouseLeftButtonDown event, this delegate is invoked.
IXRUIElement::AddMouseLeftButtonUpEventHandler	Attaches a delegate to the MouseLeftButtonUp event for this UI element. When the UI element raises the MouseLeftButtonUp event, this delegate is invoked.
IXRUIElement::AddMouseMoveEventHandler	Attaches a delegate to the MouseMove event for this UI element. When the UI element raises the MouseMove event, this delegate is invoked.
IXRUIElement::AddMouseWheelEventHandler	Attaches a delegate to the MouseWheel event for this UI element. When the UI element raises the MouseWheel event, this delegate is invoked.
IXRUIElement::Arrange	Positions child elements on the graphical window and determines a size for IXRUIElement.
IXRUIElement::CaptureMouse	Enables the UI element to capture the mouse.
IXRUIElement::GetCacheMode	Retrieves a value that indicates whether this UI element will use bitmap caching and hardware-accelerated graphics when it is displayed at run time.
IXRUIElement::GetClip	Retrieves the geometry that defines the outline of a UI element.
IXRUIElement::GetDesiredSize	Retrieves the size of this UI element as computed during the measure pass of the layout process.
IXRUIElement::GetEffect	Retrieves the pixel shader effect to apply to the UI element.
IXRUIElement::GetIsHitTestVisible	Retrieves whether the contained area of this UI element can return true values for hit testing.
IXRUIElement::GetOpacity	Retrieves the degree of opacity of a UI element.
IXRUIElement::GetOpacityMask	Retrieves the brush that is used to alter the opacity of regions of this UI element.
IXRUIElement::GetProjection	Retrieves the three-dimensional (3-D) transformation that is applied when XAML for Windows Embedded displays this UI element.
IXRUIElement::GetRenderSize	Retrieves the final size of this UI element after it is displayed in the graphical window.
IXRUIElement::GetRenderTransform	Retrieves information about the transformation that affects where this UI element is displayed.
IXRUIElement::GetRenderTransformOrigin	Retrieves the origin point of any possible display transformation, in relation to the bounds of this UI element.
IXRUIElement::GetUseLayoutRounding	Retrieves a value that determines whether rendering for the object and its visual subtree should use rounding behavior that aligns rendering to whole pixels.
IXRUIElement::GetVisibility	Retrieves a value that indicates whether this UI element is visible.
IXRUIElement::HitTest	Returns the results of a hit test that specifies an x,y coordinate position on the screen.
IXRUIElement::InvalidateArrange	Invalidates the arrange state, or layout, for this UI element. After the invalidation, XAML for Windows Embedded asynchronously updates the element's layout.
IXRUIElement::InvalidateMeasure	Invalidates the measurement state, or layout, for this UI element.
IXRUIElement::Measure	Updates the original desired size of this UI element.
IXRUIElement::ReleaseMouseCapture	Removes mouse capture from this UI element, which typically means that no UI element holds mouse capture.
IXRUIElement::RemoveGestureEventHandler	Removes a delegate from the Gesture event for this UI element.
IXRUIElement::RemoveGotFocusEventHandler	Removes a delegate from the GotFocus event for this UI element.
IXRUIElement::RemoveKeyDownEventHandler	Removes a delegate from the KeyDown event for this UI element.
IXRUIElement::RemoveKeyUpEventHandler	Removes a delegate from the KeyUp event for this UI element.
IXRUIElement::RemoveLostFocusEventHandler	Removes a delegate from the LostFocus event for this UI element.
IXRUIElement::RemoveLostMouseCaptureEventHandler	Removes a delegate from the LostMouseCapture event for this UI element.
IXRUIElement::RemoveMouseEnterEventHandler	Removes a delegate from the MouseEnter event for this UI element.
IXRUIElement::RemoveMouseLeaveEventHandler	Removes a delegate from the MouseLeave event for this UI element.
IXRUIElement::RemoveMouseLeftButtonDownEventHandler	Removes a delegate from the MouseLeftButtonDown event for this UI element.
IXRUIElement::RemoveMouseLeftButtonUpEventHandler	Removes a delegate from the MouseLeftButtonUp event for this UI element.
IXRUIElement::RemoveMouseMoveEventHandler	Removes a delegate from the MouseMove event for this UI element.
IXRUIElement::RemoveMouseWheelEventHandler	Removes a delegate from the MouseWheel event for this UI element.
IXRUIElement::SetCacheMode	Sets a value to indicate that this UI element will use bitmap caching and hardware-accelerated graphics when it is displayed at run time.
IXRUIElement::SetClip	Sets the geometry used to define the outline of a UI element.
IXRUIElement::SetIsHitTestVisible	Determines whether the contained area of this UI element can return true values for hit testing.
IXRUIElement::SetOpacity	Determines the degree of opacity of a UI element.
IXRUIElement::SetOpacityMask	Determines the brush that is used to alter the opacity of regions of this UI element.
IXRUIElement::SetProjection	Sets the three-dimensional (3-D) transformation to apply when XAML for Windows Embedded displays this UI element.
IXRUIElement::SetRenderTransform	Sets information about the transformation that affects where this UI element is displayed.
IXRUIElement::SetRenderTransformOrigin	Determines the origin point of any possible display transformation, in relation to the bounds of this UI element.
IXRUIElement::SetUseLayoutRounding	Determines whether rendering for the object and its visual subtree should use rounding behavior that aligns rendering to whole pixels.
IXRUIElement::SetVisibility	Determines whether this UI element is visible. Elements that are not visible cannot be displayed on the screen.
IXRUIElement::TransformPointRelative	Transforms the specified source x,y coordinates into the target x,y coordinates by using this element's IXRTransform-derived object and its display-transformation origin point.
IXRUIElement::TransformToVisual	Retrieves a transform object that can be used to transform coordinates from the UI element to the specified object.
IXRUIElement::UpdateLayout	Assures that the positions of all child elements of this UI element are updated for layout.

Thread Safety

Members of this class are thread safe if you previously called IXRApplication::CreateHostFromXaml and supplied it with an XRWindowCreateParams structure that has AllowsMultipleThreadAccess set to true.

Remarks

This class provides a starting point for accessing and modifying element-layout characteristics. The derived class IXRFrameworkElement provides additional methods for managing element-layout characteristics.

This class defines much of the input behavior for UI elements, including the events for UI focus events and keyboard, mouse, and stylus input.

The events in XAML for Windows Embedded are routed events. A routed event is an event that is passed upward from a child object to each of its parent objects in the object tree. For routed events, the object that handles the event might not be the same object that initially raised it.

Routed events have a built-in event-handling notification system, so that unhandled input events that are routed from child objects in the visual tree are automatically passed to parent objects. This input behavior is useful for input-area grouping and control compositing.

To find out whether this element currently has UI focus, use the derived IXRControl class.

Z-order determines the visual layering of objects on the screen. You can set the z-order for this UI element to a value from 0 through 1,000,000. To do this, set its Canvas.ZIndex attached property by calling the inherited method IXRDependencyObject::SetAttachedProperty(const WCHAR*, const WCHAR*, int). To retrieve the Canvas.ZIndex attached property value, call IXRDependencyObject::GetAttachedProperty(const WCHAR*, const WCHAR*, int*).

To access an IXRUIElement object, first obtain a pointer to a visual host in the call to IXRApplication::ParseXaml, obtain the root element of the element tree by calling IXRVisualHost::GetRootElement, traverse through its visual-tree structure by calling IXRFrameworkElement::FindName, and then obtain a pointer to a named object in the visual tree.

You can also access an interface pointer to an IXRUIElement object from inside an event handler by calling IUnknown::QueryInterface on the object in pSender. Or, you can use a class derived from IXRUIElement to create a UI element yourself and insert it into a generated visual tree, instead of declaring it in the source XAML for your application.

When you create a class instance, use an IXRUIElementPtr smart pointer instead of a raw interface pointer. For more information, see XRPtr<Interface>.

For more information about how to create UI elements in the source XAML for your application, use the link to the Microsoft Silverlight 3 documentation in the class topic for each derived class.

Hit Testing

IXRUIElement contains various APIs that can affect hit testing. Hit testing is the process by which XAML for Windows Embedded takes the input stimulus (such as mouse clicks) from the application, and then determines which IXRUIElement object in the layout and visual tree to designate as the source of the input event.

IXRUIElement::GetVisibility and IXRUIElement::SetVisibility are methods that access Visibility state, which affects how all input is handled by this element. Elements that are not visible do not participate in hit testing and do not receive user-input events, even if the mouse is inside of where the element would appear if it were visible.

Finally, the GetBackground method, which is contained in various classes derived from IXRUIElement, can also influence hit-test behavior because a null background value makes the element invisible to hit testing.

.NET Framework Equivalent

System.Windows.UIElement

Requirements

Header	XamlRuntime.h
sysgen	SYSGEN_XAML_RUNTIME