12. Attributes

Attribute related commands

element attlist element ?attribute?
	returns a description of the attribute or list of all attributes that have been defined for element if attribute has been omitted.
attribute delete handle attribute ?attribute...?
	deletes all specified attributes for element handle.
attribute hide element attribute ?boolean?
	Prevents an attribute from being shown in an element tag or returns the status of the attributes hidden flag if boolean is omitted.
atribute value handle ?name? ?new value?
	returns or sets attribute values for element handle. Returns a list of attribute-value apirs if no attribute name is supplied. If attribute name is supplied, returns the attribute value if new value is omitted or sets the attribute value to new value. Multiple pairs of attribute names and new values may be supplied.
attribute delete handle name ?name...?
	Deletes the attributes name from the element identified by handle.
id defined ?name?
	returns a handle for the element where the id name has been defined. If name has been omitted, a list of all defined ids is returned.
id referenced ?name?
	returns a list of element handles where the id name has been referenced. If name has been omitted, a list of all referenced ids is returned.

The element attlist command can retrieve a list of all attributes that have been defined for an element or the specification for an individual attribute of an element.

To retrieve a list of all attributes that have been defined for an element, only the element name is passed to the element attlist command.

	.s element attlist IMG
$\Rightarrow$	SRC ALT ALIGN ISMAP SDAPREF

If the name of an attribute is passed after the element name, the dtd attlist command returns the attribute definition of this attribute.

	.s element attlist IMG SRC
$\Rightarrow$	cdata required {} {}

	.s element attlist IMG SDAPREF
