Office of Digital Humanities

Digital Humanities & Technology 210

Object Properties

Objectives

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

1. Know the proper syntax for referring to a property in a LiveCode 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 a script.

Properties and Scripting

Earlier we learned that every LiveCode object has properties,or characteristics that determine its appearance and function—its name, location, style, appearance, text characteristics, etc. These property settings are established when the object is created and mostly set by choices made from the properties palette. The LiveCode scripting language has a full range of commands to examine and manipulate these properties within a handler. In other words, you can change any property of any object by using LiveCode commands in a message handler.

References to a property in Transcript take the 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 LiveCode object.

For example:

  the visible of image "smiley"
  the lockText of field "mytext"
  the backgroundColor of graphic "outline"

Referring to Properties in Scripts

You can insert references to most properties within LiveCode statements wherever the value of that property is appropriate. Some of the most common places to reference the value of a property are in if-then, put, or get statements:

if the property of object is propvalue then...
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 LiveCode object.
propvalue is the value of the property in question (including booleans).
container is a reference to any container (e.g. field or variable.)

Changing Properties in Scripts

Up until now you have usually set property values by using the property inspector. However, you can also use the set command within a handler to directly change the value of a property of an object to another 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 LiveCode object.
propvalue is the value of the property being adjusted (including booleans).

The ability to check and modify object properties gives you the power to do a lot of interesting things in scripts. You can perform certain functions based upon the values of the various properties. You can also change the appearance and behavior of objects in your message handlers. For example, you could use a mouseEnter handler to change the background color of a button, field, or graphic, creating a “rollover” effect.

Examples of setting properties in a message handler:

on mouseEnter
  set the backgroundColor of me to red
  set the foregroundColor of me to yellow
end mouseEnter

on mouseLeave
  set the backgroundColor of me to empty
  set the foregroundColor of me to empty
  -- setting a property to empty forces the object 
  --  to use the property setting from its parent object
end mouseLeave

Common Properties

As we discussed earlier, there are a number of properties that are common to all types of objects. Here are a few of the common properties that may be accessed (with get or put) and manipulated (with set):

• the name: This property is a little unusual in that it has several variations that you can specify depending how much detail you want. In general, the name of an object is what appears in the name field in the property inspector for that object. However, if you use the name variant of the property, you get not just the name of the object, but also the type of object; e.g., button "clickme" or field "myField".


• the short name: Use this variant of the property if you want only the name string by itself.


• the long name: This variant of the property contains the object’s complete “genealogy”; that is, all of the needed information to specify the exact object name, card and stack that identifies the object.

  The demo shows the difference between the name, the short name, and the long name of field "myfield".

  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

  If you want to change the name of an object in a script, just use the name form of the property:

    set the name of field "myField" to "yourField"
  

• the 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.
• the id, the number, the layer: Each object has these three properties assigned to it, dependent upon the order in which it was created. All three properties can be accessed, but not all of them can be changed. Not surprisingly, a set command cannot change the ID of most objects (image objects being the notable exception). LiveCode 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.
• the visible: The visible property tells whether the object is showing or hidden. Since there are only two possible states, the value of this property is either true or false. When you use the hide command to hide an object, it actually sets the visible property of that object to false, while show sets the value of the visible property to true.
• the 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.


• the opaque: determines whether the background of a card or object 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

• the 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.
• the showBorder: set to either true or false. Shows or hides the border, for any object that has a border.

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 LiveCode, the only way to change the text settings of buttons was via the set command.)

li>the textFont: the name of the font being used;
• the textSize: the point size of the character font being used;
• the textStyle: the font style of the characters, such as bold, italic, underline, etc.;
• the textAlign: the alignment of lines—left, center or right. Note that as of LiveCode version 5.5 this property can be set for individual lines of text within a field, as well as for an entire field.

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

• the textHeight: the amount of space between lines of text, independent of the textSize property. By default this property is set to 4/3 times the textSize of the field.
• the 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:

• the backgroundColor: the fill color of the object. Synonym: the backColor
• the foregroundColor: the text color or line color of an object. You can also use the synonyms the textColor or the foreColor.
• the borderColor: the color of the plain (non-3D) border of an object
  

  Objects with a 3-D look (that is, objects for which the threeD property is set to true) use two color properties to determine their border color:

• the topColor: The color of the “raised edge” of the object’s border.
• the bottomColor: The color of the shadowed edge of a 3-D style object.

To set any of these properties, you may use a standard color name ("red", "blue", "aquamarine", "mistyRose", etc.), or RGBvalues (255,0,128), or a hexidecimal color definition ("#A366FF").

Size and Position Properties

LiveCode Size and Position Properties

The LiveCode coordinate system uses pixels as the unit of measurement and the upper-left corner of the card as the point of reference. A valid location coordinate consists of two whole numbers, separated by commas. The first number is the X-distance (meaning the number of pixels from the left edge of the card), and the second is the Y-distance (meaning meaning the number of pixels down from the top of the card).

