BlitzMax/Modules/BASIC/BlitzMax runtime

The Blitz runtime module provides low level functionality required by BlitzMax applications when they are running. This includes things like memory management, exception handling and string and array operations.

Much of the functionality provided by this module is hidden from application programmers, but is instead used 'behind the scenes' by the compiler. However, there are some very useful commands for debugging, memory management and simple standard IO.

Information: The AppDir global variable contains the fully qualified directory of the currently executing application. An application's initial current directory is also set to AppDir when an application starts.

Information: The AppTitle global variable is used by various commands when a default application title is required - for example, when opening simple windows or requesters. Initially, AppTitle is set the value "BlitzMax Application". However, you may change AppTitle at any time with a simple assignment.

Information: The AppArgs global array contains the command line parameters sent to an application when it was started. The first element of AppArgs always contains the name of the application. However, the format of the name may change depending on how the application was launched. Use AppDir or AppFile for consistent information about the applications name or directory.

Example:

' appargs.bmx
' print the command line arguments passed to the program at runtime
Print "Number of arguments = "+AppArgs.length
For a$=EachIn AppArgs
Print a$
Next

Information: The LaunchDir global variable contains the current directory at the time the application was launched. This is mostly of use to command line tools which may need to access the 'shell' current directory as opposed to the application directory.

Information: mode can be one of the following:
1 : automatic GC - memory will be automatically garbage collected
2 : manual GC - no memory will be collected until a call to GCCollect is made
The default GC mode is automatic GC.

Rem
My Rem Example
First created 9th August, 2004
(C)2050 Blitz Intergalactic Software Corporation
End Rem
Print "This program has no useful function"
Rem
Remarks are useful for making your program easily readable.
You can leave details explaining the function of your program
in a remarks section so that you and any other programmers
that work with your code can more easily understand the workings
of your program
End Rem
Print "Sorry."
End

Rem
Int is a signed 32 bit integer BlitzMax primitive type.
End Rem
Local a:Int
' the following values all print 0 as BlitzMax "rounds to zero"
' when converting from floating point to integer
a=0.1;Print a
a=0.9;Print a
a=-0.1;Print a
a=-0.9;Print a

Rem
Long is a signed 64 bit integer BlitzMax primitive type.
End Rem
Const MAXLONG:Long=$7fffffffffffffff:Long
Const MINLONG:Long=$8000000000000000:Long
Print "A long can have the maximum value of:"+MAXLONG
Print "A long can have the minimum value of:"+MINLONG

Rem
Double is a 64 bit floating point BlitzMax primitive type.
End Rem
Local speedoflight:Double
Local distance:Double
Local seconds:Double
speedoflight=299792458:Double 'meters per second
distance=149597890000:Double 'average distance in meters from earth sun
seconds=distance/speedoflight
Print "Number of seconds for light to travel from earth to sun="+seconds

Rem
Object is the base class of all BlitzMax types.
The following function attempts to cast from any object to
the custom type TImage and returns true if the given object
is an instance of TImage or an instance of a &Type derived
from TImage.
End Rem
Function IsImage(obj:Object)
If TImage(obj) return True
Return False
End Function

Description: Else provides the ability for an If Then construct to execute a second block of code when the If condition is False.

Example:

Rem
Else provides the ability for an If Then construct to execute a second block of code when the If condition is false.
End Rem
i=3
If i<5 Print "i<5" Else Print "i>=5" 'single line If Else
If i<5 'block style If Else
Print "i<5"
Else
Print "i>=5"
EndIf

Description: ElseIf provides the ability to test and execute a section of code if the initial condition failed.

Example:

Rem
ElseIf provides the ability to test and execute a section of code if the initial condition failed.
End Rem
age=Int( Input("How old Are You?") )
If age<13
Print "You are young"
ElseIf age<20
Print "You are a teen!"
Else
Print "You are neither young nor a teen"
EndIf

Rem
While executes the following section of code repeatedly while a given condition is true.
End Rem
Graphics 640,480
While Not KeyHit(KEY_ESCAPE) 'loop until escape key is pressed
Cls
For i=1 to 200
DrawLine rnd(640),rnd(480),rnd(640),rnd(480)
Next
Flip
Wend

