BRIGHAM YOUNG UNIVERSITY

  Humanities Technology and Research Support Center

Computers & the Humanities 210

Object Properties

Objectives

By the end of this reading you should know the following:

1. Know the proper format for referring to a property in a Revolution scripting statement.
2. Know how to use the set command to set a property of an object in the scripting language.
3. Understand the difference between the name of an object and the short name of an object.
4. Know how the properties the textFont, the textStyle, and theTextSize correspond to settings in the Text Formatting panel of the Property Inspector and the Text menu.
5. Know what the location property of an object refers to (i.e., how is it measured?)
6. Understand that every property that can be set in the Property Inspector can also be set in scripting.

Properties and Scripting

As we discussed before, every Revolution object has properties, or characteristics that determine its appearance and function: its name, location, style, attributes, text characteristics, etc. These are established when the object is created and mostly set by choices made from the properties palette. The Revolution scripting language has a full range of commands to examine and manipulate these properties within a handler. In other words, it is possible with any given object to view and change the characteristics of objects through the use of transcript commands within a handler

References to a property in Transcript have the general form:

the [PROPERTY] of [OBJECT]

where

both the and of are required keywords
[PROPERTY] is the name of the property in question.
[OBJECT] is a reference to a button, field, or other Revolution object.

Common Properties

As has been noted before, there are a number of properties which are common to all types of objects. Most properties can be accessed easily within a handler wherever the value of that property is appropriate. The most common methods are by either an if, a put, or a get statement:

if the [PROPERTY] of [OBJECT] is [PROPVALUE]
put the [PROPERTY] of [OBJECT] into [CONTAINER]
get the [PROPERTY] of [OBJECT]

where

[PROPERTY] is the name of the property in question.
[OBJECT] is a reference to a button, field or other Revolution object.
[PROPVALUE] is the value of the property in question (including booleans).
[CONTAINER] is a reference to any container.

You usually set properties, of course, by using the properties palette. However, you may use the set command within a handler to change directly a particular property of an object to a particular value:

set the [PROPERTY] of [OBJECT] to [PROPVALUE]

where

[PROPERTY] is the name of the property in question.
[OBJECT] is a reference to a button, field or other Revolution object.
[PROPVALUE] is the value of the property being adjusted (including booleans).

The power of this capability is that you can access the properties of objects within scripts, i.e., their values are available for reference and use. You can then script handlers to perform certain functions based upon the values of the various properties, including setting that property to a new value. This implies, then, that through the judicious use of handlers for various messages, you can alter the appearance and function of various objects.

Here are a few of the properties common to all objects which may be accessed and manipulated:

• Name: The name of an object is what appears in the Name field in the property inspector for that object. Specifying just the name gets the object's local identity: the kind of object as well as the actual name. Use short name to get just the name by itself. With long name you get the object's complete "genealogy".
  For instance, here is what you would get if you entered the following in the message box for a field named "myfield":
  

  put the name of field "myfield"
    --> field "myfield"
    
  put the short name of field "myfield"
    --> myfield
    
  put the long name of field "myfield"
    --> field "myfield" of card "mycard" of stack "mystack"
    

• Label: The label of any object is the string of characters that have been input to serve as a label to the object. This is particularly useful with buttons.
• ID, Number, Layer: Each object has these three properties assigned to it dependent upon when it was created. All three properties can be accessed. Not surprisingly, a set command cannot change the ID of the object (the ID cannot be changed by any method). Revolution won't let you set the number of the object either. But it does allow setting the layer, which changes the number property if there is another object of that type on the card.
• Visible: The visible property tells whether the object is showing or hidden. Hence, the value of the property is either true or false. If you were to use the hide statement with an object, it would make the visible property of that object have the value of false, and show would then change the value of the visible property to true.
• ToolTip: Here you can determine what tool tip (if any) is to be shown the user.
• blendLevel: This is an integer value between 0 and 100. Setting the blendLevel of an object alters its translucency, making it transparent to one degree or another (0 is completely opaque and 100 is completely transparent), allowing pixels behind it to show through.

Field text Properties

All of the font-related attributes of a field are properties that can be both read and set:

• textSize: the point size of the character font being used
• textHeight: the height of the lines
• textFont: the font, of course
• textStyle: the font style of the characters, such as bold, italic, underline, etc.
• textAlign: the alignment of lines—left, center or right. Note that this property can only be set for an entire field, not for individual lines of text within a field.

The font attributes of other control objects work in the same manner. In early versions of Revolution this was the only way. You couldn't specify font attributes for buttons with menus or the Text Properties dialog box like we have done. You had to use set commands:

