Module mojo.app

The app module contains the App class along with various support functions for controlling application behaviour.

Imports:	mojo.audio mojo.graphics mojo.input
Classes:	App DisplayMode
Functions:	DesktopMode : DisplayMode () DeviceHeight : Int () DeviceWidth : Int () DisplayModes : DisplayMode[] () EndApp : Void () GetDate : Int[] () GetDate : Void ( date:Int[] ) HideMouse : Void () LoadState : String () LoadString : String ( path:String ) Millisecs : Int () OpenUrl : Void ( url:String ) SaveState : Void ( state:String ) SetDeviceWindow : Void ( width:Int, height:Int, flags:Int ) SetSwapInterval : Void ( interval:Int ) SetUpdateRate : Void ( hertz:Int ) ShowMouse : Void () UpdateRate : Int ()

Function Documentation

Function DesktopMode : DisplayMode ()

Gets the display mode used by the desktop.

On targets other that desktop and xna, this returns a DisplayMode with width and height equal to DeviceWidth and DeviceHeight.

Function DeviceHeight : Int ()

Returns the height of the application's device window, in pixels.

On the desktop and xna targets, you can use SetDeviceWindow to alter the size of the device window.

On other targets, you cannot directly control the size of the graphics device via mojo. This must be done by editing the 'native' project code for the target.

Function DeviceWidth : Int ()

Returns the width of the application's device window, in pixels.

On the desktop and xna targets, you can use SetDeviceWindow to alter the size of the device window.

On other targets, you cannot directly control the size of the graphics device via mojo. This must be done by editing the 'native' project code for the target.

Function DisplayModes : DisplayMode[] ()

Gets an array of valid fullscreen display modes for use with SetDeviceWindow.

On targets other than desktop and xna, this returns an empty array.

Function EndApp : Void ()

Ends the current application.

Note that ending an application may not be completely possible on some targets - for example, html5 and flash applications cannot be 'closed' because they are usually embedded in a browser. However, Monkey will attempt to end the app as best it can, at least ensuring that no more app code will be executed.

Important! On Windows Phone 8, The only time you can end an application is when the OS calls your app's OnClose or OnBack method. Calling EndApp at any other time will have no effect on Windows Phone 8.

Function GetDate : Int[] ()

Returns the current date and time as an array of 7 integers: year, month (1-12), day (1-31), hours (0-23), minutes (0-59), seconds (0-59) and milliseconds (0-999).

On the GLFW target, GetDate is only accurate to the second. Milliseconds are not available and index 6 of the GetDate array will always return 0.

Example

Import mojo

Class MyApp Extends App

    Method OnCreate()

        SetUpdateRate 60

    End

    Method OnRender()

        Local date:=GetDate()

        Local months:=["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"]

        Local day:=("0"+date[2])[-2..]
        Local month:=months[date[1]-1]
        Local year:=date[0]
        Local hour:=("0"+date[3])[-2..]
        Local min:=("0"+date[4])[-2..]
        Local sec:=("0"+date[5])[-2..] + "." + ("00"+date[6])[-3..]

        Local now:=hour+":"+min+":"+sec+"  "+day+" "+month+" "+year

        Cls
        DrawText now,DeviceWidth/2,DeviceHeight/2,.5,.5
    End

End

Function Main()

    New MyApp

End

Function GetDate : Void ( date:Int[] )

Fills the date array with 7 integers representing the current date: year, month (1-12), day (1-31), hours (0-23), minutes (0-59), seconds (0-59) and milliseconds (0-999).

Function HideMouse : Void ()

Hides the mouse pointer if the underlying operation system supports a mouse.

Function LoadState : String ()

Loads a string representing the application's persistant state as previously saved with SaveState.

If the application state hasn't yet been previously saved, LoadState returns an empty string.

This is generally used to store data such as user preferences and high score tables.

Note: On the android target, building and uploading a new version of an application to a device will not clear the application's state. To do this, you must manually uninstall the application from the device first.

See also SaveState

Example

'run this app several times to see application state being updated.
Import mojo.app
Import mojo.graphics

Class MyApp Extends App

    Field state$

    Method OnCreate()

        'comment out the following line to reset state
        state=LoadState()

        If state
            Print "state found - updating state!"
            state=Int( state )+1
        Else
            Print "state not found - creating initial state!"
            state="1"
        Endif

        SaveState state
    End

    Method OnRender()
        Cls
        DrawText "state="+state,0,0
    End

End

Function Main()
    New MyApp
End