• the 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 of the card. You change the location of an object by setting its location property in an x,y format. For example:

    set the loc of image "flower" to 240,160

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

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

Caution! There is no validity checking when you set location and dimension properties by script. So it is possible to set the right to less than the left and the top to greater than the bottom and sort of give the object dimensions of zero! This has the effect of making the object “disappear” because it has dimensions that are too small to see.

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

Button Properties

Here is a look at some of the properties of buttons, which of course can also be set by scripting.

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

• the hilite: The hilite property determines whether the button is hilited or not, i.e., how the button appears. When set to true the button appears hilited (darkened). When set to false the button looks normal. The hilite property is not the same as the autoHilite.
• the autoHilite: This property determines how the button behaves when clicked. When set to true the button automatically highlights on the down click and returns to normal onthe up click. When set to 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 set or used in scripting include:

• the icon: The icon property is unique to buttons and can be set by specifying the id property of the image you want to use as the icon. Setting the icon of a button to zero or empty 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.
• the showName: set to either true or false, this determines whether the name/label of the button is displayed.
• the enabled: set to either true or false, this determines whether the button is clickable or not. Using the enable and disable commands automatically set this property to true or false respectively.
• the disabled: set to either true or false, this determines whether the button is clickable or not. It is the logical inverse of the enabled property. Using the enable and disable commands automatically set this property to false or true respectively.

Field Properties

A number of properties unique to fields can also be retrieved and set.

• the vScrollbar, the hscrollbar: determines whether the field has vertical or horizontal scrollbars
• the showLines: determines whether light dotted lines appear under each line of text in the field, giving the field the appearance of lined paper;
• the lockText: determines whether the text in the field can be altered or not by the user;
• the dontWrap: determines whether the text in the field wraps automatically or not.
• tabStops: determines the tab stops for the entire field or designated lines of the field. Tab stops are defined in pixels from the left margin of the field.

Fields also have these properties in common with other object types:

• the opaque: determines whether the field is transparent or not;
• the disabled: determines whether the field can receive mouse messages or not (and it appears disabled, indicated by thecolor of the text.) You cannot enter text into an unlocked, disabled field

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

Graphics Properties

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

• the style: the style of a graphic can be retrieved and/or changed (with obvious limitations: "oval," "regular," "polygon," "line," etc.)
• the opaque: determines whether the graphic is transparent or not
• the lineSize: is set to a number that adjusts the thickness of the line defining the graphic.
• the angle: This is an integer value between 0 and 360. Increasing the angle of an image rotates it clockwise.

Each style of graphic may also have unique properties that pertain only to that style. For example, an oval-style graphic has arcAngle and startAngle properties that can be set to show “pie slice” segments of the oval. In the case of a graphic with a style of "regular" (for Regular Polygons) there is a property the polySides that allows you to specify how many sides the polygon has.

Image Properties

All of the properties which are common to all objects are accessible and changeable for image objects. There are some useful unique properties, however:

• the fileName: If you have referenced an image to an external file rather than importing it into your stack, then the fileName property contains the path to that image file. Changing this to a legitimate file path will change the data the image displays.
• the resizeQuality: This is an important property if you are using images that you need to resize. The available settings are “normal”, “good”, and “best”. “Best” produces the highest-quality scaling, but is slower than “normal” and “good”. The default value for a new image is “normal”, so if you intend to resize the image, set this property first.
• the angle: This is an integer value between 0 and 360. Increasing the angle of an image rotates it counter-clockwise, in contrast to the way this property works with graphics.

Checking the Value of Inherited Properties

As we learned in an earlier lesson, certain properties of objects can be inherited from parent objects. The properties that can be inherited are primarily color, pattern, and text properties. So, for example, the textFont of the stack will be inherited by the cards in the stack and all control objects in the stack, but only if the object itself has no setting for that property.

The effective keyword

If an inheritable property of an object is empty, you can’t simply check the property to find out what color or font settings the object displays. In cases like this, you can use the effective keyword to obtain the inherited setting of the property. The effective keyword searches the object’s parents, if necessary, to find out what setting is actually used.

For instance, suppose you have a field whose textFont property is empty. The textFont for the card is also empty, but the textFont for the stack is set to "Arial", so the field inherits the stack setting and uses the Arial font to display its text. In cases like this you can use the expression the effective textFont to find out which font the field is using:

  put the textFont of fld "myField" --> empty
  put the effective textFont of fld "myField" --> Arial

Take note that using the effective keyword does not pose any risk of reporting the wrong setting—if the object does have its own property setting the effective keyword reports the value of the control’s own property setting, not that of its parent.

Further Exploration

There are dozens of other properties, both shared and unique to the different object types, that will not be covered in this course.You can discover them either by reading the documentation or by examining the property inspector. When you open 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 can be referenced. By using the property name you can check the value of that property for that particular object and change it to a different setting. Experimentation is welcome here (and even encouraged), though in some cases you may get some unexpected results.