In this section the 'type' _Variant will match any appropriate type. The 'type'_Array will match any appropriate array type ( users cannot use these 'types' for their own routines ).
Array
_Array Array(Number len1, Number len2 = 0, Number len3 = 0)
This creates an initialised array for an open array datum. The routine can handle up to 3 open dimensions. The lenn values apply just to the open dimensions. The low index will always be 1. The type of the array is determined by the type of the datum to which the array is being assigned. The initialisation of the elements is based on the default expressions defined ( or implicit ) for the base type.
lenn - This is the length for the n'th open dimension.
ArrayLow, ArrayHigh
Number ArrayLow(_Array array, Number dim = 1) Number ArrayHigh(_Array array, Number dim = 1)
These will return the low and high index limits for the specified dimension of an array. These will only work for numeric indexes; but as open array indexes are always numeric there should be no problem.
If the length of the dimension is zero then Null will be returned.
array - This is any array datum.
dim - This is the dimension, counting from 1. If omitted the fisrt dimension will be reported.s
Char
Text Char(Number code)
This will return one character long string containing the character corresponding to the specified Unicode value.
code - This is the Unicode value to convert into a character.
CharCode
Number CharCode(Text str)
This will return the Unicode value for the first character in the text.
str - This is the text with the character to convert to Unicode.
ExtractImage
TImage ExtractImage(Ref TCanvas canvas, Number x = 0, Number y = 0, Number width = Null, Number height = Null)
This will extract an image from a canvas. Either the whole image or a selected rectangular portion may be extracted.
canvas - This is the canvas from which to extract the image.
x - This is the x coordinate of the region to extract.
y - This is the y coordinate of the region to extract.
width - This is the width in pixels of the region to extract. If the value is Null then the image will be extracted up to the right edge.
height - This is the height in pixels of the region to extract. If this is Null then the image will be extracted down to the bottom edge.
Format
Text Format(_Variant value, Text format = Null )
This will format a value of one of the basic types to produce a Text value.
value - This is the value to be formatted.
format - This is the optional format specification string to use - if Null then a default format will be used. Details of the format codes are covered in the Format Specifiers section.
Len
Number Len(Text text)
This will return the length of a Text string.
text - String to get the length of.
ReadArray
_Array ReadArray(Text datafile, Text logfile = Null)
This will read in an external data file. The file should contain a list of values that conform to the syntax of the GraRLS language. Each value must be of the same type as the element type of the array to which the values are assigned. Each value must be terminated with a semicolon.
datafile - This the name of the file to read.
logfile - This the name of a file to write any parsing error messages to.
ReadData
_Array ReadData(Text datafile, Text fmtfile = Null, Text logfile = Null)
This will read in an external data file. Currently CSV ( comma separated values ) files are supported. The routine will return an array. The data type of the created array will match the type of the datum to which the result is assigned.
datafile - This the name of the file to read.
fmtfile - This the name of a format file that tells the routine how to parse the data.
logfile - This the name of a file to write any parsing error messages to.
ReadImage
TImage ReadImage(Text filename)
This will read an image from a file. Current BMP, PNG and PAT files are supported.
filename - This is the name of the file containing the image. The extension of the file name will indicate the type of image file to read.
ReadValue
_Variant ReadValue(Text datafile, Text logfile = Null)
This will read in an external data file. The data will be formatted in the syntax of the GraRLS language itself. The routine will return a single value; this value may be a structure or an array. The type value must match the type of the variable to which it is being assigned.
If the value is an array the value must contain the square brackets. This makes it awkward to append new entries for the array. If this is an issue then use the ReadArray function instead.
datafile - This the name of the file to read.
logfile - This the name of a file to write any parsing error messages to.
SubImage
TImage SubImage(Const Ref TImage image, Number x = 0, Number y = 0, Number width = Null, Number height = Null)
This will extract a section of an image.
image - This is the existing image from which to extract the subimage.
x - This is the x coordinate of the region to extract.
y - This is the y coordinate of the region to extract.
width - This is the width in pixels of the region to extract. If the value is Null then the image will be extracted up to the right edge.
height - This is the height in pixels of the region to extract. If this is Null then the image will be extracted down to the bottom edge.
TextSize
Point TextSize(Text text, Const Ref TFont font, Number width)
This will return the size in pixels that a piece of text will take up on the display if written with the given font. The x and y values in the point will contain the width and height of the text.
text - This is the text to measure.
font - This is the font to use.
width - This is the width of a block to which the text should be limited ( i.e. the lines will start wrapping ).
ToNumber
Number ToNumber(Text text)
This will parse a string of text that represent a number and return that number. Both camma and dot will be interpreted as a decimal point. There should be no thousands separators.
text - This is the text to parse.