Chapter Contents

Previous

Next

Attributes

Attributes are the properties that specify the information associated with a component, such as its name, description, and color. Attributes determine how a component will look and behave. For example, the Push Button Control has an attribute named label that specifies the text displayed on the button. You can create two instances of the Push Button Control on your frame and have one display "OK" and the other display "Cancel," simply by specifying a different value for the label attribute of each instance.

You can define attributes with attribute statements in CLASS blocks:

scope data-type attribute-name/(attribute-options);

Attribute names can be up to 256 characters long.

Like methods, attributes can have public, private, or protected scope. The scope works the same for attributes as it does for methods. See Defining Method Scope for more information.

Examples of attribute options include the attribute description, whether the attribute is editable or linkable, custom access methods that are to be executed when the attribute is queried or set, and whether the attribute sends events.

If an attribute is editable, you can use the Editor option to specify the name of the FRAME, SCL, or PROGRAM entry that will be used to edit the attribute's value. This entry is displayed and executed by the Properties window when the ellipsis button (...) is selected.

To specify an attribute's category, use the Category attribute option. The category is used for grouping similar types of options in the Class Editor or for displaying related attributes in the Properties window. You can create your own category names. Components that are supplied by SAS may belong to predefined categories.

Creating Attributes Automatically

With the Autocreate option, you can control whether storage for list attributes and class attributes is automatically created when you instantiate a class. By default, Autocreate='Y', which means that SCL automatically uses the _NEW_ operator to instantiate class attributes and calls the MAKELIST function to create the list attributes.

Note:   Even when Autocreate='Y', storage is not created for generic objects because the specific class is unknown.  

If you specify Autocreate='N', then storage is not automatically created, and it is your responsibility to create (and later destroy) any list attributes or class attributes after the class is instantiated.

import sashelp.fsp.collection.class;
class myAttr;
  public list myList / (autocreate='N');
  public list listTwo;   /* created automatically */
  public collection c1;  /* created automatically */
  public collection c2 / (autocreate='N');
endclass;

Specifying Where an Attribute Value Can Be Changed

An attribute's scope and the value of its Editable option determines which methods can change an attribute's value.

• If the scope is public and Editable='Y', then the attribute can be accessed (both queried and set) from any class method as well as from a frame SCL program.

• If the scope is public and Editable='N', then the attribute can only be queried from any class method or frame SCL program. However, only the class or subclasses of the class can modify the attribute value.

• If the scope is protected and Editable='N', then the class and its subclasses can query the attribute value, but only the class itself can set or change the value. A frame SCL program cannot set or query the value.

• If the scope is private and Editable='N', then the attribute value can be queried only from methods in the class on which it is defined, but it cannot be set by the class. Subclasses cannot access these attributes, nor can a frame SCL program. This combination of settings creates a private, pre-initialized, read-only constant.

Setting Initial Values and the List of Valid Values

Unless you specify otherwise, all numeric attributes are initialized to missing values, and all character attributes are initialized to blank strings. You can use the initialValue attribute option to explicitly initialize an attribute. For example:

