Module mojo.app

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

Declarations

Imports
`mojo.audio`	The audio module contains functions for playing sounds and music.
`mojo.graphics`	The graphics module contains various functions that allow you to draw 2D graphics on all supported Cerberus target platforms.
`mojo.input`	The input module allows programs to check for user input from a wide variety of devices such keyboards, mice, joysticks and touchsceens.

Imported By
`mojo` , `mojo2`

Please note that only documented modules are listed here, there might be undocumented modules that import this one.

Classes
`App`	This is the main application class.
`DisplayMode`	A simple structure that contains info on the various fullscreen display modes available when using the desktop target.

Functions
`DesktopMode : DisplayMode ()`	Gets the display mode used by the desktop.
`DeviceHeight : Int ()`	Returns the height of the application's device in pixels.
`DeviceWidth : Int ()`	Returns the width of the application's device in pixels.
`DeviceWindowHeight : Int ()`	Returns the height of the application's device window in desktop units.
`DeviceWindowWidth : Int ()`	Returns the width of the application's device window in desktop units.
`DisplayModes : DisplayMode[] ()`	Gets an array of valid fullscreen display modes for use with SetDeviceWindow.
`EndApp : Void ()`	Ends the current application.
`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).
`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).
`HideMouse : Void ()`	Hides the mouse pointer if the underlying operating system supports a mouse.
`LoadState : String ()`	Loads a string representing the application's persistant state as previously saved with SaveState.
`LoadString : String ( path:String )`	Loads a string from path.
`Millisecs : Int ()`	Returns the number milliseconds (thousandths of a second) the application has been running.
`OpenUrl : Void ( url:String )`	Opens the given url using the underlying operating system.
`SaveState : Void ( state:String )`	Saves a string representing the application's persistant state.
`SetDeviceWindow : Void ( width:Int, height:Int, flags:Int )`	Sets the application's device window to the given width and height in Desktop units.
`SetDeviceWindowIcon : Void ( _path:String )`	Sets the icon of the application's device window.
`SetDeviceWindowPosition : Void ( _x:Int, _y:Int )`	Sets the position of the application's device window.
`SetDeviceWindowSize : Void ( _width:Int, _height:Int )`	Sets the size of the application's device window in Desktop units.
`SetDeviceWindowSizeLimits : Void ( _minWidth:Int, _minHeight:Int, _maxWidth:Int, _maxHeight:Int )`	Sets the minimum and maximum size limits of the application's device window.
`SetDeviceWindowTitle : Void ( _title:String )`	Sets the title of the application's device window.
`SetSwapInterval : Void ( interval:Int )`	Attempts to change the 'swap interval' of the application's device.
`SetUpdateRate : Void ( hertz:Int )`	Sets the application's update rate.
`ShowMouse : Void ()`	Shows the mouse pointer if the underlying operating system supports a mouse.
`UpdateRate : Int ()`	Returns the current update rate, as set by SetUpdateRate.

Detailed Discussion

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

Functions 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 DeviceWindowWidth and DeviceWindowHeight.

Function DeviceHeight : Int ()

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

You cannot directly control the size of the graphics device via mojo. If possible at all this has to be done by using config settings or by editing the 'native' project code for the target.

Function DeviceWidth : Int ()

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

You cannot directly control the size of the graphics device via mojo. If possible at all this has to be done by using config settings or by editing the 'native' project code for the target.

Function DeviceWindowHeight : Int ()

Returns the height of the application's device window in desktop units. These units are the same as pixels unless your app runs on a Retina display.

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

Function DeviceWindowWidth : Int ()

Returns the width of the application's device window in desktop units. These units are the same as pixels unless your app runs on a Retina display.

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

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, Cerberus 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 operating system supports a mouse.

See also

ShowMouse

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.

Parameters

path - the data file path of the string to load, relative to your applications .data folder.

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.cerberus-x.com"
Else
OpenUrl "mailto:email@example.com"
Endif
Endif
End

Method OnRender()

Cls
DrawText "Click above to visit Cerberus X, below to email some one!",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.

Parameters

state - application state to save.

See also

LoadState

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

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

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
128	Use stencil buffer	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 SetDeviceWindowIcon : Void ( _path:String )

Sets the icon of the application's device window.

Works only for GLFW target.

Function SetDeviceWindowPosition : Void ( _x:Int, _y:Int )

Sets the position of the application's device window.

Please note, that the position does not include the title bar of the window.

Works only for GLFW target.

Function SetDeviceWindowSize : Void ( _width:Int, _height:Int )

Sets the size of the application's device window in Desktop units.

Works only for GLFW target.

Function SetDeviceWindowSizeLimits : Void ( _minWidth:Int, _minHeight:Int, _maxWidth:Int, _maxHeight:Int )

Sets the minimum and maximum size limits of the application's device window.

Works only for GLFW target.

Function SetDeviceWindowTitle : Void ( _title:String )

Sets the title of the application's device window.

Works only for GLFW target.

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 operating system supports a mouse.

See also

HideMouse

Function UpdateRate : Int ()

Returns the current update rate, as set by SetUpdateRate.

See also

SetUpdateRate