Lgi Scripting Library

These are the built in methods for the Lgi scripting language:

	Strings	Containers	File System	Dates and Time	Bitmaps	User Interface	General
Global functions:	LoadString FormatSize Sprintf Print ToString	New Delete Len	ReadTextFile WriteTextFile SelectFiles SelectFolder ListFiles DeleteFile PathExists PathJoin PathSep	Sleep ClockTick Now	CreateSurface ColourSpaceToString StringToColourSpace	LoadDialog MessageDlg GetInputDlg GetViewById	Execute System OsName OsVersion CurrentScript Assert Throw DebuggerEnabled
Object Members:	obj.Find obj.Split obj.Join obj.Upper obj.Lower obj.Sub obj.Strip	obj.Add obj.HasKey obj.Delete obj.Sort	obj.Open obj.Read obj.Write obj.Pos obj.Close	obj.Year obj.Month obj.Day obj.Hour obj.Minute obj.Second obj.Milli obj.Date obj.Time obj.DateTime obj.Timestamp	obj.x obj.y obj.Bits obj.ColourSpace obj.Palette obj.Load obj.Save	obj.Handle obj.Id obj.Name obj.Value obj.Enabled obj.Foreground obj.Background	obj.Type obj.Length

string LoadString(id);

Loads a string from the resource file. The strings have to be stored in a Lgi resource file and loaded at runtime by the current application. There is a graphical editor for the resource files.

Arguments:

id - the string's id as an integer.

Returns:

A string or NULL on failure.

Example:

c = LoadString(186);
Print(c, "\n");

Enter offset:

string FormatSize(bytes);

Formats a number of bytes in KB, MB or GB as appropriate.

Arguments:

bytes - the size to format.

Returns:

A string containing the size description.

Example:

c = FormatSize(345674211);
Print(c, "\n");

329.66 M

string Sprintf(format[, args, ...]);

Formats a string. Not available on the mac platform.

Arguments:

format - the format of the output string, same as C's printf.
[optional]args - any arguments that are required to be formatted.

Returns:

A formatted string.

Example:

c = Sprintf("Format: %i, %i, %s, 0x%x\n", 345, 11, "StringArg", 0x1234fa);
Print(c);

Format: 345, 11, StringArg, 0x1234af

void Print(item1[, item2, ...]);

Prints variables on the console, if available. No new line is explicitly printed, you have to add "\n" to your arguments to move to the next line.

Arguments:

itemN - The object to print. Non string objects will be converted to string if possible.

Returns:

Nothing.

String ToString([items, ...]);

Converts all the arguments to strings.

Arguments:

itemN - And object to print.

Returns:

String.

int obj.Find(sub_string[, start[, end]]);

Finds a the position of a sub-string.

Arguments:

sub_string - The string to find. The search is case sensitive.
[optional] start - The start index of the area to search.
[optional] end - The end index of the area to search.

Returns:

The location of the sub-string or -1 if not found.

Example:

c = "A string to search";
Print(c.Find("to"), "\n");
Print(c.Find("missing"), "\n");

9
-1

list obj.Split(separator[, max_split]);

Splits a string into parts based on a separator.

Arguments:

separator - The string to use as a separator between the parts.
[optional] max_splits - The maximum number of splits to make.

Returns:

A list of strings. Could be empty if the input is also empty.

Example:

c = "123, 456, 879";
p = c.split(",");
for (i=0; i<p.Length; i++)
{
    Print("[", i, "]='", p[i].Strip(), "'\n");
}

[0]='123'
[1]='456'
[2]='879'

string obj.Join(list);

Joins a list of objects into a single string separated by the 'obj' string.

Arguments:

list - The objects to be joined.

Returns:

A string concatenation of all the source objects.

Example:

c = New("list");
c.Add(123);
c.Add(456);
c.Add(789);
p = ", ";
r = p.Join(c);
Print(r, "\n");

123, 456, 789

string obj.Upper();

Makes an upper case version of 'obj'.

Returns:

An upper case string.

Example:

c = "A string";
Print(c.Upper(), "\n");

A STRING

string obj.Lower();

Makes a lower case version of 'obj'.

Returns:

An lower case string.

Example:

c = "A string";
Print(c.Lower(), "\n");

a string

string obj.Sub(start[, end]);

Returns part of the string 'obj'.

Arguments:

