loq_ui_button

Contains a button class that uses a SpriteGroup for its states.

This module lets you create complex buttons that uses a SpriteGroup.  The Loqheart “Export Layout for Corona” flash extension will generate buttons using this module.

To use require the loq_ui_button module and call newButton() with a SpriteButton “constructor” table.

The buttons created by loq_ui_button supports additional events and states compared to the buttons created by the ui.lua module created by Ansca.  Check out the code sample below.

Usage

local loqbutton = require(‘loq_ui_button’)

Summary
loq_ui_buttonContains a button class that uses a SpriteGroup for its states.
Functions
activateMultitouchEnables multi-touch.
deactivateMultitouchDisables multi-touch.
newButtonA function that takes a constructor table to create a new SpriteButton.
SpriteButtonA button class that uses a SpriteGroup to represent its visual state.
SpriteButton Constructor TableThe newButton() function takes a table that can contain the following properties.
Functions
setEnabledUsed to enable or disable the touch events on the button and change its visual state.
setupSets the display of the button to the state passed in or the current state if none passed in.
Examples
Examples
Creating a SpriteButtonCreating a SpriteButton

Functions

activateMultitouch

local function activateMultitouch()

Enables multi-touch.

deactivateMultitouch

local function deactivateMultitouch()

Disables multi-touch.

newButton

local function newButton(paramObj)

A function that takes a constructor table to create a new SpriteButton.

Parameters

Returns

SpriteButton instance

See Also

SpriteButton

SpriteButton

A button class that uses a SpriteGroup to represent its visual state.

See Also

SpriteGroup, newButton

Summary
SpriteButton Constructor TableThe newButton() function takes a table that can contain the following properties.
Functions
setEnabledUsed to enable or disable the touch events on the button and change its visual state.
setupSets the display of the button to the state passed in or the current state if none passed in.

SpriteButton Constructor Table

The newButton() function takes a table that can contain the following properties.  Another other custom properties are passed along to button.

spriteGroupThe SpriteGroup instance that contains the visual states for the button.  If this is value is empty then newButton expects, the “up” and “down” parameters to be display objects.
autoPlaySet the sprite animation play when it changes state.  Default is true.  Otherwise will prepare the sprite without playing.
upName of the up animation sequence in the sprite instance, or a display object for the up state.  The spriteGroup parameter must be empty in the latter case.
downName of the down animation sequence in the sprite instance, or a display object for the down state.  The spriteGroup parameter must be empty in the latter case.
releaseName of the release animation sequence in the sprite instance.
pressName of the press animation sequence in the sprite instance.
upFrameThe start frame of the up animation sequence.  Not used when spriteGroup is empty.
downFrameThe start frame of the down animation sequence.  Not used when spriteGroup is empty.
pressFrameThe start frame of the press animation sequence.  Not used when spriteGroup is empty.
releaseFrameThe start frame of the release animation sequence.  Not used when spriteGroup is empty.
onUpA callback function for the up event.  Dispatched after a button has been released.  The function receives an event object.
onDownA callback function for the down event.  Dispatched after a button has been pressed.  The function receives an event object.
onPressA callback function for the press event.  Dispatched when button is first pressed.  Only triggers if the press sprite is assigned.  The function receives an event object.
onReleaseA callback function for the press event.  Dispatched when the button is released.  Only triggers if the release sprite is assigned.  The function receives an event object.
onTapA callback function for the tap event.  Dispatched when the button is tapped.  The function receives an event object.

Functions

setEnabled

Used to enable or disable the touch events on the button and change its visual state.

Parameters

  • _enable If true, enables touch events.  If false disables the touch events.
  • _state A string value: ‘up’, ‘down’, ‘press’, ‘release’ representing one of the visual states of the button.

setup

Sets the display of the button to the state passed in or the current state if none passed in.  If the sprite animations for the the buttons states have changed, you can use this to refresh the button.

Parameters

  • _state Sets the current sprite of the button.  If _state is nil, then refreshes the button sprite with the current state.
  • _keep If true, does not update the sprite if the current one is the same as the one to be played.

Examples

Summary
Examples
Creating a SpriteButtonCreating a SpriteButton

Examples

Creating a SpriteButton

Creating a SpriteButton

local loqsprite = require("loq_sprite")
local spriteFactory = loqsprite.newFactory("startButton_sheet")

-- Create a complex button with press, down, release, up states.
-- Attaches listeners for onPress, onDown, onRelease, onUp and onTap events.

local loqbutton = require("loq_ui_button")

local sbtn = loqbutton.newButton { -- create a SpriteButton constructor table
    spriteGroup = spriteFactory:newSpriteGroup("startButton_bup")

    -- when the state changes automatically play the sprite
    , autoPlay = true

    -- the sprites for the button states
    , up = "startButton_bup"
    , down = "startButton_bdown"
    , press = "startButton_bpress"
    , release = "startButton_brelease"

    -- the start frame of the state
    , upFrame = 1
    , downFrame = 2
    , pressFrame = 3
    , releaseFrame = 4

    -- the callback functions for the button states
    , onUp = function(event) atrace('startButton up') end
    , onDown = function(event) atrace('startButton down') end
    , onPress = function(event) atrace('startButton press') end
    , onRelease = function(event) atrace('startButton release') end
    , onTap = function(event) atrace('startButton tap') end


    -- custom data passed along to button to position it
    , x = 100
    , y = 100

    -- custom data to set the button's id
    , id = 'button 1'
}


local upDisplay = display.newRect(0, 0, 100, 100)
upDisplay:setFillColor(255, 0, 0)
local downDisplay = display.newRect(0, 0, 100, 100)
downDisplay:setFillColor(0, 255, 255)

local lbtn = loqbutton.newButton {
    -- spriteGroup is empty, instead use display objects for the state
      up = upDisplay
    , down = downDisplay
    , onTap = function(event) atrace('rect button tap') end
    , id = 'button 2'
}
A group of sprites in a display group instance.
local function activateMultitouch()
Enables multi-touch.
local function deactivateMultitouch()
Disables multi-touch.
local function newButton(paramObj)
A function that takes a constructor table to create a new SpriteButton.
A button class that uses a SpriteGroup to represent its visual state.
Close