• textFont: the font of the button name or label
• textSize: the point size of the name or label in the chosen font
• textStyle: the font style of the name or label
• textAlign: the alignment of the name or label within the button

Color Properties

All the color-related attributes of an object are properties that can be both read and set:

• backgroundColor: the fill color of the object
• borderColor: the color of the plain (non-3D) border of an object
• foregroundColor: the text color or line color of an object. You can also use the synonym the textColor.
• shadowColor: the color of the drop shadow (if the object has one)

For any of these properties, a standard color name may be used ("red", "blue", "aquamarine", "mistyRose", etc.), or the RGB values ("255,0,128"), or the HTML-style color indicator ("#A366FF").

Size and Position Properties

The Revolution coordinate system uses pixels as the unit of measurement and the upper-left corner of the card as the point of reference. Usually two numbers are provided, separated by commas. The first has reference to X (meaning the number of pixels from the left edge of the card), and the second has reference to Y (meaning meaning the number of pixels down from the top of the card).

• location (loc): The location of an object is specified as the X,Y coordinates of the center of the object in reference to the upper left-hand corner. You change the location of an object by setting its location property in an x,y format.

Other Position and Dimension Properties: There are several more properties pertaining to the position and dimensions of objects:

• left, right, top, bottom: the side properties change the position without changing the shape of the object
• width and height: change shape without changing location.
• rectangle (rect): gives all four dimensions (left, top, right, bottom) and can be used to change size, shape, and position at will.

There is no validity checking. You can set right less than left and top greater than bottom and sort of turn the object inside out!

This chart shows all of the different location and dimension properties and how they relate to each other.

Button Properties

There are two properties unique to buttons that are closely related:

• Hilite: The hilite property tells if the button is hilited or not, i.e., how the button appears. When set true the button appears hilited (inversed). When set to false the button looks normal. The hilite property is not the same as the autoHilite.
• AutoHilite: This property determines how the button behaves when clicked. When set true the button automatically inverses on the down click and returns to normal on the up click. When set false there is no visible change when the button is clicked.

All button styles work in this manner except checkBox and radioButton. These two styles hilite on one full click and restore on another full click. With autoHilite you get the default behavior, which is usually adequate. However, using the hilite property you can control hiliting explicitly in the script, or have certain events take place based upon the hilite of a certain button.

Other button properties that can also be retrieved and set include:

• opaque: determines if the button is transparent or not
• icon: The icon property is unique to buttons and can be set by specifying the number of the desired icon. Setting the icon of a button to zero removes any icon setting. Note that all of the icon states of a button can be set in this way, using the hiliteIcon, the disabledIcon, the hoverIcon, etc.
• showName: set to either true or false, this determines if the name/label of the button is displayed
• disabled: set to either true or false, this determines if the button is clickable or not. Using the enable and disable commands set this propety to true or false respectively.

Field Properties

A number of properties unique to fields can also be retrieved and set. The possible values for these properties are either true or false:

• vScrollbar,hscrollbar: determines if the field has appropriate scrollbars
• showLines: determines if the field appears as lined paper
• opaque: determines if the field is transparent or not
• disabled: determines if the field can execute its script or not (and it "appears" disabled, indicated by the color of the text) You cannot enter text into an unlocked, disabled field.
• lockText: determines if the text in the field can be altered or not by the user
• dontWrap: determines if the text in the field wraps automatically or not

Later in the course we will talk more about the properties of the text within containers (fields and variables).

Graphics Properties

Graphics in Revolution have their own properties. They are very similar to those of fields and buttons, such as font attributes:

• style: the style of a graphic can be retrieved and/or changed (with obvious limitations: "oval," "regular," "polygon," "line," etc.
• opaque: determines whether the graphic is transparent or not
• showBorder: shows or hides a rectangular border around the graphic.
• lineSize: is set to a number that adjusts the thickness of the line defining the graphic.

Image Properties

All of the properties which are common to objects are accessible and have the ability to be manipulated with image objects. There are some useful unique properties, however:

• fileName: If you have referenced an image's data rather than importing it into your stack, then the fileName property contains the path to that image. Changing this to a legitimate path will change the data the image displays.
• angle: This is an integer value between 0 and 360. Setting the angle of an image rotates it counter clockwise.

Further Exploration

There are dozens of other properties, both shared and unique to the different object types, that will not covered in this course. These may be discovered either by reading the documentation or by using the property inspector. Upon examining the property inspector for any object, hovering the mouse over the various properties will give you the actual name of the property by which it must be referenced. Using that one may obtain the value of that property for that particular object and thereby determine how that property may be altered. Experimentation is welcome here (and even encouraged), though you may get some unexpected results.