===== The Element ===== ==== Definition and Usage ==== The [[area|]] element allows for defining a content anchor (a subset of information units of a [[media|]] element's content) that may be used in relationships with other objects in an NCL application. Content anchors may represent: * spatial portions of images: through the //coords// attribute; * temporal portions of continuous media content (audio, video, etc.): through the //begin// and //end// attributes, or based on the number of audio samples or video frames, through the //first// and //last// attributes, which indicate the initial and final sample/frame; * temporal and spatial portions of videos: through the //coords//, //begin//, and //end// attributes; or through the //coords//, //first//, and //last// attributes; * textual segments: through the //beginText//, //beginPosition//, //endText//, and //endPosition// attributes, that define the beginning and end strings, and their occurrence in the text respectively; * a string that is used by the media player to identify a content region (for example, a function or method in an imperative media object, an interface in a declarative media object, like an HTML anchor, a port in a media object with an NCL application as a content, etc.): through the //label// attribute; * a clip in the content of a declarative hypermedia object: using the //clip // attribute. Every [[media|]], [[context|]], [[body|]], and [[switch|]] element has a content anchor with a region representing the whole content of the node defined by default. This anchor is called "whole content anchor". Except for media objects with imperative code content (for example, those whose MIME type is "application/x-ncl-NCLua"), every time an NCL component is referred without specifying one of its anchors, the whole content anchor is assumed. ==== Syntax ==== ^ Element ^ Attributes ^ Content ^ Parent ^ | [[area|]] | __//id//__, //coords//, //begin//, //end//, //beginText//, //endText//, //beginPosition//, //endPosition//, //first//, //last//, //label//, //clip// | -- | [[media|]] | ==== Attributes ==== ^ Name ^ Value ^ Description ^ | //id// | It may receive any string value that begins with a letter or an underscore and that only contains letters, digits, <".">, and <"_">. | The //id// attribute uniquely identifies the element within a document. | | //coords// |

A list of values of the form "left-x, top-y, right-x, bottom-y" where each value is either:

  1. a real number in the range [0,100] ending with the character <"%"> (e.g. "30%"), or
  2. a positive integer specifying the value in pixels. For pixel values, the "px" unit qualifier may be omitted.
|

The //coords// attribute specifies the position of a rectangular area on the screen.

Coordinates are relative to the top, left corner of the object content.

The values are separated by commas.

The order of values is "left-x", "top-y", "right-x", and "bottom-y".

When the "left-x" and "right-x" are expressed as a percentage, the value is relative to the width property of the media object.

When the "top-y" and "bottom-y" are expressed as a percentage, the value is relative to the height property of the media object.

| | //begin// |

Except for the [[media|]] element of the "application/x-ncl-time" type, the //begin// attribute shall be specified according with one of the following syntax:

  1. <"Hours:Minutes:Seconds.Fraction">, where "Hours" is an integer in the [0,23] interval, "Minutes" is an integer in the [0,59] interval, "Seconds" is an integer in the 0,59 interval, and "Fraction" is a positive integer,
  2. Seconds<"s">, where "Seconds" is a positive real number.

For the [[media|]] element of the "application/x-ncl-time" type, the //begin// attribute shall be specified according with the following syntax: <"Year:Month:Day:Hours:Minutes:Seconds.Fraction">, according to the country time zone. The NCL user agent is responsible for translating the value for the country time zone to the one corresponding to the UTC.

If the //end// attribute is defined, but without an explicit definition for the //begin// attribute, the start of the whole media content presentation shall be considered as the anchor beginning.

In the case of a media element of the "application/x-ncl-time" type, the //begin// attribute must always be defined and it assumes an absolute UTC value.

| The //begin// attribute specifies the beginning of the temporal anchor. | | //end// | Same as for //begin//. | The //end// attribute specifies the end of the temporal anchor. | | //beginText// |

String.

If the beginning of the content anchor region is not defined, the beginning of the text content is assumed.

| The //beginText// and //beginPosition// attributes specifies the beginning of the text anchor. The //beginText// defines a string in the text. | | //endText// | String. | The //endText// and //endPosition// attributes specifies the end of the text anchor. The //endText// defines a string in the text. | | //beginPosition// | Positive integer. The default value is 1. | The //beginText// and //beginPosition// attributes specifies the beginning of the text anchor. The //beginPosition// defines the occurrence of the string in the text. | | //endPosition// | Positive integer. The default value is the position of the last character in string. | The //endText// and the //endPosition// attributes specifies the end of the text anchor. The //endPosition// defines the occurrence of the string in the text. | | //first// |

The //first// attribute shall be specified according with one of the following syntax:

  1. Samples<"s">, where Samples is a positive integer,
  2. Frames<"f">, where Frames is a positive integer, or
  3. NPT<"npt"> where NPT is the Normal Play Time value.

If the //last// attribute is defined, but without an explicit definition for the //first// attribute, the start of the whole media content presentation shall be considered as the anchor beginning.

| -- | | //last// |

The //last// attribute shall be specified according with one of the following syntax:

  1. Samples<"s">, where Samples is a positive integer,
  2. Frames<"f">, where Frames is a positive integer, or
  3. NPT<"npt"> where NPT is the Normal Play Time value.

If the //first// attribute is defined, but the //last// attribute is not specified, the end of the whole media content presentation shall be assumed as the anchor ending.

| -- | | //label// | String. | The //label// attribute identifies a content region, for example, a function in an imperative media object, or an interface in a declarative media object, like an HTML anchor, or a port in a media object with an NCL application as content, etc. | | //clip// |

String.

The value depends on the declarative hypermedia object type. For NCL media objects, the clip value is a triple <"(chainId,beginOffset,endOffset)"> that is used by the NCL media player to identify an NCL application [[port|]] through which a temporal chain begins, and the beginning and the end time in this temporal chain.

For [[media|]] elements with NCL code content the following defaults are defined:

  1. "chainId" is the whole content anchor of the [[body|]] element,
  2. "beginOffset" is "0s", and
  3. "endOffset" is the end time of the temporal chain.
| The //clip// identifies a stream clip in the content of a declarative hypermedia object |