class myAttr;
   public num n1 / (initialvalue = 3);
   public list list2 / (initialvalue = {1, 2, 'abc', 'def'};
endclass;

Explicitly initializing attribute values improves the performance of your program.

You can use the ValidValues attribute option to specify a list of values that the attribute can have. This list is used as part of the validation process that occurs when the value is set programmatically by using either dot notation or the _setAttributeValue method.

If you specify the ValidValues option and the InitialValue option, the value that you specify with the InitialValue option must be included in the values that you specify with the ValidValues option.

In the list of valid values, you can use blanks to separate values, or, if the values themselves contain blanks, use a comma or a slash (/) as the separator. For example:

class business_graph_c;
  public char statistic
         / (ValidValues='Frequency/Mean/Cumulative Percent',
            InitialValue='Mean');
  public char highlightEnabled
         / (ValidValues='Yes No',
            InitialValue='Yes');
 endclass;

You can also specify an SCL or SLIST entry to validate values. For more information on how to use an SCL entry to perform validation, refer to SAS Guide to Applications Development.

Associating Custom Access Methods with Attributes

A custom access method (CAM) is a method that is executed automatically when an attribute's value is queried or set using dot notation. When you query the value of an attribute, SCL calls the _getAttributeValue method. When you set the value of an attribute, SCL calls the _setAttributeValue method. These methods are inherited from the Object class.

You can use the getCAM and setCAM attribute options to specify additional methods that you want _getAttributeValue or _setAttributeValue to execute. For example:

class CAM;
  public char A / (getCAM='M1');
  public num B / (setCAM='M2');
  protected M1: method c:char;
    put 'In M1';
  endmethod;
  protected M2: method b:num;
    put 'In M2';
  endmethod;
endclass;

CAMs always have a single signature and cannot be overloaded. The CAM signature contains a single argument that is the same type as its associated attribute. A CAM always returns a numeric value.

You should never call a CAM directly; instead, use the _getAttributeValue or _setAttributeValue methods to call it automatically. To prevent CAMs from being called directly, it is recommended that you define them as protected methods.

Attribute Values and Dot Notation

When you use dot notation to change or query an attribute value, SCL translates the statement to a _setAttributeValue method call (to change the value) or to a _getAttributeValue method call (to query the value). These methods are inherited from the Object class and provide the basis for much of the behavior of attributes.

For example, the _setAttributeValue method

• verifies that the attribute exists

• verifies that the type of the attribute matches the type of the value that is being set

• validates the value against the ValidValues metadata item if that item exists for the attribute

• invokes the custom set method (setCAM) if it exists

  Note:    If Editable='No', the custom set method is not called (even if it was defined for the attribute).  
  

• stores the value in the attribute

• sends the "attributeName Changed" event if the attribute has a SendEvent='Yes' metadata item

• sends the "contents Updated" event if the attribute is specified in the object's contentsUpdatedAttributes attribute. This event notifies components in a model/view relationship that a key attribute has been changed.

See Implicit Behaviors of Dot Notation for additional information.

The following figures detail the flow of control for the _setAttributeValue and _getAttributeValue methods.

Flow of Control for _setAttributeValue

Flow of Control for _getAttributeValue

Linking Attributes

Attribute linking enables one component to automatically upate the value of one of its attributes when the value of another component attribute is changed. You can link attributes between components or within the same component. Only public attributes are linkable.

To implement attribute linking, you need to identify attributes as either source attributes or target attributes. You can identify source and target attributes either in the Properties window or with SCL. To identify an attribute as a source attribute with SCL, specify SendEvent='Y' in the attribute's option list. To identity an attribute as a target attribute, specify Linkable='Y' in the attribute's option list.

You can then link the attributes (specify the LinkTo option) in the Properties window.

When SendEvent='Y', SAS/AF software registers an event on the component. For example, the textColor attribute has an associated event named "textColor Changed". You can then register an event handler to trap the event and to conditionally execute code when the value of the attribute changes.

If you change the SendEvent value from 'Y' to 'N', and if Linkable='Y', then you must send the "attributeName Changed" event programmatically with the attribute's setCAM in order for attributes that are linked to this attribute to receive notification that the value has changed. If the linked attributes do not receive this event, attribute linking will not work correctly. In the previous example, the setCAM for the textColor attribute would use the _sendEvent method to send the "textColor Changed" event.

Refer to SAS Guide to Applications Development for more information on attribute linking.

Attribute Metadata

SCL uses a set of attribute metadata to maintain and manipulate attributes. This metadata exists as a list that is stored with the class. You can query a class (or an attribute within a class) with specific methods to view attribute metadata. To list the metadata for a specific attribute, execute code similar to the following:

init:
   DCL num rc;
   DCL list metadata;
   DCL object obj;
 
   obj=loadclass('class-name');

   rc=obj._getAttribute('attribute-name',metadata);   
   call putlist(metadata,'',3);  
return;

Chapter Contents

Previous

Next

Top of Page

Copyright © 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.