# 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

ReadTextFile
WriteTextFile
SelectFiles
SelectFolder
ListFiles
DeleteFile
PathExists
PathJoin
PathSep

Sleep
ClockTick
Now

CreateSurface

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.

#### 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.

#### list SelectFiles(parent_wnd[, file_types[, initial_dir[, multi_select[, save_as]]]]);

Shows a file select dialog.
Arguments:

- parent_wnd - the handle of the parent window.
- [optional] file_types - the types of files to select, e.g. "*.gif;*.png;*.jpg".
- [optional] initial_dir - the initial folder to select from.
- [optional] multi_select - TRUE if multiple file can be selected.
- [optional] save_as - TRUE if dialog should be for saving a file.

Returns:

- list of filenames.

Example:

    files = SelectFiles(Parent, "*.png", "C:\\Users\\matthew\\Desktop", 1);
    if (files)
    {
        for (i=0; i<files.Length; i++)
        {
            Print(files[i], "\n");
        }
    }

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

#### list SelectFolder(parent_wnd[, initial_dir]);

Shows a folder select dialog.
Arguments:

- parent_wnd - the handle of the parent window.
- [optional] initial_dir - the initial folder to select from.

Returns:

- String FolderPath.

#### 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.
Example:

    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.
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 GColourSpace 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).

#### 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 GColourSpace 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

#### string GetInputDlg(parent_wnd, initial_value, msg, title, is_password);

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.

Returns:

- A string containing what the user entered.

#### 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: The length of the file in bytes.
- 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