15 Application development

15.1 Element focus and navigation

15.1.1 The focusable property

In many cases, such as text editing, the user is required to place focus on a particular element, ensuring that input events, such as keyboard input, are sent to that element.

The focusable property determines if an element can get keyboard focus (i.e. receive keyboard events) and be a target for field-to-field navigation actions. (Note: in some environments, field-to-field navigation can be accomplished with the tab key.) The value "true" means that the element is keyboard-aware and should be treated as any other UI component that can get focus. The value "false" means that it should not. The value "auto" is equivalent to "false", except that it acts like "true" for the following cases:

• the a element
• the text and flowDiv elements with editable set to "true"

All renderable elements can be focusable, including both container elements and graphics elements,. It is possible for a focusable container element to have focusable descendants.

Custom (i.e., non-SVG) elements can also be focusable, including custom elements with sXBL bindings. (See XML Binding Language for SVG.)

15.1.2 Navigation

System-dependent input facilities (e.g., the tab key on most desktop computers) should be supported to allow navigation between elements that can obtain focus (ie. elements for which the value of the focusable property evaluates to "true").

In the author wishes to change the specified field navigation order (and, wherever not specified, the default tab order), they must catch the input event related to the navigation and then cancel the event.

Navigation order is determined using the nav-index, nav-left, nav-right, nav-up, and nav-down properties from the CSS 3 Basic User Interface Module. In most cases, the value 'auto' will cause the user agent to use document order for navigation order. This property only applies to focusable elements.

The SVG language supports a flattened notion of field navigation between focusable elements where it is possible to define field navigation between any two focusable elements defined within a given SVG document without regard to document hierarchy. For example:

<rect id="r1" focusable="true".../>
<g> id="g1" focusable="true">
  <circle id="c1" focusable="true".../>
</g>

In the above example, it is possible to specify field-to-field navigation such that it is possible to navigate directly from any of the three elements. Thus, assuming a desktop computer which uses the tab key for field navigation, then it is possible to specify focus navigation order such that the tab key takes the user from r1 to c1 to g1.

SVG's flattened notion of field navigation extends to referenced content and shadow trees as follows:

• Focusable elements within the content referenced by a use element participate in field navigation operations using the flattened focus model. (Note: If a referenced symbol contains a focusable element, and that symbol is referenced by two use elements, then the document will have two separate focusable fields, not just one.)
• If an image element references an SVG document, then all of the focusable fields defined within the referenced SVG document participate in field navigation operations using the flattened focus model.
• Focusable elements within shadow trees created by sXBL bindings (see XML Binding Language for SVG) are included in the set of focusable fields that participate in field navigation operations. For more on focusable elements within shadow trees, refer to the Focus and navigation section on sXBL

The one difference with referenced content and shadow trees has to do with the handling of nav-index. For all of the above cases, nav-index includes a hierarchical aspect as defined in the sXBL specification (see sXBL 'nav-index' rules).

15.1.3 Obtaining focus

When the user agent gives an element focus it receives a {"http://www.w3.org/2001/xml-events", "DOMFocusIn"} event.

The SVGElement and SVGElementInstance interfaces have a focus() method that, when called, requests that the User Agent give focus to the particular element. Calling focus() on an element that is not focusable causes focus to go to the nearest focusable ancestor element. If there is no focusable ancestor element, then focus goes to the document. If focus() is called on an SVGElementInstance that corresponds to a given use element, then that SVGElementInstance can get focus only if its corresponding element is focusable; otherwise, focus goes to the nearest focusable ancestor element (perhaps spanning from the shadow instance tree into the main document) or, if there are no focusable ancestors, to the document.

The SVGDocument interface have next() and previous() methods which move the focus onto the respectively next or previous focusable element.

User agents which support pointer devices such as a mouse must allow users to put focus onto focusable elements. For example, it should be possible to click on a focusable element in order to give focus.

Empty text fields in SVG theoretically take up no space, but they have a point or zero-width line segment that represents the location of the empty text field. User agents should allow users with pointer devices to put focus into empty text fields by initiating a select action (e.g., a mouse click) at the location of the empty text field.

15.2 Tooltips

The SVG 1.1 language does not specify a method for the declarative display of tooltips on SVG content. While it suggests that the content of the title element could be displayed as a tooltip, it does not provide any control for the content developer. This meant that developers resorted to implementing their own tooltip functionality using scripting.

SVG 1.2 adds declarative tooltip support through the tooltip property. This allows for the display of textual tooltips to be declaratively controlled for each element in the SVG document. User agents should use the platform tooltip system if there is one available. On platforms without native support for tooltips, user agents can implement their own tooltip system. This means that the appearance, position and behavior of the tooltip is implementation or platform specific.

However, in the visual environment, the user agent must attempt to display the entire tooltip in a readable manner, avoiding clipping by the edge of the device or canvas. If possible the tooltip should be implemented as a temporary graphic that is superimposed on the top of the SVG canvas at the location of the pointer if one exists. Also, if possible, the content of the tooltips should be made available to accessibility implementations on the device.

15.2.1 The hint element

The hint element is another level of metadata for an element. The contents of the hint element are intended to be displayed by a tooltip. It differs from the title and desc elements in that a hint may give instructions to the user, as opposed to describe the element that it belongs to.

  <define name="hint">
    <element name="hint">
      <ref name="attlist.hint"/>
      <ref name="SVG.hint.content"/>
    </element>
  </define>
  <define name="attlist.hint" combine="interleave">
    <ref name="SVG.Core.attrib"/>
  </define>
  <define name="SVG.hint.content">
    <choice>
      <ref name="SVG.XLinkEmbed.attrib"/>
      <text/>
    </choice>
  </define>

Below is an example of the hint element.

<svg xmlns="http://www.w3.org/2000/svg" version="1.2">

  <circle cx="50" cy="50" r="25" fill="red" tooltip="enable">
    <title>The target area</title>
    <hint>Click here to start the animation</hint>
    <animate .... />
  </circle>

</svg>

15.2.2 The tooltip property

The tooltip property specifies whether or not tooltips should be displayed for this element.

If the tooltip property is set to "enable" then the content of the tooltip is the text content of the hint child of an element. For elements that do not have a hint child, the tooltip content is the content of its parent's tooltip. If the tooltip property is set to "disable" then the content of the tooltip is empty. The value of the tooltip for a root svg element without a hint child is empty. In the case of an empty value, the tooltip will not be displayed.

Tooltips and the CSS hover property both track the mouseover and mouseout events. Tooltips may require the pointer to be stationary over the target for a short period of time. Tooltips and hover represent additive effects. The hover processing should occur first followed by tooltip processing. That is, tooltip processing is placed after hover processing and before hyperlink processing. Tooltips respond to pointer events in the same manner as hover, thus do not activate on elements with either the display or pointer-events properties set to "none".