Rem
Select begins a block featuring a sequence of multiple comparisons with a single value.
End Rem
a=Int( Input("Enter Your Country Code ") )
Select a
Case 1
Print "You are from America"
Case 44
Print "You are from the United Kingdom"
Case 62
Print "You are from Australia"
Case 64
Print "You are from New Zealand"
Default
Print "I cannot tell which country you are from"
End Select

Rem
Local defines a variable as local to the Method or Function it is defined meaning it is automatically released when the function returns.
End Rem
Function TestLocal()
Local a
a=20
Print "a="+a
Return
End Function
TestLocal
Print "a="+a 'prints 0 or if in Strict mode is an error as a is only local to the TestLocal function

Rem
Function marks the beginning of a BlitzMax function declaration.
When a function does not return a value the use of brackets when
calling the function is optional.
End Rem
Function NextArg(a$)
Local p
p=Instr(a$,",")
If p
NextArg a$[p..]
Print a$[..p-1]
Else
Print a$
EndIf
End Function
NextArg("one,two,three,four")
NextArg "22,25,20" 'look ma, no brackets

Comment: The Type or Method must be extended (compilation will fail if it was not extended).

Example:

Rem
A BlitzMax type that contains Abstract methods becomes abstract itself.
Abstract types are used to define interfaces that extending types must
implement before they can be used to create new instances.
In the following code TShape is an abstract type in that you can not
create a TShape but anything extending a TShape must implement a Draw()
method.
End Rem
Type TShape
Field xpos,ypos
Method Draw() Abstract
End Type
Type TCircle Extends TShape
Field radius
Function Create:TCircle(x,y,r)
Local c:TCircle=New TCircle
c.xpos=x;c.ypos=y;c.radius=r
Return c
End Function
Method Draw()
DrawOval xpos,ypos,radius,radius
End Method
End Type
Type TRect Extends TShape
Field width,height
Function Create:TRect(x,y,w,h)
Local r:TRect=New TRect
r.xpos=x;r.ypos=y;r.width=w;r.height=h
Return r
End Function
Method Draw()
DrawRect xpos,ypos,width,height
End Method
End Type
Local shapelist:TShape[4]
Local shape:TShape
shapelist[0]=TCircle.Create(200,50,50)
shapelist[1]=TRect.Create(300,50,40,40)
shapelist[2]=TCircle.Create(400,50,50)
shapelist[3]=TRect.Create(200,180,250,20)
Graphics 640,480
While Not KeyHit(KEY_ESCAPE)
Cls
For shape=EachIn shapelist
shape.draw
Next
Flip
Wend
End

Rem
New creates a BlitzMax variable of the Type specified.
End Rem
Type MyType
Field a,b,c
End Type
Local t:MyType
t=New MyType
t.a=20
Print t.a
' if a new method is defined for the type it will also be called
Type MyClass
Field a,b,c
Method New()
Print "Constructor invoked!"
a=10
End Method
End Type
Local c:MyClass
c=New MyClass
Print c.a

Rem
ModuleInfo allows properties such as Author and Copyright to be included in a module file.
End Rem
Module PUB.Sequencer
ModuleInfo "Framework: Audio Sequencer for use with FreeAudio"
ModuleInfo "Copyright: Blitz Research Ltd"
ModuleInfo "Author: Simon Armstrong"
ModuleInfo "Version: 1.00"

Rem
IncBin embeds an external data file in a BlitzMax program that can
then be read using the "incbin::" device name.
End Rem
' code snippet from demos/firepaint/firepaint.bmx
Incbin "stars.png"
Local stars=LoadImage( "incbin::stars.png" )

Description: Framework builds the BlitzMax application with only the Module specified rather than all modules installed.

Comment: If you specify some module with Framework, only that module and ones it imports are compiled with your code. You can then import additional modules using Import. Common framework modules are Brl.Basic and Brl.Max2D, for console and 2d applications respectively.

' restoredata.bmx
For i=1 To 5
RestoreData mydata 'reset the data pointer everly loop so we don't read past the end
ReadData name$,age,skill
Print "name="+name+" age="+age+" skill="+skill
Next
#mydata 'program label that can be used with the RestoreData command
DefData "Simon",37,5000