Special Attributes In Xojo

Introduction to Attributes

Attributes are key-value pairs that can be attached to nearly anything in a Xojo project. They actually don't even need a value, it is perfectly acceptable to leave the value empty. All three of the following are valid attributes:

Key
Key = True
Key = "String"

But, reading the attributes of an item requires introspection and overall isn't very useful. So what value is there in attributes that warrants a blog post? There are two special attributes the IDE is aware of and actively looking for on objects: Hidden and Deprecated.

The Hidden Attribute

This attribute hides the item from autocomplete and the debugger. It does not prevent access to the item, it simply hides it. Many developers used an underscore prefix trick in the past to accomplish the same thing, but the IDE now disallows that.

The Hidden attribute is especially useful for cleaning up the properties backing a computed property. Consider the following:

Public Computed Property HasFocus As Boolean
    Get
        Return Self.mHasFocus
  End Get
    Set
        If Self.mHasFocus <> Value Then
            If Value Then
                Self.SetFocus()
            Else
                Self.TrueWindow.SetFocus()
            End If
        End If
    End Set
End Property

Private Property mHasFocus As Boolean

When the object is viewed in the debugger, both HasFocus and mHasFocus will appear with identical values. By placing the Hidden attribute on the mHasFocus property, the property is completely ignored by the debugger and autocomplete. In this case, autocomplete isn't as important, since the property is private anyway.

The attribute can also be used on methods, including methods in interfaces. A good place to use this attribute is any of the Operator_ methods, such as OperatorConvert and OperatorCompare. Constructors are also a great place for this attribute. Normally, these methods will appear in the autocomplete list, but should probably never be called directly. Yes, calling the constructor chain is useful, but this attribute does not prevent that.

The attribute helps to make the object self-documenting. Since autocomplete will not show these items, there is reduced risk of using the object incorrectly.

The Deprecated Attribute

The Deprecated attribute allows developers to mark nearly anything as deprecated, while hiding it from autocomplete just like the Hidden attribute. This is most useful for developers who release their code to the public, but can also be useful in code which is shared between projects.

With the Deprecated attribute defined, any line using the item in question will be flagged when running an Analyze operation from the Project menu. The IDE will not show the deprecation warning when the project is loaded however, and will still run the project normally. The attribute only applies to the Analyze feature.

This can be useful in refactoring. Ever add a single character to a method name so the compiler will highlight every use of that method? While this is quite an effective trick, the project is left broken until every instance is fixed. Alternatively, the Deprecated attribute could be added to the method. When using Analyze, every use will be highlighted just as intended, but the project can be updated in pieces rather than all at once.

If releasing the code for the public to use, Deprecated can be even more powerful. This happens all the time in the Xojo framework, and happens to all code as it grows.

Imagine a List class that maintains a list of items. The class is released with a method Item(Index As Integer) As String for accessing individual items. Later, for the sake of clarity, it is decided that Item really should have been called ItemAtIndex. So the developer marks Item as deprecated.

When a user runs the analyzer, all uses of Item will be highlighted with the text "Item is deprecated." However, this won't help the user correct the problem. The user will need to look up in the documentation what should be used instead. This is when adding a value to the Deprecated attribute makes sense (remember: attributes are key/value pairs). Values are code, so when inputting a string, quotes will be necessary. In this case, the value will be "ItemAtIndex". Now the project analyzer will show "Item is deprecated. You should use ItemAtIndex instead."

Conclusion

Creating your own custom attributes aren't very useful because they are difficult to use through introspection. However, the "special" built in hidden and deprecated attributes can provide a lot of information to the Xojo IDE about the intention of your code which will ultimately make your code easier to use.