UserGuide

Properties

From Xojo Documentation

A property is a value of a class or module. You can think of it as a variable that belongs to a class or module. Most of the built-in classes have properties. For example, the Date class has a property to get the Year.

For more about using properties with Modules, refer to the Modules topic. For more about properties when used with classes, refer to the Class Properties, Methods and Events topic.

There are two types of properties you can add: a standard property and a computed property.

Property

Properties can be added to project items, including classes (including Windows, Web Pages, iOS Views) and modules. There are several way to add a property:

  • Insert button on the main toolbar
  • Add button on the Code Editor toolbar
  • Insert ↠ Property from the menu
  • The contextual menu
  • Keyboard shortcut (Option-Command-P on macOS or Ctrl+Shift+P on Windows and Linux)
TeamName Property

To quickly create a property, you can enter both its name and type on one line in the Name field like this: PropertyName As DataType. When you leave the field, the type will be set in the Type field.

Any of these steps adds the property, displays a blank editor (where you can type notes) and displays the Inspector where you can set the values for the property. These are the values you can change:

  • Name
    The name of the property. Just like variables, properties are given names to describe them and the same naming rules apply. To create a property that is an array, add parenthesis after the name just as you would when creating an array variable.
  • Type
    The Type can be any valid data type, including classes.
  • Default
    The default value for the type. For example, for an Integer property you can specify 42 to have its default value be 42. You can only set default types for the intrinsic properties (Integer, Double, String, etc.) and not for object types.
  • Scope
    Scope indicates what parts of your code can call the method. Choices are Global, Public, Protected and Private.
    • Global properties can be used anywhere in your code with no restrictions. These are available only with Modules.
    • Public properties can be called from anywhere in your code with no restrictions. These are available only with Classes.
    • Protected properties have some restrictions, which vary depending on where the method is located (class or module).
    • Private properties can only be called by the module or class that contains the method.

The property signature (its name, and type) also appears at the top of the Editor for reference.

Properties are referenced by their name when used within the module or class that owns them. This is how you would reference a TeamName property in your code:

TeamName = "Flying Squirrels"

For usage outside of the class or module that owns them, they are often referenced differently (usually with the class or module name as a prefix). Refer to the Modules and Classes topics for specifics.

Computed Property

A computed property is a property that does not store its value but instead calculates it each time it is accessed. This means a computed property does not store an actual value. Instead if uses a standard property to store a value or contains code to calculate a value.

There are several ways to add a computed property:

  • Insert button on the main toolbar
  • Add button on the Code Editor toolbar
  • Insert ↠ Computed Property from the menu
  • The contextual menu

Like with a property, you have to specify the values for the computed property, which are:

  • Name
    The name of the property. Just like variables, properties are given names to describe them and the same naming rules apply.
  • Type
    The Type can be any valid data type, including classes.
  • Scope
    Scope indicates what parts of your code can call the method. Choices are Global, Public, Protected and Private.
    • Global computed properties can be used anywhere in your code with no restrictions. These are available only with Modules.
    • Public computed properties can be called from anywhere in your code with no restrictions. These are available only with Classes.
    • Protected computed properties have some restrictions, which vary depending on where the method is located (class or module).
    • Private computed properties can only be called by the module or class that contains the method.

The property signature (its name, and type) also appears at the top of the Editor for reference.

A computed property has two additional parts to it: a Getter and a Setter. A computed property can be expanded in the Navigator to display the Get and Set sections below the property name. You add code to the Get section to get or calculate a value for the property. You add code to the Set section to set a value for the property. If you do not include code in Set then the property becomes a read-only property. You can also leave out code in the Get section to make the property write-only, but that is less common. In the Navigator, the Get and Set sections appear as bold when they have code.

An example of a computed property might be a TotalPrice property of a Product class. You could implement TotalPrice with this code in Get:

Return Price * Quantity

If your computed property needs to retain a value, often you would create a matching private property to do so (usually prefixed with an “m”). For a computed property called "TeamName As String", this means you might do something like this:

Get:
Return mTeamName

Set:
mTeamName = Value

The above computed property is referring to a companion property:

mTeamName As String

Code can access the computed property by its name:

Dim tName As String = TeamName

For usage outside of the class or module that owns the computed property, they are often referenced differently (usually with the class or module name as a prefix). Refer to the Modules and Classes sections for specifics.

Although the behavior is different, using a computed property in this manner is not much different than a regular property. There is one notable benefit: you can set a breakpoint in the Set section so you can track when the property value changes.

Computed properties appear in the debugger, but it is important to note that the debugger will call the "Get" section of code in order to get the value to display. This may have unintended side-effects depending on how your code works.

See Also

Module Properties, Class Properties topic