`<ux-window>`

A UX window specification is a collection of metadata for a window or viewport in which a user assistance topic or web page can be displayed. The window or viewport can be referenced by the <resourceid> element that is associated with a topic or <topicref> element.

Usage information

The <ux-window> element can be used in any <topicmeta> element in a map. If more than one <ux-window> element in a map has the same @name attribute, the first window specification in document order with that @name attribute is used.

Attributes

The following attributes are available on this element: ID and conref attributes, metadata attributes, @class, and the attributes defined below.

@features

Provides a list of other window features, such as size, position, or scroll bars. Each feature name and value can not contain any blank space, and each feature name and value is separated by a comma or other delimiter character.

@full-screen

Indicates whether the window is initially displayed in a maximized state. Allowable values are yes, no, and -dita-use-conref-target. The default value is no.

@height

Specifies the height of the window. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.

@left

Specifies the left position of the target help window, whether relative to the calling window or to the entire display. The value of this attribute is a real number optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels).

@name (REQUIRED)

Specifies the value used to refer to this window definition.

@on-top

Indicates whether the initial z-order of the target help window is on top of all windows on the desktop. Allowable values are: yes, no, and -dita-use-conref-target. The default value is no.

@relative

Indicates whether the window dimensions are relative to the calling window or the entire target display. The default value is no. The following are allowable values:

no: The window dimensions specified on this element are absolute positions; they are not relative to the calling window.
yes: The window dimensions specified on this element are relative to the calling window.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

@top

Specifies the top position of the target help window, whether relative to the calling window or to the entire display. The value of this attribute is a real number optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels).

@width

Specifies the width of the window. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.

Examples

This section shows how the <ux-window> and <resourceid> elements work together to define and use window definitions.

Figure 1. Using <ux-window> with <resourceid>

The following code sample shows how a window with a name of "help" is defined in the map. The window name is later referenced by the @ux-windowref attribute on the <resourceid> element.

<map>
 <title>Widget Help</title>
 <topicmeta>
  <ux-window id="fg23" name="help" top="10" left="20" height="400" width="500" 
     features="status=yes,toolbar=no,menubar=no,location=no" relative="yes"
     full-screen="no" />
 </topicmeta>
 <topicref href="file_ops.dita" type="concept">
   <topicref href="saving.dita" type="task" />
   <topicref href="deleting.dita" type="task" />
   <topicref href="editing.dita" type="task">
     <topicmeta>  
       <resourceid id="ab43" appname="ua" 
          appid="5432" ux-context-string="idh_fileedit" ux-windowref="help" />
     </topicmeta>
   </topicref>
</topicref>
</map>

Figure 2. Using multiple <ux-window> definitions

The following code sample shows how multiple window specifications can be defined for alternate presentations, such as desktop computers and tablets:

<map>
 <title>Puggles Help</title>
 <topicmeta>
 <ux-window id="p76" name="ux-tablet" top="1cm" left="1cm" height="4cm" width="3cm" 
    features="status=no,toolbar=no,menubar=no,location=no" relative="no"
    full-screen="no" />
 <ux-window id="p80" name="ux-desktop" top="5cm" left="10cm" height="16cm" width="12cm" 
    features="status=yes,toolbar=no,menubar=no,location=yes" relative="no"
    full-screen="no" />
 </topicmeta>
 <topicref href="c_puggles_intro.dita" type="concept">
  <!-- ... -->
 </topicref>
</map>