start - The start of the sub-string.
[optional] end - The end of the sub-string. If not supplied the end of the source string is used.

Returns:

A string.

Example:

c = "A string";
Print(c.Sub(2, 5), "\n");
Print(c.Sub(4), "\n");

str
ring

string obj.Strip([delimiters]);

Strips the specified characters off the start and end of the string.

Arguments:

[optional] delimiters - The characters to strip, defaults to whitespace (' \t\r\n').

Returns:

A string.

Example:

c = "[A string]";
Print(c.Strip("[]"), "\n");

A String

object New(object);

Creates a new object.

Arguments:

object - the name of the object. Can be a built in type of a custom defined type.
- ### - A number create a binary block of the specified number of bytes.
- "List" - creates a list.
- "HashTable" - creates a hash table.
- "Surface" - creates a memory surface (bitmap) to draw on.
- "File" - creates a file object.
- "DateTime" - creates a date/time object.
- <custom_type_name> - Some custom type defined in script.

Returns:

The new object or NULL on failure.

Example:

c = New("DateTime");
c.Date = "1/4/2014";
Print(c.Type(), ": ", c, "\n");

DateTime: 1/04/2014 12:00:00a

void Delete(object);

Will set any object to NULL. Must be used with custom types before they go out of scope otherwise they will leak memory. But also works on any other type of object, like lists, hashtables or basic strings and ints.

Arguments:

object - the object to delete.

Returns:

Nothing.

int Len(object[, object2]);

Returns the length of an array or hashtable. If more than one object is passed it'll sum the length of all of them. Non collection objects count as 1 thing. For instance a integer or floating point value are "1" item.

Arguments:

object - some object collection.

Returns:

Count of items in collections.

void obj.Add(object[, key]);

Adds 'object1' to a container. Depending on the object type:

List: the key is an optional integer index. If not supplied the object is appended to the end.
HashTable: the key is NOT optional and specifies the key under which to store the object.

Arguments:

object - the object to add.
key - the location to store the object.

Returns:

Nothing.

Example:

c = New("list");
c.Add("first");
c.Add("second");
Print(c, "\n");
Print(c.Length, "\n");

{first, second}
2

bool obj.HasKey(key);

Returns true of the container has something stored at 'key':
Arguments:

key - the location to store the object.
- List: the key is an integer index.
- HashTable: the key is a string.

Returns:

TRUE if the object exists.

Example:

c = New("hashtable");
c.Add(23, "first");
c.Add(345, "second");
Print(c.HasKey("asd"), "\n");
Print(c.HasKey("first"), "\n");

0
1

void obj.Delete(key);

Removes and deletes an object from the container

Arguments:

key - the location of the object:
- List: the key is an integer index. If it's out of range, nothing happens.
- HashTable: the key is string. If the key isn't present nothing happens.

Returns:

Nothing.

Example:

c = New("hashtable");
c.Add(123, "first");
c.Add(456, "second");
Print(c.Length, "\n");
c.Delete("first");
Print(c.Length, "\n");

2
1

void obj.Sort(key);

Sorts a list. Not relevant for a HashTable.

Arguments:

- If the list contains strings or integers, not parameter is needed.
- If the list contains object references, then a string defining which field of the object to sort on needs to be provided.

Returns:

Nothing.

Example:

c = New("list");
c.Add("first");
c.Add("second");
c.Sort();

string ReadTextFile(filename);

Returns the contents of a text file.

Arguments:

filename - the name of the file

Returns:

the contents of the file as a string.

bool WriteTextFile(filename, data);

Writes the contents of a variable to a text file.

Arguments:

filename - the name of the file
data - the date to write, can either be a string or a binary object

Returns:

non-zero on succes, zero on failure.

void SelectFiles(ParentWnd, Callback[, FileTypes[, InitialDir[, MultiSelect[, SaveAs]]]]);

Shows a file select dialog.

Arguments:

ParentWnd - the handle of the parent window.
Callback - The name of the callback function as a string.
[optional] FileTypes - the types of files to select, e.g. "*.gif;*.png;*.jpg".
[optional] InitialDir - the initial folder to select from.
[optional] MultiSelect - TRUE if multiple file can be selected.
[optional] SaveAs - TRUE if dialog should be for saving a file.

Returns: Nothing.

Example:

function OnFiles(files)
{
    Print("Files:", files, "\n");
}
				
