Easy Interfaces (ssk.easyIFC:*)

The Easy Interfaces library is a large library designed to produce:

This library has these features and benefits:

Lastly, this library provides a number of useful Effects that can be used to give your menus (and other interfaces) juicy visual effects.

Button Factories

Button Parameters

The following list is designed as a quick reference to the many button parameters.

Making Button Presets

Making a preset is as simple as:

  1. Specifying a table of Button Parameters,
  2. Adding that table to the list of known button button presets using addButtonPreset().

local params = 
{ 
    labelColor         = {1,1,1,1},
    labelSize          = 16,
    labelFont          = gameFont,
    labelOffset        = {0,1},
    unselRectFillColor = { 0.25,  0.25,  0.25, 1},
    selRectFillColor   = {0.5, 0.5, 0.5, 1},
    strokeWidth        = 1,
    strokeColor        = {1,1,1,0.5},
    emboss             = false, 
}
ssk.easyIFC:addButtonPreset( "default", params )

Later, you can use the preset like this:


easyIFC:presetPush( group, "default", 100, 100, 50, 40, "Hello" )

Default Presets

One great way to see how easy making presets is, is to look at the default presets that come with SSK2.

The default SSK2 presets can be found here: ~<path to ssk2>/interfaces/presets/default/.

Redefining Button Presets

You may redefine a preset at any time in two simple steps:

  1. Specifying a NEW table of Button Parameters,
  2. Adding that table to the list of known button presets using addButtonPreset() using an exiting preset name.

Any buttons created with that preset name after this change will use the new definition.

Tip: This is a handy feature. You can create your interface using the built-in defaults. Then, when you are ready, create a custom preset definition file and use the same preset names. This will replace all the built-in presets with your own.

Ready-Made Presets

Eventually, I expect ready-made presets to be available for free and/or paid paid on:

Button Instances

Button objects are regular display objects. Thus, they have all the same properties and methods listed on the Corona SDK API display.* reference page.

In addition, all buttons have the following properties and methods:

Properties

Methods

Button Listeners

Manually writing a solid button-listener is not straight-forward and requires a surprisingly large and sophisticated piece of code. This is often well beyond what most new and intermediate developers can do.

First, different kinds of buttons should execute their listener code at different times:

Second, the listener should gracefully handle all the weird things users do, such as:

  1. Touch a button, slide the finger off the button, then release. - Button visuals should update to tell user the button isn't selected any more and then NOT call the listener.
  2. Touch, swipe off, swipe back on, release - Again, update the visuals so the user knows the button state and then call the listener.
  3. Touch the screen, then swipe onto a button - The button should entirely ignore this. It is considered an 'accidental touch'.
  4. Touch one button and swipe onto another - Similar to case #1 above, but second button doesn't update visually. This is another 'accidental touch' scenario.
  5. ... The list goes on and you've got to handle it all.

Third, the listener should work equally well whether the developer has enabled 'multitouch' or not.

To handle all of this, the Easy Interfaces library uses a single (shared) listener for all buttons. This function is about 200 lines long and handles all of these interactions and button contexts.

All buttons use this listener by default. Then, if you want an action to happen at a particular contextual time, you supply your one (or more) small function(s) for one of these three named Button Parameters

onRelease

This is the default listener for push and radio buttons. 


-- Sample Push Button 'onRelease' Listener
local function onRelease( event )
    print("Pushed Button: " .. tostring( event.target:getText() ) )
end

-- Create Two Push Buttons
easyIFC:presetPush( group, "default", 100, 100, 50, 40, "Hello", onRelease )
easyIFC:presetPush( group, "default", 100, 150, 50, 40, "World", onRelease )

If you press the buttons created by this code, they will print:

"Pushed Button: Hello" OR "Pushed Button: World" 


-- Sample Radio Button 'onRelease' Listener
local function onRelease( event )
    print("Pushed Button: " .. tostring( event.target:getText() ) )
end

-- Create Two Radio
local first = easyIFC:presetRadio( group, "default", 100, 100, 50, 40, "Hello", onRelease )
easyIFC:presetRadio( group, "default", 100, 150, 50, 40, "World", onRelease )

first:toggle()

As soon as this code executes, the message "Pushed Button: Hello" will print.

Then if you do any of these actions NEXT:

onEvent

This is the default listener for Toggle Buttons. It is called every time the buttons toggle-state changes.

Note: The listener is not called when the visual state updates, but when the finger is lifted. i.e. Swiping on and off of a toggle button will not fire the listener.


