Cerberus X Documentation

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
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 window, in pixels.
DeviceWidth : Int () Returns the width of the application's device window, in pixels.
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.
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 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, 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:martin.leidel@gmail.com"
Endif
Endif
End

Method OnRender()

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

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.

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.

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):

flagsmeaningtargets
1Fullscreenglfw3, xna
2Resizable windowglfw3
4Decorated windowglfw3
8Floating windowglfw3
16Depth bufferedglfw3
32Single bufferedglfw3
64Use second monitorglfw3
128Use stencil bufferglfw3

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:

TargetEffect of update rate 0
DesktopUpdates are perform as quickly as possible. Timing is provided by vsync, or the app can perform 'delta timing'.
Html5Updates are performed using the requestAnimationFrame feature, which depends on the refresh rate of the monitor (usually 60hz).
iOS, Android, WinRT, PSMUpdates are performed at vsynced 60hz.
Flash, XnaUpdates 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