SelectFiles(Parent, "OnFiles", "*.png", "C:\\Users\\myUserName\\Desktop", 1);

C:\Users\myUserName\Desktop\2channel.png
C:\Users\myUserName\Desktop\19.Poster_1.png
C:\Users\myUserName\Desktop\payment.png

void SelectFolder(ParentWnd, Callback[, InitialDir]);

Shows a folder select dialog.

Arguments:

ParentWnd - the handle of the parent window.
Callback - the name of the callback function as a string.
[optional] InitialDir - the initial folder to select from.

Returns: nothing.

Example:

function OnFolder(folder)
{
    Print("Folder:", folder, "\n");
}
				
SelectFolder(Parent, "OnFolder", "C:\\Users\\myUserName\\Desktop");

list ListFiles(folder_path[, pattern]);

Lists files in a folder.

Arguments:

folder_path - the folder to list.
[optional] pattern - the files to list, e.g. "*.gif".

Returns:

list of file descriptors. You can access relavant meta-data using the fields:
- Name: the file's name.
- Length: the size in bytes.
- Modified: the date modified.
- Folder: True if the entry is a folder.

files = ListFiles(".");
if (files)
{
    for (i=0; i<files.Length; i++)
    {
        Print(files[i].Name, " is ", files[i].Length, " bytes\n");
    }
}

FileSystem.asm is 1080 bytes
FileSystem.script is 936 bytes
Object.script is 1320 bytes
Strings.script is 1440 bytes
System.script is 837 bytes

bool DeleteFile(path);

Deletes a file.

Arguments:

path - The path to the file to delete.

Returns:

True if the file is deleted.

string CurrentScript();

Returns:

the current script file and it's path.

bool Assert(value[, msg]);

Checks that 'value' is non-zero, if it is zero, it throws an exception with 'msg' if supplied.

Arguments:

value - The value to check.
msg - [Optional] the message to pass to Throw.

Returns:

Bool - true if value is non-zero.

void Throw([msg]);

Throws an exception, optionally with 'msg' as the message.

Arguments:

msg - [Optional] the message to display in the debugger.

Returns:

None.

void DebuggerEnabled(enabled);

Turns the debugger on or off.

Arguments:

enabled - True if you want the debugger to appear on an exception. If false the script will just exit at the point the exception happened, returning "false" to the caller.

Returns:

None.

int PathExists(path);

Queries the file system to see if a path exists as a file or folder.

Arguments:

path - The path to the query.

Returns:

0 - If the path doesn't exist.
1 - If the path is a file.
2 - If the path is a folder.

string PathJoin(path1[, path2[, ...]]);

Joins a whole lot of path fragments together, evaluating relative parts as needed.

Arguments:

path1 - The base path.
path2 - A relative path segment.

Returns:

The complete normalised path.

string PathSep();

Returns:

