BRL.System · BlitzMax

The system module's primary function is to provide synchronization with the operating system.

This achieved through the PollSystem and WaitSystem commands. However, you don't usually have to call these commands yourself as other BlitzMax commands will call them when necessary.

In addition, the system module also provides commands for checking the date and time, for moving the mouse pointer and for generating simple system requesters.

Functions

`Function InitSystemDriver(driver:TSystemDriver)`

Initialises the BlitzMax system driver.

There can only be one system driver initialised. A second call to this function will result in an exception.

`Function SystemDriver:TSystemDriver()`

Returns the BlitzMax system driver, or throws an exception if InitSystemDriver() hasn't been called with one.

`Function PollSystem()`

Poll operating system

PollSystem returns control back to the operating system, allowing such events as keystrokes and gadget actions to be processed. Control is then returned back to your program.

If PollSystem encounters a key, mouse or app suspend/resume/terminate event, an equivalent TEvent object event will be generated which may be intercepted using the EmitEventHook hook.

`Function WaitSystem()`

Wait for operating system

WaitSystem returns control back to the operating system, waiting until an event such as a keystroke or gadget action occurs.

Note that WaitSystem may wait indefinitely if there is no possibility of any events occuring, so use with caution.

If WaitSystem encounters a key, mouse or app suspend/resume/terminate event, an equivalent TEvent object will be generated which may be intercepted using the EmitEventHook hook.

`Function CurrentDate$(_format$="%d <i>b</i> <i>Y</i>")`

Get current date

By default, it returns the current date in the format: DD MON YYYY (i.e. 10 DEC 2000). You can also specify some parameters to return the date in a format of your choice:

parameter	description
%%a	Abbreviated day name (sun - mon).
%%A	Long day name (Sunday - Monday).
%%b	Abbreviated month name (jan - feb).
%%B	Long month name (January...).
%%c	Locale date & time.
%%d	day - in number (1..31).
%%H	hour - in number (0..23).
%%I	hour - in number (1..12).
%%j	day of the year (1..366).
%%m	month - in number (1..12).
%%M	minutes - in number (00..59).
%%P	AM / PM.
%%S	seconds - in number (00..59).
%%U	week number
%%w	day of the week (0..6).
%%W	week of the year (0..53).
%%x	locale data representation.
%%y	year without century (2014 --> 14).
%%Y	Year (2014).
%%Z	Time zone name.

You can use these parameters together:
CurrentDate("Month: %%a Day: %%d")

Returns

The current date as a string

Example

' currentdate.bmx

Print "The date is "+CurrentDate$()

`Function CurrentTime$()`

Get current time

Returns the current time in the format: HH:MM:SS (i.e. 14:31:57).

Returns

The current time as a string

Example

' currenttime.bmx

Print "The time is "+CurrentTime$()

`Function MoveMouse( x,y )`

Move mouse pointer

MoveMouse positions the mouse cursor at a specific location within the current window or graphics display.

`Function ShowMouse()`

Make the mouse pointer visible

`Function HideMouse()`

Make the mouse pointer invisible

`Function Notify( text$,serious=False )`

Notify user

Notify activates a simple user interface element informing the user of an event. The optional serious flag can be used to indicate a 'critical' event.

Note that a user interface may not be available when in graphics mode on some platforms.

Example

' notify.bmx

Notify "Hello World"

`Function Confirm( text$,serious=False )`

Request user confirmation.

Confirm activates a simple user interface element requesting the user to select between YES and NO options. If the user selects YES, then Confirm returns True. Otherwise, False is returned.

Note that a user interface may not be available when in graphics mode on some platforms.

Returns

True or False depending on the user's selection

Example

' confirm.bmx

result=Confirm("Are you sure?")

print result

`Function Proceed( text$,serious=False )`

Request user confirmation or cancellation.

Proceed activates a simple user interface element requesting the user to select between YES, NO and CANCEL options. If the user selects YES, then Proceed return 1. If the user selects NO, then Proceed returns 0. Otherwise, Proceed returns -1.

Note that a user interface may not be available when in graphics mode on some platforms.

Returns

1, 0 or -1 depending on the user's selection

Example

' proceed.bmx

result=Proceed("Are you sure you want to continue?")

print result

`Function RequestFile$( text$,extensions$="",save_flag=False,initial_path$="" )`

Display system file requester.

text is used as the title of the file requester.

The optional extensions string can either be a comma separated list of file extensions or as in the following example groups of extensions that begin with a "group:" and separated by a semicolon. save_flag can be True to create a save-style requester, or False to create a load-style requester.

initial_path is the initial path for the file requester.

Note that a user interface may not be available when in graphics mode on some platforms.

Returns

The path of the selected file or an empty string if the operation was cancelled.

Example

' requestfile.bmx

filter$="Image Files:png,jpg,bmp;Text Files:txt;All Files:*"
filename$=RequestFile( "Select graphic file to open",filter$ )

Print filename

`Function RequestDir$( text$,initial_path$="" )`

Display system folder requester.

text is used as the title of the file requester.

initial_path is the initial path for the folder requester.

Note that a user interface may not be available when in graphics mode on some platforms.

Returns

The path of the selected folder or an empty string if the operation was cancelled.

Example

' requestdir.bmx

path$=RequestDir("Select a Folder",CurrentDir())

Print "directory selected was "+path

`Function OpenURL( url$ )`

Opens a URL with the system's default web browser.

Note that a user interface may not be available when in graphics mode on some platforms.

`Function DesktopWidth()`

Get desktop width

Returns

Width of the desktop, in pixels

`Function DesktopHeight()`

Get desktop height

Returns

Height of the desktop, in pixels

`Function DesktopDepth()`

Get desktop depth

The depth of the desktop is the number of bits per pixel.

Note that on some platforms this function may return 0 if the desktop depth cannot be determined.

Returns

Bits per pixel depth of the desktop

`Function DesktopHertz()`

Get desktop refresh rate

Note that on some platforms this function may return 0 if the desktop refresh rate cannot be determined.

Returns

Refresh rate, in cycles per second, of the desktop