-- Sample Toggle Button 'onEvent' Listener
local function onToggle( event )
    print("Pressed Button: " .. tostring( event.target:getText() ) )
    print("Is pressed ?= " .. tostring( event.target:pressed() ) )
end

easyIFC:presetToggle( group, "default", 100, 100, 50, 40, "Hello", onToggle )
easyIFC:presetToggle( group, "default", 100, 150, 50, 40, "World", onToggle )

If you touch these buttons, they will print a message any time you press and release the button. As expected, they ignore all 'weird' interactions and don't fire their listener unless a real toggle occured. Both buttons can be toggled and will ignore the state of the other button.


-- Sample Push Button 'onEvent' Listener
local function onToggle( event )
    print("Pressed Button: " .. tostring( event.target:getText() ) )
    print("Is pressed ?= " .. tostring( event.target:pressed() ) )
end

easyIFC:presetPush( group, "default", 100, 100, 50, 40, "Hello", nil, { onEvent = onToggle } )
easyIFC:presetPush( group, "default", 100, 150, 50, 40, "World", nil, { onEvent = onToggle } )

These buttons will fire two events. First when you touch the button, and second when you release the button.

If you touch a button and swipe away, you will not get the second event.

onPress

This listener is rarely used and excutes ONLY on the begining of a button touch. i.e. It is called when the user first touches the button.


-- Sample Push Button 'onPress' Listener
local function onPress( event )
    print("Pressed Button: " .. tostring( event.target:getText() ) )
end

easyIFC:presetPush( group, "default", 100, 100, 50, 40, "Hello", nil, { onPress = onPress } )

Touching this button will fire the listener immediately.

Swiping off and back onto the button is ignored and will not fire the listener again.

You must lift your finger and touch the button again to get a new call to the listener.

Label Factories

presetLabel

Creates label instance using a preset record.

ssk.easyIFC:presetLabel( group, presetName, text, x, y [, params ] )

quickLabel

ssk.easyIFC:quickLabel( group, text, x, y [, font [, size [, color [ , anchorX [, anchorY ]]]]] )

quickEmbossedLabel

ssk.easyIFC:quickEmbossedLabel( group, text, x, y [,font [,size [,colorM [,colorH [,colorS ]]]]] )

Label Factory Arguments

As you will have noticed, the above factories have a fairly consistent function signature and share common arguments. Those argument can be summarized as follows:

Making Label Presets

Making a preset is as simple as:

  1. Specifying a table of Label Parameters,
  2. Adding that table to the list of known label presets using addLabelPreset().

local params = 
{ 
    font                 = "Bounty Hunter.ttf",
    fontSize             = 32,
    embossTextColor      = _K_,
    embossHighlightColor = _Y_,
    embossShadowColor    = _G_,
}
ssk.easyIFC:addLabelPreset( "bounty", params )

Later, you can use the preset like this:


-- Use 'bounty' preset, but override fontSize
easyIFC:presetPush( group, "bounty", "Boom!", 100, 100, { fontSize = 60 } )

Label Preset Parameters

Presets take all of the following parameters:

Label Instances

Label Instances are regular display objects. Thus, they have all the same properties and methods listed on the Corona SDK API display.* reference page.

In addition, Preset Label Instances have the following properties and methods:

Properties

Methods

Effects

The button library comes with a set of functions that let you:

Tip: While they were first designed for interfaces, These functions can also be used on other display objects.

Visual Calculations

Fly Ins

Fly Ins


-- Silly Game

local function onPress( event )

   print("You Win!")

   transition.cancel( event.target )

   event.target.rotation = 0

   event.target:setText("Winner!")

   event.target:disable()

end

local button = ssk.easyIFC:presetPush( group, "default", 150, 100, 250, 40, 
                                       "Press Before Spinning Stops!", onPress )

local onComplete
local onComplete2

onComplete = function( obj )

    ssk.easyIFC.easyFlyIn( button, { delay = 1000, time = 1000, sdr = 720, 
                                     myEasing = easing.linear,
                                     onComplete = onComplete2 } ) 

end

onComplete2 = function( obj )

    obj:disable()
    obj:setText( "Loser!" )

end

ssk.easyIFC.easyFlyIn( button, { time = 500, sox = -fullw, onComplete = onComplete  } )

Flipping

easyFlip


   local button = ssk.easyIFC:presetPush( group, "default", x, y, 250, 40, "Flippy Button" )

   ssk.easyIFC.easyFlip( button, { delay = 500, time = 1250, myEasing = easing.outBounce } )

RoamingGamer Copyright © Roaming Gamer, LLC. 2008-2016; All Rights Reserved