Getting Started - UI Styles

Get up-and-running quickly with Styles.

Overview

Style objects are the basic type of formatting for any widget from dmc-corona-ui. In fact, it's impossible not to have a style associated with a widget!

Styles are simply containers for properties. They "answer questions" from Widgets about their look, like "What is my width?".

Styles also notify Widgets of any changes so Widgets can update their look.

Except for x/y coordinates, any and all drawn aspects of a Widget start with the Style object. Any desired Widget changes have to be made in teh Style.

A Style for each Widget

Each widget has its own specific Style object to accomodate their styling differences. That Style-type and only that Style-type can be used with the Widget.

The Type for both Style and Widget Must Match

local dUI = require 'lib.dmc_ui'

-- Good, Text == Text

local widget = dUI.newText()
local style = dUI.newTextStyle()

widget.style = style

-- Bad, Button ~= TextField

local widget = dUI.newButton()
local style = dUI.newTextFieldStyle()

widget.style = style

Setting Style Properties

When creating a Style directly or locally on a Widget, ensure that the information is put into the correct location.

Setting Style-Info on Style

All style information for a style object is in the first level of a Style

dUI = require 'lib.dmc_ui'

style = dUI.newTextStyle{

    align = 'left',
    fillColor = {1,1,1,1},
    font = native.systemFont,
    textColor = {0,0,0,1},

}

Setting Style-Info on Widget

All style information for a Widget must be within a property called style.

dUI = require 'lib.dmc_ui'

text = dUI.newText{

    text="my text",

    style={
        align = 'left',
        fillColor = {1,1,1,1},
        font = native.systemFont,
        fontSize = 16,
        marginX = 10,
        marginY = 5,
        textColor = {0,0,0,1},
        strokeColor = {0,1,0,1},
        strokeWidth = 1
    }
}

Assign a Style

A Style can be created and assigned to a Widget in several ways:

Inline styles

This essentially creates an anonymous Style and assigns it to the Widget. This is good for quick app testing, but the drawback is that it doesn't help with reusability.

dUI = require 'lib.dmc_ui'

widget = dUI.newText{
    style = {
        align='right',
        fontSize=14,
    }
}

Separate Style object

Here we create a separate Style object and can assign that to 1 or many widgets. This works, but the drawback here is that you must have a reference to the Style object in order to assign it to the Widget.

dUI = require 'lib.dmc_ui'

-- create style object

style1 = dUI.newTextStyle()

-- assign inside of widget constructor

widget2 = dUI.newText{
    style=style1
}

-- assign anywhere by using property 'style'

widget1 = dUI.newText()
widget1.style = style1

Named Styles

A named style can be created anywhere in the app and referenced anywhere. This is very good approach as it provides great re-usability, and an entire app can easily be styled in this manner.

one_file.lua

dUI = require 'lib.dmc_ui'

-- this named style 'home-page' can be created anywhere in the app

style = dUI.newTextStyle{
    name='home-page'
}

another_file.lua

dUI = require 'lib.dmc_ui'

-- and assigned somewhere else

widget = dUI.newText{
    text="Big Title"
}
widget.style = 'home-page'

Themes

Themes take named styles one step further. A theme is essentially a collection of named styles. This is very good approach if you intend on switching styles in your app.

Modify a Style

Styles can be modified in two ways.

Indirectly

Some widgets have style "helpers" which allow properties to be set without needing to go through the style.

For example, these two are equivalent:

text = dUI.newText()

-- helper
text:setTextColor( 1, 1, 1 )

-- direct
text.style.textColor={ 1, 1, 1 }

Directly

Get a reference to the style you're interested in and make changes directly. This will always work, even if there's a helper available.

text = dUI.newText()

text.style.textColor={ 1, 1, 1 }
text.style.fillColor={ 1, 1, 1 }

Children Styles

Some Styles contain children Styles. Some of the time style properties can be accessed via helpers, but more often you'll just grab the style itself.

In this example we see that the Textfield widget has a main style style which contains three children styles hint, display, and background.

textfield = dUI.newTextField()

textfield.style.background.cornerRadius = 2
textfield.style.hint.fontSize = 24
textfield.style.display.textColor = {1,0,1,0.5}

One of the important features of Styles is that they can be linked together to form "Cascading Styles". This is done by simply setting the property inherit on the child substyle.

dUI = require 'lib.dmc_ui'

parent = dUI.newTextStyle()

-- inheritance set from constructor

child = dUI.newTextStyle{
    inherit = parent
}

-- inheritance set afterwards

child = dUI.newTextStyle()
child.inherit = parent
When a link is made, the substyle will be reset erasing any local modifications which had been made.

Behind the Scenes

Styles are simply containers for properties. Typically, custom styles might only store a few properties and get the rest from the hierarchy.

At some point, all Styles inherit from the Default style for that Widget-type. It's this way styles can be mostly empty, but still "contain" all information for a Widget.

When a Style is set on a Widget, a second empty Style is created, which is linked to the first style, and that second style is attached to the Widget. This allows you to change specific properties for a particular Widget without affecting all of the others. If a change is to be made to all of the Widgets, then make that change to a Style higher up in the hierarchy.