Miscellaneous Functions

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)
Number ArrayHigh(_Array array, Number dim)

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, to test.

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.

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.

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