Plasmacore:Applications and Screens

From Plasmaworks

Class Application

In a Plasmacore program, class Application acts as the primary event dispatcher and program manager. You generally do not need to interact with it directly, though you may wish to install a custom ExitRequestHandler. Type "gogo doc Application::exit_request_handler" for more information.

Class Screen

A Plasmacore Screen provides program state, view, and control. The application maintains a Screen stack, with the topmost screen on the stack having active control. Your main class (topmost or specified with [main {classname}]) should extend class Screen; the program will start there.

Each Screen has the following methods.

Class Methods

current(): This method returns the active screen (same as Application.screen).

Lifecycle Events

init(...): As with any class, the initializer is called when you first create an object of the class.

on_activate(): This method is called when a screen is about to have update() and/or draw() called on it for the first time. This is sometimes a while after the screen is created, so on_activate() is a good place to put timing-sensitive commands.

on_suspend(): This method is called whenever a screen is about to become inactive.

on_deactivate(): This method is called when a screen is about to become permanently replaced.

Examples assuming screen 1 is the active screen:

Action	Events
screen1.push(screen2)	screen1.on_suspend() screen2.on_activate()
screen1.replace_with(screen2)	screen1.on_suspend() screen1.on_deactivate() screen2.on_activate()
screen2.pop	screen2.on_suspend() screen2.on_deactivate() screen1.on_resume # assuming screen1 is the prior screen

on_resume(): Called when another active screen that was push()ed on this one relinquishes control (via advance() or pop()) and this screen becomes active once more. Note that if the resumed screen has never had an update or draw, its on_activate() is called instead of its on_resume().

on_images_lost(): Called on all screens when image data has been irrevocably lost. Currently only happens on Android due to app switching. Generally you don't need to do anything, but if you're using any OffscreenBuffer object or Image objects created with custom Bitmap data then you'll need to recreate them.

Update Cycle and Input

update(): When a screen is the active screen on the stack, its update() method is called 60 times per second. Update your game state in this method.

draw(): When a screen is the active screen on the stack, its draw() method is called up to 60 times per second. Draw the current game state here.

on(MouseEvent e)

Called for each kind of mouse input.

 # TECHNIQUE 1
 method on( MouseEvent e )
   if (e.is_button_press)
     println( "button #$ of mouse #$ pressed at position $." (e.button,e.mouse_id,e.position) )
   elseIf (e.is_button_release or e.is_movement)
     println( "Similar stuff" )
   else
     println( "Something else" )
   endIf
 
 # TECHNIQUE 2
 method on( MouseEvent e )
   which (e.type)
     case MouseEvent.button_press
       println( "button #$ of mouse #$ pressed at position $." (e.button,e.mouse_id,e.position) )
     case MouseEvent.button_release, MouseEvent.movement
       println( "Similar stuff" )
     others
       println( "Something else" )
   endWhich

For multitouch devices, each different touch registers as a different mouse id.
See class Input for other mouse-related info.

on(KeyEvent e)

Called for each keyboard event type (press, release, repeat - e.g. key.type == KeyEvent.type_press).
Compare e.keycode to Key.keycode_escape, etc.
Compare e.unicode to 'A', '!', etc.
Use e.is_press('A') or e.is_press(Key.keycode_a), etc.
See class Input for other keyboard-related info and methods, including "Input.keyboard_visible = true" for virtual keyboards.

on(AccelerationEvent e)

Called on platforms that have accelerometer input.
Use the gravity readings of e.x, e.y, and e.z.
Call e.orientation() to obtain RollPitchYaw orientation data with roll, pitch, and yaw.

Transfer of Control

push(Screen,[Int32 fade_style]): Push another screen on top of this one, allowing it to assume control. You can pass Screen.fade_none (the default), Screen.fade_between (the most common fade), Screen.fade_in, or Screen.fade_out.

pop([Int32 fade_style]): Removes this screen from the stack and allows the previous screen to resume control.

replace_with(Screen,[Int32 fade_style]): Replaces this screen with the given screen.

chain(Screen): Specifies a screen to be the "next" screen after this one. See advance(), below.

advance([Int32 fade_style]): If a "next" screen is specified, performs a replace_with(). Otherwise performs a pop().

Example

 # Demonstrates using Screens as game states.  A Title Screen alternates
 # with a Controls Screen until a tap (aka click).  The app then transitions
 # to a Game Screen that can become a Pause Screen with a tap.
 class TitleScreen : Screen
   PROPERTIES
     stopwatch() : Stopwatch
 
   METHODS
     method init
 
     method on_activate
       Display.background_color = Color.red
 
     method update
       if (stopwatch.elapsed_seconds > 2) replace_with( ControlsScreen() )
 
     method draw
       SystemFont.handle = Handle.center
       SystemFont.draw( "TITLE SCREEN\n\nTap to Start", Display.center )
 
     method on( MouseEvent e )
       if (e.is_button_press) replace_with( GameScreen(), Screen.fade_between )
 endClass
 
 class ControlsScreen : Screen
   PROPERTIES
     stopwatch() : Stopwatch
 
   METHODS
     method init
 
     method on_activate
       Display.background_color = Color.yellow
 
     method update
       if (stopwatch.elapsed_seconds > 2) replace_with( TitleScreen() )
 
     method draw
       SystemFont.handle = Handle.center
       SystemFont.draw( "CONTROLS SCREEN\n\nTap to Start", Display.center )
 
     method on( MouseEvent e )
       if (e.is_button_press) replace_with( GameScreen(), Screen.fade_between )
 endClass
 
 class GameScreen : Screen
   METHODS
     method init
 
     method on_activate
       on_resume
 
     method on_resume
       Display.background_color = Color.blue
 
     method draw
       SystemFont.handle = Handle.center
       SystemFont.draw( "GAME PLAY\n\nTap to Pause", Display.center )
 
     method on( MouseEvent e )
       if (e.is_button_press) push( PauseScreen() )
 endClass
 
 class PauseScreen : Screen
   METHODS
     method init
 
     method on_activate
       on_resume
 
     method on_resume
       Display.background_color = Color.gray
 
     method draw
       SystemFont.handle = Handle.center
       SystemFont.draw( "PAUSED\n\nTap to Resume", Display.center )
 
     method on( MouseEvent e )
       if (e.is_button_press) pop
 endClass