The path separator character for the current platform. ("\" on windows, "/" otherwise)

bool obj.Open(path[, mode]);

Opens a file. Typically this follows creating a file object with New and once the file operations are done, use Delete to clean up the memory.

Also of note: to get or change the size of the file use the Length member.

Arguments:

path - The path to the file to open.
[optional] mode - Type of access:
- "r" - Read access (the default).
- "w" - Write access.
- "rw" - Read and write access.

Returns:

True if the file is openned.

object obj.Read(length[, type]);

Reads content from a file at the current location.

Arguments:

length - The bytes to read.
type - The type of the data:
- 0: string data (the default).
- 1: integer data.

Returns:

The data read as the indicated type, or NULL if the read failed.

int obj.Write(object[, length]);

Writes the object to the file.

Arguments:

object - the object to write.
length - [optional] number of bytes to write.
If specified and the object is:
- an integer: valid values are 1, 2, 4, or 8 up to the maximum size of the actual variable.
- a string: any value from 1 through to the length of the string including the NULL in bytes (not characters).
If not specified and the object is:
- an integer: all the integer's bytes are written in the native order of the CPU (little-endian for supported platforms). For GV_INT32 4 bytes are written, for GV_INT64 8 bytes are written.
- a string: all the string's bytes up to, but not including, the NULL.

Returns:

The bytes written.

int obj.Pos([new_position]);

Gets or sets the current file position.

Arguments:

[optional] new_position - A new file position.

Returns:

The current file position.

void obj.Close();

Closes a file.

Returns:

Nothing.

void Sleep(ms);

Pauses the current thread.

Arguments:

ms - The number of milliseconds to pause for.

Returns:

Nothing.

int64 ClockTick();

Returns the current clock tick.

Arguments:

None.

Returns:

A 64bit clock time from an unknown epoch, in milliseconds. Useful for timing things.

datetime Now();

Returns the current date time.

Arguments:

None.

Returns:

A GDateTime variant set to the current date and time.

int obj.Year;

Sets or gets the year part of a date/time object.

int obj.Month;

Sets or gets the month part of a date/time object.

int obj.Day;

Sets or gets the day part of a date/time object.

int obj.Hour;

Sets or gets the hour part of a date/time object.

int obj.Minute;

Sets or gets the minute part of a date/time object.

int obj.Second;

Sets or gets the second part of a date/time object.

int obj.Milli;

Sets or gets the millisecond part of a date/time object.

int64 obj.Timestamp;

Sets or gets the int64 version of a date/time object. This is compatible with a range of operating system APIs.

string obj.Date;

Sets or gets the date part of the object. Typically this is in the form 'day/month/year' in the current locale of the operating system.

string obj.Time;

Sets or gets the time part of the object. Typically this is in the form 'hour:minute:second' in the current locale of the operating system.

string obj.DateTime;

Sets or gets both the date and time parts of the object as a string.

object CreateSurface(x, y[, pixel_type]);

Creates a bitmap in memory with the specified dimensions and bit depth or colour space.

Arguments:

x - The width in pixels.
y - The height in pixels.
[optional] pixel_type - The type of pixel.
The default will be the same as the screen if you don't specify it at all. Otherwise you can use:
- an integer: which specifies the bits per pixel.
  The exact colour space will be determined to be one of the System##BitColourSpace values.
- a string: which specifies the exact colour space.
  Possible values are taken from the LColourSpace enum in Lgi but in string form, ie:
  - "CsIndex8" - Creates a 8 bit indexed image with a palette.
  - "CsRgb16" - An rgb image with 5 red, 6 green and 5 blue bits per pixel.
  - "CsRgb24" - An rgb image with 8 bits per component.
  - "CsRgba32" - An rgba image with 8 bits per component.
  Some special values are available for the supported system colour spaces:
  - "System15BitColourSpace" - The system supported 15 bits/pixel colour space.
  - "System16BitColourSpace" - The system supported 16 bits/pixel colour space.
  - "System24BitColourSpace" - The system supported 24 bits/pixel colour space.
  - "System32BitColourSpace" - The system supported 32 bits/pixel colour space.
  Not every system will support all colour spaces. Unsupported colour space images can't be placed on the screen directly. They have to be converted to a compatible colour space first.

Returns:

A memory bitmap object or NULL on failure.

Example:

c = CreateBitmap(320, 240);
Print(c.Type(), ": ", c.x, ", ", c.y, ", ", c.Bits, ", ", c.ColourSpace, "\n");

Surface: 320, 240, 32, 1211639896

The colourspace '1211639896' decimal is '0x48382858' in hex. Each byte is a component description, the high nibble is the colour type (defined in Lgi as the GComponentType enum), and the lower nibble is the number of bits (and zero = 16 bits).

string ColourSpaceToString(intColourSpace);

Converts a LColourSpace integer to a string.

int StringToColourSpace(stringColourSpace);

Converts a string colour space representation to a LColourSpace.

Returns:

Non zero LColourSpace entry on success, or CsNone on error (value 0).

int obj.X;

The width of the image in pixels (read only).

int obj.Y;

The height of the image in pixels (read only).

int obj.Bits;

The number of bits per pixel (read only).

colour_space obj.ColourSpace;

The colour space of the image (read only). This is a integer value that maps to a LColourSpace enum.

list obj.Palette;

The palette of the image. Use array indexing to set or get the individual palette entries.

bool obj.Load(filename);

Loads an image from a file. Only filters that are compiled into the executable are supported.

Arguments:

filename - The path to the image file.

Returns:

TRUE if the file was loaded.

bool obj.Save(filename);

Soads an image to a file. Only filters that are compiled into the executable are supported.

Arguments:

filename - The path to the image file.

Returns:

TRUE if the file was saved.

view LoadDialog(parent_wnd, dialog_id);

Loads a dialog from a resource file.

Arguments:

parent_wnd - The handle of the parent window.
dialog_id - The id of the dialog from "resdefs.h".

Returns:

A view object.

string MessageDlg(parent_wnd, msg, title, btns);

Displays a model alert message.

Arguments:

parent_wnd - The handle of the parent window.
msg - A message above the editbox.
[optional] title - The title of the dialog.
[optional] btns - Integer mask of buttons:
- MB_OK = 0
- MB_OKCANCEL = 1
- MB_ABORTRETRYIGNORE = 2
- MB_YESNOCANCEL = 3
- MB_YESNO = 4
- MB_RETRYCANCEL = 5
- MB_CANCELTRYCONTINUE = 6

Returns:

Integer representing the button pressed:
- IDOK = 1
- IDCANCEL = 2
- IDABORT = 3
- IDRETRY = 4
- IDIGNORE = 5
- IDYES = 6
- IDNO = 7
- IDCLOSE = 8
- IDHELP = 9
- IDTRYAGAIN = 10
- IDCONTINUE = 11
- IDTIMEOUT = 32000

void GetInputDlg(parent_wnd, initial_value, msg, title, is_password, callback);

Asks the user for input using a dialog.

Arguments:

parent_wnd - The handle of the parent window.
initial_value - The initial value in the editbox field.
msg - A message above the editbox.
title - The title of the dialog.
is_password - True if you want the editbox content obsured by dot characters.
callback - The function name to call with the dialog result code.

Returns: Nothing.

function MyCallback(str)
{
    Print("String entered is: '" + str + "'\n");
}

GetInputDlg(app, "SomeText", "Enter some text:", "InputTest", false, "MyCallback");

object GetViewById(parent, id);

Gets the child view by it's id.

Arguments:

parent - The parent window.
id - The id of the child.

Returns:

A view reference, or NULL if not found.

int obj.Handle;

The operating system handle for the view (read only).

int obj.Id;

The control ID for the view.

string obj.Name;

The textual name assocaited with the view.

int64 obj.Value;

The numerical value assocaited with the view.

bool obj.Enabled;

This sets or gets the enabled/disable state of the view.

colour obj.Foreground;

Gets or sets the CSS foreground colour for the view.

colour obj.Background;

Gets or sets the CSS background colour for the view.

string Execute(executable[, arguments]);

Executes a process and waits for it to finish.

Arguments:

executable - The path to the executable.
[optional] arguments - Arguments to pass to the executable.

Returns:

A string containing what the process wrote to stdout.

bool System(executable[, arguments]);

Executes a process and doesn't wait for it to finish.

Arguments:

executable - The path to the executable.
[optional] arguments - Arguments to pass to the executable.

Returns:

TRUE if the process was started.

string OsName();

Returns the current OS name:

Win32
Win64
MacOSX
Linux
Haiku

Example:

Print(OsName(), "\n");

Win64

list OsVersion();

Returns the current OS version as 3 integers in a list.

Returns: The OS version:

Windows XP {5, 1, 0}
Windows Vista {6, 0, 0}
Windows 7 {6, 1, 0}
Windows 8 {6, 2, 0}
Mac OS X 10.8.2 {10, 8, 2}
Ubuntu 13.04 {3, 8, 8} (i.e. the kernel version)

Example:

Print(OsVersion(), "\n");

{6, 1, 0}

string obj.Type;

Gets the type of the object as a string.

Returns:

A string.

Example:

c = New("list");
Print(c.Type(), "\n");

List

int obj.Length;

Gets the length of an object. The meaning of that depends on the context of what type it is:

List or HashTable: number of objects in the container.
String: The number of bytes.
File: Reading the value gives the length of the file in bytes. Writing to the value sets the file's size.
Bitmap: Number of pixels.
View: Number of child views.

Returns:

A integer or NULL if not applicable.

Example:

c = "This is a string.";
Print(c.Length, "\n");

c = New("list");
c.Add(123);
c.Add(456);
Print(c.Length, "\n");

17
2

Windows XP	{5, 1, 0}
Windows Vista	{6, 0, 0}
Windows 7	{6, 1, 0}
Windows 8	{6, 2, 0}
Mac OS X 10.8.2	{10, 8, 2}
Ubuntu 13.04	{3, 8, 8} (i.e. the kernel version)