ATTR

Adds the fields for an attribute to the current chapter or group.

Syntax

ATTR strValue [ color:ColorSpec ] [ lines:intValue ] [ dialog:Dialog ]
    [ ctrltype:ControlType ] [ checked-value: anyValue unchecked-value:anyValue ]
    [ push-button ] [ no-auto ] [ no-param ]
    [ write-protected ] [ hidden:boolValue ] [ enabled:boolValue ]
    [ mandatory:boolValue ] [ width:realValue ] .

Dialog : time | date | datetime | distribution | actor | subprocess | resource | color | transcond .

ControlType : check | radio | dropdown .

Parameters

• <main-parameter> (strValue) - The name of the attribute to display.
• color (ColorSpec, optional) - Sets the color to draw the attribute name in. The default is "black".
• lines (intValue, optional) - Controls the size of the attribute field where appropriate. The default depends on the attribute's type.
• dialog (Dialog, optional) - Controls the fields to show in the Notebook for the attribute and what kind of dialog window to open when the Dialog icon is selected. By default these are based on the attribute's type.
• ctrltype (ControlType, optional) - Allows to change the fields displayed for an attribute. The default depends on the attribute's type and configuration.
• checked-value (anyValue, optional) - Specifies the value for a selected checkbox. Necessary when ctrltype:check is used.
• unchecked-value (anyValue, optional) - Specifies the value for a deselected checkbox. Necessary when ctrltype:check is used.
• push-button (modifier, optional) - Changes a program call attribute to be displayed as a button. By default this is not specified.
• no-auto (modifier, optional) - Removes the "<automatically>" value from a program call attribute. By default this is not specified.
• no-param (modifier, optional) - Hides the parameter field of a program call attribute. By default this is not specified.
• write-protected (modifier, optional) - When specified it prevents modifying the attribute via the Notebook. By default this is not specified.
• hidden (boolValue, optional) - When the value evaluates to true, then the attribute will not be visible in the Notebook. Otherwise the attribute is presented as normal. The default is 0 (false).
• enabled (boolValue, optional) - When the value evaluates to true, then the attribute can be edited by the user in the Notebook. Otherwise the attribute name and fields are greyed out and can not be interacted with. The default is 1 (true).
• mandatory (boolValue, optional) - When the value evaluates to true, then the attribute is marked as being mandatory, meaning it requires a value different from the attribute's default value. The default is 0 (false).
• width (realValue, optional) - Determines the column width of the attribute within a table. Only used when specifying the AttrRep for a record type attribute.

Details

The ATTR command is used to add an attribute at the place where it occurs to the Notebook. The attribute is referenced by its name as a <main-parameter>.

The look of an attribute and the provided fields (text field, radio buttons etc.) depends primarily on the attribute type. It can further be controlled through the parameters like lines, dialog or ctrltype which are described in the following sub-sections. The Notebook page has some details on the different representation options available while the following sections focus more on the how.

The same attribute can appear in multiple chapters (using multiple ATTR commands) and each one can also have different configurations of parameters. The underlying attribute and its value is always the same in such a case.

Color

The parameter color can be used as part of the command to set the displayed color of the attributes's name. The color is specified through a ColorSpec, which has to evaluate to a strValue or an intValue (see LEO Colors for details).

Lines

The size of the attribute field can be controlled through the lines parameter. The parameter indicates how many lines should be visible at once in the Notebook for the attribute.

It is available for attributes that contain longer, broken up or several values, like multi-line texts, record type attributes or Inter-model reference attributes.

Dialog

The dialog parameter allows to change what kind of pop-up window should open when selecting the Dialog icon next to the attribute. By default a dialog fitting the attribute type is selected. The possible values are:

• time for a dialog with fields for specifying a duration.
• date for a dialog focusing on entering a date.
• datetime for a dialog where a date and time can be entered.
• distribution for a dialog for the assignment of a distribution function.
• actor for a dialog for the assignment of performers.
• subprocess for a dialog for the selection of a subprocess.
• resource for a dialog for the assignment of resources.
• color for a color picker dialog.
• transcond for a dialog to specify a condition using variables.

The fields used to represent the attribute can be influenced by the dialog setting. For example when using dialog:color then multiple fields will be shown in the Notebook to modify various aspects of a color, like separate fields for red, green and blue values and a preview of the color.

Control Type

For some types of attributes different types of user interface controls are available. To switch from the default control type the ctrltype parameter is used. It can have a value of check, radio or dropdown.

When the value check is used, then the attribute will be displayed as a checkbox. This can be used for attributes with simple types, like numbers, enumerations etc. Using check requires to also specify the values for when the attribute is checked and unchecked through the parameters checked-value and unchecked-value.

For enumeration type attributes also the options radio and dropdown are available. by default all values are listed as radio buttons for up to four possible values (ctrltype:radio). Otherwise, only the current value is represented in a dropdown list (ctrltype:dropdown).

