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 change 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 stack, card, 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 (e.g. field or variable.)

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 (with get or put) and manipulated (with set):

• 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".
  Try it! Click the enter button next to each of the statements below to see what you would get if you entered that statement in the message box for a field named "myfield":
  

  put the name of field "myfield"	enter	Result:
  put the short name of field "myfield"	enter	Result:
  put the long name of field "myfield"	enter	Result:
  			reset all

• Label: This property pertains to stacks, buttons, groups, and graphics. It is the text that the user sees on the object, as contrasted to the name, which the user does not see if the label property is set. This is particularly useful with buttons and stacks. A synonym to this property is title.
• 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 most objects (With the exception of image objects the ID property 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: A toolTip is the explanatory text that appears when you hover your mouse pointer over an object. If this property is empty, no toolTip will appear.
• opaque: determines whether the background of a card or object is is transparent or opaque to the objects beneath it.
  Try it! Click the enter button next to each of the statements below to see what happens when you set the opaque property of the field to true or false:
  

  set the opaque of field "flowerlist" to false set the opaque of field "flowerlist" to true

  enter     enter

• blendLevel: This is an integer value between 0 and 100. Setting the blendLevel of an object alters its transparency, or the degree to which objects underneath it show through. 0 is completely opaque and 100 is completely transparent.

Text Properties

In addition to changing them in the property inspector, you can both read and set all of the text and font-related attributes of objects using scripting. (In fact, in early versions of Revolution, the only way to change the text settings of buttons was via the set command.)

• textFont: the font, of course
• textSize: the point size of the character font being used
• 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.

There is a pair of text-related properties that apply only to fields:

• textHeight: the amount of space between lines of text, independent of the textSize property.
• fixedLineHeight: if true, the space between all lines of text in a field is the same, equal to the textHeight property; if false, the textHeight property is ignored, and each line may vary in height according to the textSize of the text in the line.

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!

The chart at right 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:

• 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.