$\Rightarrow$	cdata fixed {<Fig><?SDATrans Img:#AttList>#AttVal(Alt)</Fig>} {}

The result of this form of the element attlist command is a list with four elements. These elements are:

• The declared value of the attribute.
• The default value type of the attribute.
• The default value of the attribute (or an empty string if no default value has been declared).
• The list of allowed values for this attribute ( or an empty string if the attribute has not been restricted to a list of predefined values).

The declared value element of the list can be one of the values listed below:

• cdata

  The attribute value is interpreted as character data.

• entity

  The attribute value is the name of a general entity. The entity must be known to the sgml widget when the attribute value is set.

• entities

  The attribute value is a list of general entity names. The attribute value is returned as a Tcl list. When specifying a new value, a well-formed Tcl list must be supplied that contains general entity names.

• id

  The attribute value is an id that identifies the element where the attribute value occurs. When the attribute value is set, the sgml value verifies that the same id has not yet been used for another element.

• idref

  The attribute value is the name of an id that has been assigned to an sgml element.

• idrefs

  The attribute value is a list of id references. The value is returned by the sgml widget as a Tcl list.

• name

  The attribute value is a single name that aheres to the restrictions for names set forth in the SGML standard.

• names

  The attribute value is a list of names that ahere to the syntax for names. The value is returned by the sgml widget as a Tcl list.

• nmtoken

  The attribute value is a single name token that aheres to the restrictions for names set forth in the SGML standard.

• nmtokens

  The attribute value is a list of name tokens that ahere to the syntax for names. The value is returned by the sgml widget as a Tcl list.

• number
• numbers
• nutoken
• nutokens
• notation
• nametokengroup

The default value type element of the list can be one of the values listed below:

• required
• current
• implied
• conref
• defaulted
• fixed

The default value is a string that represents the default value that has been specified for this attribute. If no default value has been specified, this element is empty.

12.1 Accessing the attribute list

The list of attribute values for an element can be accessed by the attribute value widget command. In its simplest formt, this command takes only one parameter, an element handle, and returns a list consisting of all attributes and attribute values for this element.

	set ref [ .s element at insert ]
$\Rightarrow$	E8561c80
	.s attribute value $ref
$\Rightarrow$	{ID REF17}

If the value of a specific attribute is required, the name of this attribute can be passed to the attribute value command after the element handle:

	set ref [ .s element at insert ]
$\Rightarrow$	E8561c80
	.s attribute value $ref ID
$\Rightarrow$	REF17

If the attribute has not been specified for the element, the command returns an empty string. It is an error to request the value of an attribute that has not been declared for the element in the DTD:

	set ref [ .s element at insert ]
$\Rightarrow$	E8561c80
	.s attribute value $ref BLA
$\oslash$	"Attribute "BLA" not declared for element "REF"

In its third form, the attribute value command can be used to set one or more attribute values. When used in this way, attribute names and attribute values are provided in pairs after the element handle:

	set ref [ .s element at insert ]
$\Rightarrow$	E8561c80
	.s attribute value $ref ID ref18 NAME myref

To clear an attribute value (and to remove the attribute from the attribute list of the element), an empty string must be used at the attribute value:

	set ref [ .s element at insert ]
$\Rightarrow$	E8561c80
	.s attribute value $ref ID ""
	.s attribute value $ref
$\Rightarrow$	{}

When the attribute values are changed, the sgml widget re-computes the display of the element tags and refreshes the window.

12.2 Specifying which attributes are shown

It is possible to configure which attributes will be shown in the start tag of elements and which will be hidden. The atrribute hide command can be used to prevent some attributes from being shown in the element tags:

[.s attribute hide H1 SDAFORM 1]

The first argument for the atrribute hide command is the name of an element, the second argument is the name of the attribute to be hidden or shown. The third argument is a boolean value that specifies if the attribute is to be hidden (true) or shown (false).

When the third argument is omitted, the attribute hide command returns a boolean value that reflects the status of the attribute. The returned value is 1 if the attribute is hidden or 0 if it is shown in the start tag of the element.

Note that is is not possible to pass an element handle at the first parameter to the attribute hide command: The command affects all elements of the specified element type.

This command has no effect when the display of attribute values has been disabled for the whole sgml widget with the -showattributes configuration option. See chapter XXX for details.

12.3 Attributes with list values

Attribute that have a declared value of ENTITIES, IDREFS, NAMES, NMTOKENS, NUMBERS, or NUTOKENS are treated as having lists as values. The sgml widget returns the values of these attributes as Tcl lists:

	set ref [ .s element at insert ]
$\Rightarrow$	E8561c80
	.s attribute value $ref
$\Rightarrow$	{IDLIST {REF17 REF18}}

Any values for list-like attributes that are set with the attribute value command should be proper Tcl lists. It is possibly the safest strategy to convert the intended attribute values for such attributes into proper Tcl lists with the list command:

	set newval [list REF19 REF20]
$\Rightarrow$	{REF10 REF20}
	.s attribute value $ref IDLIST $newval

12.4 Attributes with ID and IDREF values

The sgml widget does not (yet) enforce special rules on attribute values other than IDs. Attributes with a declared value of ID are checked across all elements in the document instance and multiple assignments of the same attribute value to other attributes with a declared value of ID is prevented.

The sgml widget does not verify the an attribute value of type IDREF (or a member of an IDREFS list) is defined as ID by some other element in the document. Currently, applications using the sgml widget have to perform these checks ``by hand'', i.e. by writing the appropriate Tcl scripts. Notifications (described in chapter ) may simplify this task.

The list of defined IDs can be retrieved with the id defined command:

	.s id defined
$\Rightarrow$	{ID1 ID2 ID3 ID4}

There is no way to manipulate the contents of the ID list directly; new IDs are entered when they are assigned as attribute values and removed when the attribute value changes or the element is deleted.

It is possible to determine where an ID has been defined by using the id defined command. This command takes an ID as parameter and returns an element handle for the element that defines the ID:

	.s id defined ID2
$\Rightarrow$	E8561c80

The id defined command returns an empty string for undefined IDs.

The id referenced widget command can be used to retrieve a list of all IDs that have been referenced in the document. The general form of the id referenced command is:

pathname id referenced ?id?

If the optional argument id is not specified, the result is a Tcl list consisting of the names of all IDs that have been referenced in the document. If the id argument is specified, it must be the name of an id that has been defined in the document. In this case, the sgml widget returns a list of element handles in which the specified ID is referenced as the value of an idref or idrefs attribute.

To detect references to any unspecified IDs in the document, the following Tcl procedure could be used:

This procedure returns a list of IDs that were referenced in a document without being used as the value of an ID attribute.