Dialog Trays (ssk.dialogs.*)

This module contains a factory for creating nice looking dialog trays with an optional floating-shadow effect as well as an optional touch blocker (modal versus modeless).

Basic Trays

Basic Dialog Trays

(Note: GIF motion is not a smooth as real thing.)

Creating a Basic Dialog Tray

To create a basic dialog tray of any width or height, use this function:

local dialog = basic.create( [ group [, x [, y [, params ]]]]])

group (display.currentStage) - A display group to insert tray into.
x, y (centerX,centerY) - < x, y > position to place tray center at.
params - A parameterized table of options:
- width (fullw/2) - Width of tray.
- height (fullh/2) - Height of tray.
- fill (_W_) - Fill color for tray background.
- blockerFill (_K_) - Fill color for 'blocker'.
- blockerAlpha (0.5) - Alpha of 'blocker'
- blockerAlphaTime (0) - Time it takes for blocker alpha to rise from 0 to blockerAlpha when tray is opening. Similarly time to fall from blockerAlpha to 0 when closing.
- closeOnTouchBlocker (false) - If true touching the blocker will close the dialog tray.
- softShadow (false) - If true the tray will have a nice hover/soft- shadow.
- softShadowFill (_K_) - Fill color for soft-shadow.
- softShadowOX (2) - X-offset shadow should use.
- softShadowOY (2) - Y-offset shadow should use.
- softShadowBlur (4) - How blured shadow should be, where higher values are more blurred.
- softShadowSigma (140) - Blur sigma for shadow's gaussian blur effect.
- softShadowAlpha (0.5) - Alpha for sof shadow.
- onClose (nil) - Optional function to call before closing tray.
- blockerAction (nil) - Optional function to call if blocker is touched.
- style (1) - Tray style.
  - 1 - Un-adorned rounded edges.
  - 2 - Rounded edges with a line embellishment.

Custom Trays

Custom dialog trays use a up to two images (one for the tray and one for the shadow) to create a nice looking floating dialog tray.

Custom Dialog Trays

(Note: GIF motion is not a smooth as real thing.)

Creating a Custom Dialog Tray

To create a custom dialog tray of any width or height, use this function:

local dialog = basic.create( [ group [, x [, y [, params ]]]]])

group (display.currentStage) - A display group to insert tray into.
x, y (centerX,centerY) - < x, y > position to place tray center at.
params - A parameterized table of options:
- width (fullw/2) - Width of tray.
- height (fullh/2) - Height of tray.
- fill (_W_) - Fill color for tray background.
- blockerFill (_K_) - Fill color for 'blocker'.
- blockerAlpha (0.5) - Alpha of 'blocker'
- blockerAlphaTime (0) - Time it takes for blocker alpha to rise from 0 to blockerAlpha when tray is opening. Similarly time to fall from blockerAlpha to 0 when closing.
- closeOnTouchBlocker (false) - If true touching the blocker will close the dialog tray.
- softShadow (false) - If true the tray will have a nice hover/soft- shadow.
- softShadowFill (_K_) - Fill color for soft-shadow.
- softShadowOX (2) - X-offset shadow should use.
- softShadowOY (2) - Y-offset shadow should use.
- softShadowBlur (4) - How blured shadow should be, where higher values are more blurred.
- softShadowSigma (140) - Blur sigma for shadow's gaussian blur effect.
- softShadowAlpha (0.5) - Alpha for sof shadow.
- onClose (nil) - Optional function to call before closing tray.
- blockerAction (nil) - Optional function to call if blocker is touched.
- trayImage - Path to PNG or JPG file that should be used as the tray image.
- shadowImage - Path to PNG or JPG file that should be used as the tray shadow.
  - Note: Shadow images are typically all white versions of the tray image. This is then shaded based on prior shadow settings.

Examples

Basic


   group = group or display.currentStage
   params = params or {}

   ssk.display.newRect( group, centerX, centerY, 
                                { w = fullw, h = fullh, fill = hexcolor("#ED9C55") } )

   local function showDialogTray( style )

         local width = 600
         local height = 400

         local function onClose( self, onComplete )
            transition.to( self, { y = centerY + fullh, transition = easing.inBack, 
                                            onComplete = onComplete } )
         end

         local dialog = ssk.dialogs.basic.create( group, centerX, centerY, 
                        { fill = hexcolor("#56A5EC"), 
                          width = width,
                          height = height,
                          softShadow = true,
                          softShadowOX = 8,
                          softShadowOY = 8,
                          softShadowBlur = 6,
                          closeOnTouchBlocker = true, 
                          blockerFill = _K_,
                          blockerAlpha = 0.55,
                          softShadowAlpha = 0.6,
                          blockerAlphaTime = 100,
                          onClose = onClose,
                          style = style } )


         local function closeTray( event )
            onClose( dialog, function() dialog.frame:close() end )
         end

         ssk.easyIFC:presetPush( dialog, "default", 0, 0, 280, 50, 
                                    "Close Dialog Tray: Style " .. style, closeTray )

         ssk.easyIFC.easyFlyIn( dialog, { delay = 250, time = 500, sox = 0, soy = fullh } )
   end

   local function onStyle1( event )
      showDialogTray(1)    
   end

   ssk.easyIFC:presetPush( group, "default", centerX - 200, centerY, 280, 50, 
                            "Show Dialog Tray: Style 1", onStyle1 )


   local function onStyle2( event )
      showDialogTray(2)        
   end

   ssk.easyIFC:presetPush( group, "default", centerX + 200, centerY, 280, 50, 
                            "Show Dialog Tray: Style 2", onStyle2 )

Custom

local width, height = ssk.misc.getImageSize( "images/fantasygui/dialog" .. style .. ".png" )
width = width * scale
height = height * scale

local function onClose( self, onComplete )
 transition.to( self, { y = centerY + fullh, transition = easing.inBack, 
                                 onComplete = onComplete } )
end

local dialog = ssk.dialogs.custom.create( group, centerX, centerY, 
             { width = width,
               height = height,
               softShadow = true,
               softShadowOX = 8,
               softShadowOY = 8,
               softShadowBlur = 6,
               closeOnTouchBlocker = true, 
               blockerFill = _K_,
               blockerAlpha = 0.15,
               softShadowAlpha = 0.3,
               blockerAlphaTime = 100,
               onClose = onClose,
               trayImage = "images/fantasygui/dialog" .. style .. ".png",
               shadowImage = "images/fantasygui/dialog" .. style .. "_shadow.png" } )


local function closeTray( event )
 onClose( dialog, function() dialog.frame:close() end )
end

ssk.easyIFC:presetPush( dialog, "default", 0, 0, 320, 50, 
                         "Close Custom Dialog Tray: Example " .. style, closeTray )

ssk.easyIFC.easyFlyIn( dialog, { delay = 250, time = 500, sox = 0, soy = fullh } )
end

local function onStyle1( event )
showDialogTray(0.5,1)
end
ssk.easyIFC:presetPush( group, "default", centerX + 200, centerY - 75, 320, 50, 
                    "Show Custom Dialog Tray: Example 1", onStyle1 )


local function onStyle2( event )
showDialogTray(0.75,2)
end
ssk.easyIFC:presetPush( group, "default", centerX + 200, centerY, 320, 50, 
                    "Show Custom Dialog Tray: Example 2", onStyle2 )

local function onStyle3( event )
showDialogTray(0.75,3)
end
ssk.easyIFC:presetPush( group, "default", centerX + 200, centerY + 75, 320, 50, 
                    "Show Custom Dialog Tray: Example 3", onStyle3 )