Tutorial – InterfaceOutlet

InterfaceOutlets Tutorial

Note

This tutorial is a continuation of the Interface Tutorial. Make sure you are already familiar with Interfaces before reading this page.

InterfaceOutlets provide a really easy way to access the Views you create in your interface files.

Contents

• Linking Views
• Using Linked Views
• Targeting Multiple Views
• How InterfaceOutlets Work

Linking Views

Before you can use InterfaceOutlets you need to link the Views you

Identifiers

For a View to be connected to an InterfaceOutlet you must define the View's identifier. The identifier is a unique name that a View has, you should generally should make it reasonably descriptive as.

For example, a suitable identifier for a Button that says 'Okay' would be 'okayButton'. Whilst it will still work, using an identifier with spaces or non-Latin characters is not ideal. You should generally use a name that would work as a Lua variable.

<Button identifier="okayButton" text="Okay"/>

Linking

For a Container to track a View with an identifier, it must be linked using an InterfaceOutlet.

This is done by assigning a property in the properties table to an InterfaceOutlet.

Note

You can either link an InterfaceOutlet to your ApplicationContainer subclass or, if it's also within another Container, you can subclass the parent Container and link it to that. In most situations you will want to link it to your ApplicationContainer subclass, but this may not always be the case.

class "MyApplicationContainer" extends "ApplicationContainer" {
    
    propertyName = InterfaceOutlet( "identifier" );

}

This will link a child View with "identifier" as its identifier to the property propertyName. self.propertyName can now be used to access the View.

---

It is generally advisable for clarity to use the identifier as the property name. When this is the case you can omit the identifier from the InterfaceOutlet connection call.

class "MyApplicationContainer" extends "ApplicationContainer" {
    
    okayButton = InterfaceOutlet();

}

Note

If there is more than one View with the same identifier the first View that is found will be used. If you want to link to multiple Views with the same identifier look at the Targeting Multiple Views section.

Using Linked Views

Note

It is important to note that before the desired View is added to the Container the value of the property will be false. During functions such as :initialise children have not yet been added and as such no InterfaceOutlets will be linked. If you want to use a linked View as soon as possible use add a handle for the ReadyInterfaceEvent.

Getting and Setting Properties

Once you link a View the property will be a reference to that View. Continuing the 'okayButton' example, self.okayButton will be the your 'Okay' Button's instance.

You can then get and set properties. For example, you could change the location of the Button and get its text.

self.okayButton.x = 100

local text = self.okayButton.text -- the variable 'text' now has the value of "Okay"

Adding Action Functions (i.e. clicking)

Action functions allow you to very easily run code when you often want to. The best example of this is clicking a button.

An action function must begin with 'on' followed by the property name of the InterfaceOutlet, with the first letter of the property name capitalised.

For example, the action function for 'okayButton' must be called 'onOkayButton'. The code below will change the text

function MyApplicationContainer:onOkayButton( event )
    event.sender.text = "Clicked!"
    -- or this, it's identical
    self.okayButton.text = "Clicked!"
end

Targeting Multiple Views

Linking

If you have a group of Views you want to access you can pass true as the second argument to the InterfaceOutlet constructor. If the property uses the same name as the identifier you can either use nil for the first argument or just enter the identifier string. Generally you should use a plural for the property name to indicate it is linked to multiple views.

okayButtons = InterfaceOutlet( "okayButton", true )

Using

How InterfaceOutlets Work

This section is not necessary for learning how to use Silica, but it might help if you're a little unsure about to use InterfaceOutlets. It also might just be interesting to know how one of the more intriguing aspects of Silica works.

1. Property Linkage

When the property is set in the class' properties table using okayButton = InterfaceOutlet() the outlet is added to a list of InterfaceOutlets the class has.

2. Container Initialisation

When the Container that links the View is initialised it starts monitoring changes to its children.

3. View Insertion

When the Container has a child View inserted (usually when the interface is being loaded) it will check to see if the identifier of the View matches any of its outlets. If it does it will set the value of the desired property of the Container to the View.

4. View Removal

If the View is removed from the Container the link will be broken and the value of the property will be reverted back to false. If another view is added with the identifier it will be linked up instead.

Next Steps

Check out the Container Subclass Interface Tutorial, which is the next in the Interface Tutorial series.