Nevron Open Vision Documentation
Input Elements

 
Input Elements Overview

Input elements are represented by the NInputElement abstract class that derives from the NVisualElement class. It serves as base class for elements that can receive and process user input. Input elements themselves are still not participating in the document measure and layout systems, but have the ability to be a part of a display tree (inherited from NVisualElement). 

Input elements implement core features for higher level user input such as the ability to be enabled/disabled, gain focus and mouse capture, process UI events and have cursor and tooltip. More information about core user input is provided by the User Input topic. Following is some information about these features:

Enabled and Disabled Elements

An input element is considered enabled if its Enabled property value is true. Otherwise the input element is considered disabled. Disabled elements have limited participation in the UI events processing including:

Keyboard Focus, Mouse Capture and Drag-Drop Target

For an input element to be able to gain keyboard focus, the CanFocus() method must return true. The Focus() method attempts to set the keyboard focus on the input element and returns true, if after the call the input element has the keyboard focus. You can use the IsFocused property to determine whether the input element is currently focused or not. To prevent an input element from gaining focus, set its AllowFocus property to false.

For an input element to be able to gain mouse capture, the CanCaptureMouse() method must return true. The CaptureMouse() method attempts to capture the mouse to input element, and returns true, if after the call the input element has the mouse capture. You can use the IsMouseCaptured property to determine whether the input element has currently captured the mouse. You can release the mouse capture by calling the ReleaseMouseCapture() method. To prevent an input element from capturing the mouse, set its AllowMouseCapture property to false.

All input elements are by default considered to be drop targets, which means that if enabled they can process the UI Action Events associated with drop targets, which are the NDragDrop.DragOverEvent and NDragDrop.DragDropEvent. To exclude an input target from the drop target events processing, you can set its AllowDrop property to false.

UI Events Processing

All UI events, have the ability to sink and bubble (see Events for more info). The UI events processing starts by the respective dispatcher (NMouse, NKeyboard and NDragDrop), which raises the respective event for a certain input target. The input target for which an Action UI Event is raised is determined by each dispatcher as follows:

For more information about core user input, take a look at the User Input topic.

UI Event dispatchers are not interested in whether an input target is enabled nor take any actions in events handling. Their responsibility is to just to keep track/update the target for which to raise the respective action UI event. Thus, it is up to the DOM to implement higher level abstractions, such as enabled/disabled elements, how to react to handled events etc., which is exactly what NInputElement does - a higher abstraction layer for working with UI events and the core User Input.

NInputElements provides "out of the box" handling methods only for the at-target/bubbling phase of both Target Change UI Events and Action UI Events. An UI event can be intercepted by an NInputElement in three ways, and in the following sequence:

  1. By the NInteractor that belongs to the input element (accessible from the Interactor property). An interactor is a pluggable UI events processor, that allows you dynamically add/remove and/or enable/disable interactivity features for a specific input element, via associated tools. See Interactors for more info.
  2. By the NCommander that belongs to the input element, if it is a NKeyboard.KeyDownEvent event (accessible from the Commander property). A commander is a pluggable command actions dispatcher, that can execute the command actions it contains in response to either command source events or keyboard shortcuts. See Commanding for more info.
  3. By the respective Default Event Handler. Default event handlers are protected overridable methods of each input element (OnMouseMove, OnMouseDown, OnKeyDown etc.).

By default, the NInputElement does not have an interactor or commander, meaning that by default UI events are handled by the default event handler methods. Most widgets that come along with NOV are simple widgets that have predefined interactivity, which is achieved by overriding the default event handlers. That is why you can override the interactivity of most widgets by creating custom interactors (and the associated tools).

Input elements do nothing when disabled and an Action UI Event is received by them for processing. Input elements however always receive Target Change UI Events. For example: if you have overriden the OnMouseDown and OnMouseIn default event handlers in a custom input element and this element is disabled, your OnMouseDown override will never get invoked, while your OnMouseIn override will be invoked when the mouse enters the element subtree.

When overriding a default event handler for an Action UI Event, you must check the Cancel flag, because you may not be the last override of this method (i.e. your override method can be called by another override). Following is the pattern that needs to be used:

Handling Action UI Events Pattern
Copy Code
protected override void OnMouseDown(NMouseButtonEventArgs arg1)
{
    // if not handled -> do something 
    if (!arg1.Cancel)
    {
        ...
        // do something
        ...
        // mark event as handled if you do not want other targets in the event route to take other actions
        arg1.Cancel = true;
    }
    // call base
    base.OnMouseDown(arg1);
}

The same rule also applies for the handled Action UI Events. For example: if you have overriden the OnMouseDown and OnMouseIn default event handlers in a custom input element and this element has an interactor with tool that handles (marks as canceled) both the OnMouseDown and the OnMouseIn event, your OnMouseDown will not get called, while your OnMouseIn override will be called. This is because the NInputElement "respects" the Cancel flag only for Action UI Events.

Cursors and ToolTips

NInputElement adds higher level support for cursors and tooltips, by proving the Cursor and ToolTip properties, that let you specify a default cursor and tooltip for the input element.  

NInputElement requests the cursor assigned to the Cursor property, after the NMouse.MoveEvent, NMouse.DownEvent and NMouse.UpEvent have been processed by the input element. This gives you the flexibility to modify the Cursor property as part of your event handlers, or simply request a different cursor by calling the NMouse.RequestCursor method as part of your handling, if you need to have a dynamic cursor. Note that the cursor specified by the Cursor property is only requested when the element is enabled (see Cursors for more info).

Similarly to the cursor, the NInputElement requests the tooltip assigned to the ToolTip property, after the NMouse.MoveEvent has been processed by the input element. This gives you the flexibility to modify the ToolTip property as part of your event handlers, or simply request a different tooltip by calling the NMouse.RequestToolTip method as part of your handling, if you need to have a dynamic tooltip. Note that the tooltip specified by the ToolTip property is only requested when the element is enabled or the ShowOnDisabled property of the tooltip is set to true (see ToolTips for more info).

The following example applies a cursor and tooltip to a button widget (widgets indirectly derive from NInputElement):

 

Set Cursor and ToolTip to an Input Element
Copy Code
NButton button = new NButton("Button with cursor and tooltip");
// assign a tooltip that shows the specified string (tooltip content however can be any widget)
button.ToolTip = new NToolTip("Click me");
// assign the predefined Hand cursor - NOV has several predefined cursors, but also provides the ability to define custom ones.
button.Cursor = new NCursor(ENPredefinedCursor.Hand);
See Also
Send Feedback