Function LoadString : String ( path:String )

Loads a string from path.

See also Resource paths, File formats

Function Millisecs : Int ()

Returns the number milliseconds (thousandths of a second) the application has been running. Divide this by 1000.0 to get the number of seconds the applications has been running.

Example

Import mojo.app
Import mojo.graphics

Class MyApp Extends App

    Method OnCreate()
        SetUpdateRate 10
    End

    Method OnRender()
        Cls 128,0,255
        DrawText "Application has been running for: "+Millisecs()/1000.0+" seconds.",0,0
    End

End

Function Main()
    New MyApp
End

Function OpenUrl : Void ( url:String )

Opens the given url using the underlying operating system.

OpenUrl is only available on the hltm5, glfw, android, ios and win8 targets. On other targets, OpenUrl does nothing.

Example

Import mojo

Class MyApp Extends App

    Method OnCreate()

        SetUpdateRate 60

    End

    Method OnUpdate()

        If MouseHit(0)
            If MouseY()\<DeviceHeight/2
                OpenUrl "http://www.monkeycoder.co.nz"
            Else
                OpenUrl "mailto:blitzmunter@gmail.com"
            Endif
        Endif
    End

    Method OnRender()

        Cls
        DrawText "Click above to visit Monkeycoder, below to email Mark!",DeviceWidth/2,DeviceHeight/2,.5,.5
    End


End

Function Main()

    New MyApp

End

Function SaveState : Void ( state:String )

Saves a string representing the application's persistant state.

This is generally used to store data such as user preferences and high score tables.

See also LoadState

Function SetDeviceWindow : Void ( width:Int, height:Int, flags:Int )

Sets the application's device window to the given width and height.

You can only change the device window on the desktop and xna targets.

Calling this function does NOT result in your application's OnResize method being called.

flags can be any combination of the following values (use the | operator to combine flags):

flags	meaning	targets
1	Fullscreen	glfw3, xna
2	Resizable window	glfw3
4	Decorated window	glfw3
8	Floating window	glfw3
16	Depth buffered	glfw3
32	Single buffered	glfw3
64	Use second monitor	glfw3

Use DisplayModes for a list of valid fullscreen device width/heights.

Note that this function is not affected by any app config settings such as #GLFW_WINDOW_FULLSCREEN.

Function SetSwapInterval : Void ( interval:Int )

Attempts to change the 'swap interval' of the application's device.

This refers to how many frames to wait before graphics are displayed (or 'swapped') after being rendered. Setting the swap interval to '1' effectively enables vsync, '0' disables it.

SetSwapInterval only has any effect on the desktop target and, even then, is not universally supported by all graphics drivers on the PC. It may also only work in fullscreen mode.

Use with care!

Function SetUpdateRate : Void ( hertz:Int )

Sets the application's update rate.

If hertz is non-zero, this is the number of times per second that the application's OnUpdate method should be called. Commonly used update rates are 60, 30, 20, 15, 12 or 10 updates per second. OnRender is also called at the same frequency if possible (after each OnUpdate), meaning SetUpdateRate effectively also sets the target frames per second.

If hertz is zero, the app goes into 'free running' mode. In this mode, the app executes OnUpdate/OnRender in pairs as quickly as possible. The exact behaviour differs depending on target:

Target	Effect of update rate 0
Desktop	Updates are perform as quickly as possible. Timing is provided by vsync, or the app can perform 'delta timing'.
Html5	Updates are performed using the requestAnimationFrame feature, which depends on the refresh rate of the monitor (usually 60hz).
iOS, Android, WinRT, PSM	Updates are performed at vsynced 60hz.
Flash, Xna	Updates are performed at 60hz.

See also OnUpdate, UpdateRate, SetSwapInterval

Example

Import mojo.app
Import mojo.graphics

Class MyApp Extends App

    Field updates,updateRate

    Method OnCreate()
        updateRate=15
        SetUpdateRate updateRate
    End

    Method OnUpdate()
        updates+=1
        If updates=updateRate
            updates=0
            updateRate*=2
            If updateRate=240 updateRate=15
            SetUpdateRate updateRate
        Endif

    End

    Method OnRender()
        Cls 128,0,255
        DrawText "updateRate="+updateRate+", updates="+updates,0,0
    End

End

Function Main()
    New MyApp
End

Function ShowMouse : Void ()

Shows the mouse pointer if the underlying operation system supports a mouse.

Function UpdateRate : Int ()

Returns the current update rate, as set by SetUpdateRate.

See also SetUpdateRate