Push-button, no-auto and no-param

A program call attribute attribute can be presented in the Notebook in several different ways (see representation of program call attributes). These are controlled through the modifiers push-button, no-auto and no-param.

When the modifier push-button is specified, then only one available item (program) is provided as a button instead of the typical dropdown list.

By default an item (program) "<automatically>" is provided as an executable option in the Notebook, which would start the appropriate application with respect to the entered parameter. This option can be suppressed by using the modifier no-auto.

If the no-param modifier is defined then the parameter (program argument) field will not be available in the Notebook.

Write-protected

When the write-protected modifier is provided, then the attribute is displayed, but may not be changed through the Notebook.

Hidden

An attribute can be hidden from a Notebook depending on the value of other attributes of the object. This can be used for example when the sub-type of an object is specified through an attribute to hide attributes that are not relevant for the selected sub-type. Whether an attribute should be hidden or not is specified as an expression of the hidden parameter.

Enabled

A Notebook's input fields can be "enabled" or "disabled" in dependency of attribute values of the related object. A typical application is to enable certain fields if an enumeration attribute is set to a certain value. For such a case the AVAL command is used to read attribute values into variables. These variables can then be used to compute the "enabled" state. This state is specified as an expression at the enabled parameter.

Mandatory

Attributes can be marked as mandatory. Mandatory means that attribute values shall be different from the default value. For example, if the default value of a string attribute is empty, mandatory means that a non-empty text has to be specified for that attribute. Otherwise it is considered to be "missing". By default, attributes are optional (not mandatory). An attribute can be marked as mandatory by specifying the mandatory modifier.

In a Notebook, each mandatory attribute is marked with an asterisk (*) behind its name. When the attribute value equals the default attribute value, the color of the text and the attribute's name is red, otherwise it is the default color (usually black).

If a certain attribute is contained more than once in an Notebook, then specifying mandatory for at least one ATTR element makes it mandatory everywhere for the related class. Record type and Attribute Profile reference attributes cannot be marked as mandatory.

In case that at least one mandatory attribute is missing for the current object a predefined variable _mandatoryerr has the value 1 (true), otherwise 0 (false). This variable is available in the GraphRep and can be used to display a warning sign with the object. An example for a GraphRep which draws a warning sign when mandatory attributes are missing:

GRAPHREP
SHADOW off
PEN w:0.1cm
FILL color:lightgray
RECTANGLE w:2cm h:2cm
IF (_mandatoryerr) {
  EXECUTE internal:warn01 x:0cm y:1cm w:1cm h:1cm
}

Avoid mixing mandatory with write-protected and enabled, especially when using the _mandatoryerr variable. The check for a mandatory attribute does not consider whether the attribute can change the value or not.

Width

The parameter width is specified for an ATTR command in a record type attribute AttrRep and should have a floating-point number, like ATTR "Value" width:1.0. It determines the column width of the attribute within a table. The column width is relatively calculated on the available space in the table. When extending and reducing the table, the column widths will be adapted accordingly. The width parameter should be provided for all contained attributes, as otherwise the width of all columns can be larger than the available space in the table.

See Also

• AVAL
• CHAPTER
• GROUP and ENDGROUP
• NOTEBOOK
• SET

Examples

A Notebook with three chapters, each with several attributes. The "Description" attribute is used in the first two chapters, but showing a different amount of lines in each of them. The third chapter name is drawn using a green color.

NOTEBOOK

CHAPTER "General"
  ATTR "Name"
  ATTR "Description" lines:4

CHAPTER "Details"
  ATTR "Description" lines:7
  ATTR "Comment" lines:7
  ATTR "Max. loop count" mandatory:(1)

CHAPTER "Presentation" color:"green"
  ATTR "Position"
  ATTR "Size"
  ATTR "Font color" dialog:color

A Notebook where the attribute "Cooperative mode" is only enabled when the value of the "Cooperative" attribute is "yes".

NOTEBOOK

AVAL sCooperative:"Cooperative"

CHAPTER "General"
  ATTR "Name"
  ATTR "Cooperative" ctrltype:check checked-value:"yes" unchecked-value:"no"
  ATTR "Cooperation mode" ctrltype:radio enabled:(sCooperative = "yes")

A Notebook with a mandatory "Description" attribute and a "Comment" attribute which can be hidden or disabled depending on the value of the "Comment state" attribute (an enumeration that has a value of "normal", "hidden" or "disabled").

NOTEBOOK

AVAL sCommentState:"Comment state"

CHAPTER "General"
ATTR "Name"
ATTR "Description" mandatory:(1)
ATTR "Comment state" ctrltype:dropdown
ATTR "Comment" hidden:(sCommentState = "hidden") enabled:(sCommentState != "disabled")

Versions and Changes

Available since ADOxx 1.3