Contents

Commands and keywords

Apart from its use in the for..next construct, the to keyword is used to indicate a return variable in association with the following commands :

  Back to Contents

Overview

General

A CompoScript file is a simple text file (created using your favourite text editor) that must begin with the line :

#CompoScript

Blank lines and lines for which the first non-space character is a hash character (#) are ignored by the interpreter. Thus the # is used to introduce comments.

Compo is case-insensitive with regard to commands, keywords and variable names.

Although not necessary, it is recommended that you space-separate the various elements that make up a line of code (commands, keywords, variable names, literals, operators), as this can improve legibility. The exception to this are the options in multi-line commands (discussed shortly). Indenting may also be used as a matter of style and to improve readability, though is not necessary.

Commands

CompoScript provides over 50 commands. Parameters (if present) may be literals or variables and are separated by one or more spaces. You cannot have more than one command per line of code.

There are two command structures : single-line and multi-line. The latter have the general form :

command
{
 options
}

Some general points concerning options :

Note that this structure is distinct from multi-line program flow structures, such as :

repeat
 commands
until condition

where { and } characters are not required.

Variables

Two types of variables are available : strings and integers. This is true for user defined variables, and for the CompoScript defined dot variables. Real variables (fractional numbers) are not possible, though there are a few instances where reals are required (these pseudo-reals are discussed shortly).

Unlike some languages (such as BASIC) CompoScript does not enforce any particular naming style on different types of variables, however in general you should stick to using upper and lower case letters and numbers. Those users familiar with BASIC may like to include a terminal $ character in string variable names, though this is not necessary.

CompoScript variables are all global, there is no concept of local variables. Indeed, as they are actually system variables, they can even be accessed by external routines, run from within CompoScript, as well as persisting between scripts.

See the description of the let command for details of assigning values to variables, and of arithmetic and string operators.

Hexadecimal numbers are denoted by prefixing them with an &.

As mentioned above, some command parameters accept pseudo-reals, and although it is possible to specify these parameters using variables, you should note that these variables are in fact strings, and so arithmetic operations upon them is not possible.

Example:

let textsize = 12.5
maketext "line1"
{
 ---
 Size: <textsize>
 ---
}

is okay, but you would not be able to do (immediately before the maketext command) :

let textsize = textsize * 2

because textsize is a string variable.

NB. There is a trap for the unwary here :

let textsize = textsize + 2

will work – though probably not as intended. Because textsize is a string variable, the '2' would be appended, and textsize would be '12.52', ie still a valid pseudo-real quantity (though in this particular example, there would be no apparent difference, as maketext's Size: parameter is rounded to the nearest 1/16th of a point).

let textsize = textsize + 2.5

would produce nonsense, as textsize would end up as '12.52.5' !

Commands that make use of pseudo-reals are : export (various parameters), maketext (Size:), scaleby and shadow (3D:)

Literal strings do not need to be enclosed in quotes, even if they contain spaces, though it is strongly recommended that you do quote such strings, both for clarity and to ensure that CompoScript interprets it as you intend.

Consider the following command :

let foobar = foo

The content (and type) of foobar will depend on whether foo is defined or not. If it's not, you'll get a string variable (the characters 'foo'). If it's defined, eg if the above line was preceded by :

let foo = 12

then foobar will become an integer variable, = 12.

Enclosing something in angle brackets forces CompoScript to try to turn it into a variable (if it fails you'll get a string variable containing the whole lot). Enclosing something in quotes forces it to treat it all as a string unless it is angle bracketed.

Using string variables takes a little getting used to but are very neat once you're familiar with them.

Example:

let first = "Rob "
let last = "Davison"
let fullname$ = "<first><last> wrote this."

fullname$ is now the string "Rob Davison wrote this."

CompoScript is a loosely typed language. That is, there is no hard distinction between integers and strings, and keywords even.

Any string variable that contains only digits can be used in arithmetic expressions. Conversely, integer variables can be directly expressed in a string. No need for BASIC's VAL() and STR$() functions.

Example:

let stringnumber = "21"
let answer = stringnumber * 2
report "Life, etc equals <answer>"

Example:

let foo = 1
let foobar = foo
let foobar = <foo>
let foobar = "<foo>"
let foobar = "foo"

In the first three cases, foobar is a number (1). Only in the last case is it a string ("foo").

Conditional operators

CompoScript allows only simple conditional tests, ie a single comparison, using one of the following operators :

Compound conditions (using AND, OR, etc) are not possible.

As infered above : false = 0, and true = 1.

See the let command for details of other types of operators.

The current object

Some of CompoScript's commands can only operate on a single object (referred to as the current object) whereas others will operate on all selected objects, en masse.

Compo and CompoScript both use the concept of primary selected object (PSO) to refer to the object within a multiple selection that will be affected by commands that can operate only on a single object. The PSO is also referred to as the single object focus.

The current object can refer to one of three things :

• A single selected object.
• The primary selected object (PSO) of a multiple selection.
• Each selected object, in turn, of a multiple selection (when in a doto selection block of code).

The primary selected object is determined by how a selection is made or altered (see the select command for details) :

• From Compo's user interface, using Ctrl-A to select all objects (or select all in CompoScript) results in the top-most object being the PSO.
• In the user interface, dragging the pointer to select a group of objects will result in the back-most object being the PSO.
• When using ADJUST to add to a selection then that most recently added object will become the PSO, whereas using select + xxx in CompoScript causes no change in the PSO.
• When using ADJUST to remove any object from a selection then the back-most object becomes the PSO, whereas when using select - xxx in CompoScript, this only occurs if it was the PSO that was removed (otherwise the PSO remains unchanged).

In CompoScript, there is only one command that operates on all objects within a selection : delete.

The following commands affect just the current object : redraw, flipimage, makecopy, move, moveto, moveby, rotateto, scaleto, scaleby, trim, export, maketext (modify), makemask, loadmask, savemask, processmask, shadow, readpixel, writepixel.

  Back to Contents

Dot variables

In addition to user defined variables, CompoScript makes available to the user a number of its variables. These are distinguished by being prefixed with a fullstop, and are thus referred to as dot variables.

  Back to Contents

Program flow commands

do
breakdo
enddo

Repeat a series of instructions a number of times. ***Nesting limit 30 deep***

Example:

let loops = 5
do loops
...
enddo

Example:

do 100
...
if a = <premature_exit> then
 breakdo
endif
...
enddo

  Back to Contents

proc
defproc
endproc

Defproc and endproc are used to define a procedure – a self contained section of code that can be called by name.

Proc is used to call a procedure. ***Nesting limit 30 deep***

Procedures in CompoScript neither take parameters nor return results. There is no concept of local variables. Note also that defproc is one word, and that there should be a space between the proc and defproc keywords and the procedure's name.

You must use the end keyword to separate the main section of code from any procedure definitions that follow.

Example:

proc caption_object
...
end

defproc caption_object
...
endproc

Example:

let fred = 2
case fred of
 when 1 proc fred_one
 when 2 proc fred_two
 otherwise proc fred_common
endcase
end

defproc fred_one
 let jim$ = "fred is one"
endproc

defproc fred_two
 let jim$ = "fred is two"
endproc

defproc fred_common
 let jim$ = "fred is <fred>"
endproc

  Back to Contents

case
when
otherwise
endcase

Case structure. Cannot be nested and only one command (which can be a procedure call) per when allowed.

Example:

case x of
 when 1 proc fred
 when 2 proc bert
 when 3 proc jim
 otherwise proc unknown
endcase

  Back to Contents

for..to..step
next

For..next loop. ***Nesting limit 30 deep***

Syntax:

for <loopcounter> = <startval> to <endval> step <inc>

Where:
<loopcounter> (integer, var) – used to control cycles around the loop.
<startval>, <endval> (integer) – the initial and final values for the loop counter.
<inc> (integer) – the step value, ie the increment that is applied to the loop counter on each cycle of the loop. The step value can be positive or negative.

Example:

for i = 60 to 0 step -2
...
next

  Back to Contents

if..then
elseif..then
else
endif

Multi-line enhanced if..then construct.

NB. Must be multi-line, single line form is not supported.
NB. Immediate nesting (within the same procedure) is not yet supported (it's there, but not reliable).

Example:

let fred = 12

if fred = 2 then
 proc fred_two
elseif fred = 1 then
 proc fred_one
else
 proc fred_common
endif

The multi-line if..elseif.. structure is similar to the case structure, and indeed the previous example could be coded using such a structure. The difference between the two is that a case structure tests for different values of a single variable, whereas each if and elseif can test a different variable. To a limited extent this can be used to compensate for the lack of compound conditions (the use of AND).

Example:

if fred = 1 then
 # here: fred is 1
elseif jim = 2 then
 # here: fred<>1 AND jim=2
elseif sheila = 3 then
 # here: fred<>1 AND jim<>2 AND sheila=3
else
 # here: none of the above were true
endif

  Back to Contents

repeat
until

Repeat..until loop. ***Nesting limit 30 deep***

Example:

repeat
...
until x = 5

  Back to Contents

let

Declares and assigns a value to a variable (including any dot variables that are writable).

Syntax:

let <variable> <assignment operator> <expression>

ie 3 space separated elements follow the let command (the spaces are necessary).

Where:
<assignment operator> is one of : = | += | -= | *= | /=  (see below).
<expression> can be a single variable, a literal value, or a compound expression. In the latter case spaces may be included to separate the various components, if desired.

Examples:

let x = 12
let y = x + 3
let z = 4*5

For integers, the four standard arithmetic operators are available (for use within the <expression> element) :

add (+), subtract (-), multiply (*), divide (/)

Along with their related assignment operators :

increment by (+=), decrement by (-=), multiply assign (*=), divide assign (/=)

For string variables, there is just the one operator :

concatenate (+)

Along with its related assignment operator :

append (+=)

Examples:

let x += 3
let y *= <multiple>
let .leafname += "/gif"

Pseudo arrays

Although arrays are not possible in CompoScript, they can be approximated.

Syntax:

let foobar<var> = <something>

Example:

for loop = 1 to 10
 let myvariable<loop> = a*loop+c
next

This would assign values to 10 variables, named myvariable1, myvariable2, etc.

Interpolation

There is a special form of the let command that provides a way of obtaining non-integer step sizes within a for..next loop. This is useful for smoothly interpolating things like opacities over a fixed number of frames in an animation.

Syntax:

let <value> =(interpolate) <type> <start> to <end> <step> of <max>

Where:
<value> (pseudo-real, var) – the interpolated result.
<type> is one of : Linear | Gamma_<value> | Bezier_<value>_<value>
Flat is a synonym for Linear.
<start>, <end> (integer) – the range from which to obtain the interpolated value.
<step>, <max> (integer) – the required step and the total number of steps.

This maps a position (<step>) into one range (1 to <max>) against another range (<start> to <end>), using FP to return the exact interval. The mapping can be linear, a gamma scale or even a bezier-like S-curve.

Note that the =(interpolate) element is not optional, and should be written as is, brackets and all.

Example:

let frames = 30
for loop = 1 to frames
 # move 'opacity' from 0 and 255 in 'frames' equally sized steps :
 let opacity =(interpolate) flat 0 to 255 loop of frames
 # a more interesting alternative :
 let opacity =(interpolate) gamma_1.6 0 to 255 loop of frames
next

  Back to Contents

end

This ends the program. It need not be physically at the end of the code. If the code contains any procedure definitions, then this keyword must occur after the main code and before the procedure definitions.

  Back to Contents

stop

Halt script execution prematurely. Unlike the end keyword, stop may be used inside if..then constructs without generating an error.

Example:

if .blendmask = 0 then
 # object has no blend mask
 stop
endif

  Back to Contents

OS access commands

star

Passes a command to the standard RISC OS command line interpreter (OSCLI).

Example:

star "Filer_OpenDir <fred>"

The star command can be used to run external programs to process an image held in Compo.

Example:

#CompoScript
select first
star "WimpTask <.composcript$dir>.myprogram <.selected.imagebase>"
redraw

This simple CompoScript selects the first image on the canvas and then runs a program (expected in the same directory as the script), with the base address of the image data passed on the command line.

Note the use of the dot variables .composcript$dir to obtain the path of the current script, and .selected.imagebase to pass the base address of the currently selected image data.

Also of use are the .mask.xxx variables which, when non-zero, contain offsets from .selected.imagebase to the various mask data structures.

Great care should be taken in the writing and/or use of such programs
lest they overwrite something they shouldn't.

You can download an archive containing some simple BASIC and BASIC/ARM programs demonstrating an external utility modifying an image in this way via CompoScript.

It is not possible to call other CompoScript files from within a CompoScript.

  Back to Contents

definemenu

Define a RISC OS menu.

Currently only one menu structure is held - you can't define more than one menu concurrently and then choose which one to open. This shouldn't be a restriction, as RISC OS can only have one menu open at once – you simply define a menu immediately before you want to open it.

Syntax:

definemenu <title>
{
 list of items
}

Where:
<title> (string) – the text to be used as the menu's title, and the identifier to be used to refer to this menu, when you later wish to display it, using the openmenu command.

  Back to Contents

openmenu

Popup the named menu, that was previously created using definemenu.

Syntax:

openmenu <title> to <result>

Where:
<title> (string) – the menu identifier, as specified using definemenu.
<result> (string var, return) – contains the text of the menuitem that the user selected.

Although there can only be one menu definition at any one time, the title needs to be specified – both for clarity and also to allow for a special case : a font menu.

Example:

openmenu "Fonts" to result Default "Trinity.Medium"

This also illustrates the use of the default option to pre-tick a menu entry.

  Back to Contents

input

This provides a means of getting keyboard input from the user.

Syntax:

input <default> to <result> <prompt>

Where:
<default> (string) – The default text that will be returned by just pressing Return. Use "" for no default text.
<result> (string var, return) – returns the user's input.
<prompt> (string) – the message prompting the user.

Example:

input "Purple" to colour "Enter your favourite colour"

  Back to Contents

prompt

Pop up a dialog box containing 3 buttons and some prompt text. As well as the prompt text, the text for each button needs to be specified.

Example:

prompt to result
{
 Message:Do you really want to do this pal?
 Button1:Proceed
 Button2:Crazy!
 Button3:NoWay
}

After this call, result holds the text of the button pressed.

  Back to Contents

report

Report a message in a popup window. An optional second parameter specifies a delay time before automatically closing the window.

Syntax:

report <message> (<timeout>)

Where:
<message> (string) – the message to be reported.
<timeout> (integer) – a time delay before closing the window (centiseconds). If omitted, a default value of 500 (5 seconds) will be used.

Example:

if .selected = -1 then
 report "There is no selected object"
 stop
endif

  Back to Contents

dragload

This command opens a window which asks for a file or directory to be dropped onto it.

Syntax:

dragload <fileicon> <message> to <filename>

Where:
<fileicon> (string) – the name of the icon to represent the type of file wanted.
<message> (string) – the message to be displayed.
<filename> (string var, return) – the full pathname of the file/directory the user dropped onto this window. It is "" if no file is dropped.

Here as elsewhere, the to keyword implies a return variable, not a destination.

Note that specifying the sprite for the filetype you want, doesn't mean that only that filetype is accepted. You must therefore check that the expected type has been dropped.

Following a dragload command, several dot variables are set.

In particular, you should use .dragload.there to establish that it is in fact a file (or a directory), and before using any of the .dragload.leafname, .dragload.filetype or .dragload.length variables. Also, .dragload.length doesn't make sense in the case of directories.

Examples:

dragload file_aff "Drag a Draw file here" to pathname$
dragload directory "Drop a directory here" to pathname$

  Back to Contents

dragsave

This command is used to display a SaveAs box with a user supplied message. No data is actually saved by this command, instead it allows the user to choose where something is to be saved.

Syntax:

dragsave <fileicon> <leafname> <message> to <filename>

Where:
<fileicon> (string) – the name of the icon to be used in the window.
<leafname> (string) – the default leafname put into the SaveAs window.
<message> (string) – the message to be displayed.
<filename> (string var, return) – the full pathname after the user has dragged the icon to a directory, or a null string if the window was closed without performing a drag operation.

Following a dragsave command, several dot variables are set.

You can use .dragsave.there to establish whether a file or directory with the proposed name already exists, and certainly before using any of the .dragsave.leafname, .dragsave.filetype or .dragsave.length variables, which will all refer to this pre-existing object. Thus they can be used to avoid overwriting something that already exists.

Example:

dragsave file_ff9 abc "Drag the icon to save" to where

  Back to Contents

scandirectory

Returns the names of files in a specified directory.

Syntax:

scandirectory <dirname> to <filename>

Where:
<dirname> (string) – the pathname of the directory to be scanned.
<filename> (string var, return) – the full pathname, or null ("") if no more.

It should be used in a loop, to read the names one at a time. It is not possible to scan more than one directory concurrently.

Following a scandirectory command, several dot variables are set.

In particular, you should use .directoryscan.there to establish whether an object is a file or a directory, before using any of the .directoryscan.leafname, .directoryscan.filetype or .directoryscan.length variables. Also, .directoryscan.length doesn't make sense in the case of directories.

Example:

repeat
 scandirectory "ADFS::4.$.Images" to result
 if result <> "" then
  report "found file <result>"
 endif
until result = ""

  Back to Contents

fileinfo

This provides information about a file.

Syntax:

fileinfo <filename>

Where:
<filename> (string) – the full pathname.

Following a fileinfo command, several dot variables are set.

In particular, you should use .fileinfo.there to establish that it is in fact a file, and before using either of the .fileinfo.filetype or .fileinfo.length variables. Unlike with the commands that have similar dot variables (dragload, dragsave and scandirectory) if the object is a directory, .fileinfo.filetype will be invalid and thus cannot be used to differentiate between normal and application directories.

  Back to Contents

colourpicker

Opens a colour picker window, allowing the user to choose a colour.

Syntax:

colourpicker <type> <title> <default> to <colour>

Where:
<type> is one of : Acorn | Compo
<title> (string) – the popup window's title.
<default> (integer) – the initial colour shown when the window is opened (&rrggbb).
<colour> (integer var, return) – the colour value chosen (&rrggbb).

  Back to Contents

slider

Opens a window containing a draggable slider, allowing the user to enter a numeric value (in the range 0-255).

Syntax:

slider <title> <default> to <value>

Where:
<title> (string) – the popup window's title.
<default> (integer) – the initial value shown when the window is opened (0-255).
<value> (integer var, return) – the value shown when the window was closed.

Example:

slider "Intensity:" 128 to result

  Back to Contents

Compo specific commands

makecanvas

Used to create a Compo canvas. It takes two compulsory and one optional parameters.

Syntax:

makecanvas <xsize> <ysize> (<colour>)

Where:
<xsize>, <ysize> (integer) – the width and height of the canvas (pixels).
<colour> (integer) – 24-bit colour (&rrggbb).

If a canvas already exists, it will be resized (and coloured) as specified. Existing objects will be left intact.

Example:

makecanvas 640 480 0

creates a black canvas of 640 x 480 pixels.

  Back to Contents

loadcompo

Loads a Compo canvas.

Example:

loadcompo "ADFS::4.Images.Scene"

  Back to Contents

savecompo

Saves a Compo canvas.

Example:

savecompo "ADFS::4.Images.Scene"

  Back to Contents

nib

This controls whether the screen is updated.

Syntax:

nib <option>

Where:
<option> is one of : Up | Down | Nobox

nib up
Disable screen updates. Useful when generating animations, to stop redraws until the changes to an object are complete.

nib down
Update the screen and allow subsequent operations to update the screen immediately.

nib nobox
After this command has been issued, selecting an object won't place the dotted gui selection box around it. It'll just be invisibly selected. This is reset automatically at the start of a script.

  Back to Contents

redraw

Cause a redraw of the specified region of the current object. If no parameters are specified, the entire object is redrawn. If no object is selected it regenerates the given area of the whole canvas.

Typically called after processing an image with writepixel or calling an external program that alters it.

Syntax:

redraw (<x> <y> <width> <height>)

Where:
<x>, <y> (integer) – the coordinates of the bottom-left corner of the region to be redrawn.
<width>, <height> (integer) – the width and height of the region to be redrawn.

  Back to Contents

select

Compo specific commands mostly reference a selected object and this command is used to select one or more objects.

Syntax:

select (+|-) <object>

Where:
<object> is one of : Canvas | None | All | First | Last | Previous | Next | "Name" | <integer>

select + <object> adds to the current selection (the single object focus remains unchanged), and
select - <object> removes from the current selection (if the removed object had the single object focus this is transfered to the back-most object in the remainder of the selection).

NB. Any vector layer objects (and that includes AOIs) will always be above any bitmap objects (in the stacking order). Thus using select last to select a just created bitmap object will only work as intended if there are no vector layer objects (or AOIs) on the canvas. If there are any objects on the vector layer then select last will always select the topmost of those.

As you can see, this command takes many forms, most of which should be self-explanatory ...

select Canvas
Selects the canvas as a whole, deselecting all other objects.

select None
A synonym for the above command - deselects any selected objects. The selection focus (for exporting) is moved to the canvas.

select All
Selects all of the objects on the canvas. The single object focus is the last (top-most) object. Most commonly used before a delete command.

select (+|-) First
Selects the first (back-most) object. If there are no objects in the composition then the canvas is selected (and no error returned).

select (+|-) Last
Selects the last (top-most) object. If there are no objects in the composition then the canvas is selected (and no error returned).

select (+|-) Previous
Selects the previous object (moving towards the back of the depth stack). If the first object in the composition is already selected this command does nothing.

select (+|-) Next
Selects the next object (moving towards the front of the depth stack). If the last object in the composition is already selected this command does nothing.

select (+|-) "Name"
Selects an object by leafname. The search is case sensitive and if more than one object with the same leafname exists this command will only be able to select the first (back-most) one. If the referenced object cannot be found an error is returned and the CompoScript halted.

select (+|-) <integer>
Selects an object by depth stacking. 1 being the back-most object.

Example:

# CompoScript
# Author: Rob Davison
# Test only...
# Move through all the objects, appending '/gif' to their names
select first
let lastselected = 0
repeat
 let lastselected = <.selected>
 let .leafname += "/gif"
 select next
until .selected = <lastselected>
end

A more succinct way of achieving that would be :

# CompoScript
select all
doto selection
{
 let .leafname += "/gif"
}
end

Note that in addition to .selected, there are a whole range of dot variables relevant to the currently selected object.

  Back to Contents

doto

Apply a series of commands to the object(s) referenced.

Syntax:

doto (selection|"name")
{
 commands
}

Example:

doto "fred"
{
 proc do_something
 proc do_something_else
}

Example:

doto selection
{
 proc do_something_else_entirely
 proc do_something_different
}

Errors:
   Nothing selected for doto command
   Object passed with doto command could not be found
   Doto commands cannot be nested.
   Select command may not be used inside a "doto"
   Delete command may not be used inside a "doto" :** or exit?

  Back to Contents

delete

Deletes all currently selected objects. There are no parameters.

  Back to Contents

flipimage

Produces a left-right or top-bottom mirror image of the current object.

Syntax:

flipimage <action>

Where:
<action> is either : horizontal (left-right) or vertical (top-bottom).

  Back to Contents

makecopy

Copies the current object, including its masks and other attributes (shadow, opacity, etc.).

Example:

makecopy "fred"

Makes a copy of the current object and calls it 'fred'.

  Back to Contents

rename

Renames an object.

Example:

rename "fred" "bert"

Renames the object 'fred' as 'bert'.

  Back to Contents

move

Moves the current object within the stacking order of overlapping objects.

Syntax:

move <action>

Where:
<action> is one of : Front | Back | Forwards | Backwards

  Back to Contents

moveto

Moves the current object.

Syntax:

moveto <x> <y> (middle)

Where:
<x> is one of : Centre | Left | Right | <integer>
<y> is one of : Centre | Top | Bottom | <integer>

Left will place the left edge of the object against the left edge of the canvas. Right will place the right edge of the object against the right edge of the canvas. Similarly for Top and Bottom.

However if the optional third parameter middle is used, then it is the centre of the object that is placed against the left, right, etc edge. If numeric values are given for x or y, then the centre of the object is placed at that coordinate.

Examples:

moveto centre top
moveto 200 300
moveto 500 bottom
moveto 200 300 middle
moveto left 200 middle

  Back to Contents

moveby

Move the current object relative to its current position.

Syntax:

moveby <dx> <dy>

Where:
<dx> (number) – the number of pixels to move by horizontally. Negative moves left.
<dy> (number) – the number of pixels to move by vertically. Negative moves down.

Example:

moveby 300 -50

  Back to Contents

rotateto

Rotates the current object to the specified angle (degrees).

Example:

rotateto 30

  Back to Contents

scaleto

Scales the current object to a specific size, optionally keeping the aspect ratio of the image unchanged.

Syntax:

scaleto <width> <height> (AspectLock)

Where:
<width>, <height> (integer) – the new width and height (pixels).

Examples:

scaleto 500 650
scaleto 500 200 AspectLock

  Back to Contents

scaleby

Scales the current object by the specified factor(s).

Syntax:

scaleby <xscale> (<yscale>)

Where:
<xscale>, <yscale> (pseudo-real) – the x and y scale factors. If <yscale> is omitted, then <xscale> will be used to scale both x and y (fixed aspect ratio).

Examples:

scaleby 1.1 0.75
scaleby 0.5

  Back to Contents

trim

Trims the size of the current object. It has two forms.

Syntax:

trim <x0> <y0> <x1> <y1>

trim around

Where:
<x0> (integer) – left edge (pixels)
<y0> (integer) – bottom edge (pixels)
<x1> (integer) – right edge (pixels)
<y1> (integer) – top edge (pixels)

Use negative values to extend the size.

The second form is the equivalent of the trim round mask option in the Trim dialogue box.

Following a trim command, several dot variables are set (useful after a trim around so you can find the same image centre pixel).

  Back to Contents

export

Save the current object as a bitmap image file, or copy a flattened version back onto the canvas.

Syntax:

export <type>
{
 options
}

Where:
<type> is one of : PNG | Sprite | JPEG | GIF | Clear | PBM | TGA | PSD | BMP | ToCanvas
options is type-specific and are mostly . . optional (apart from Filename:). CompoScript chooses sensible defaults if you don't specify.

As of version 1.21e, when exporting vector layer objects, CanvasArea: is automatically turned on. In previous versions the user had to ensure it was on.

The ToCanvas type was introduced in version 1.22e and differs from the other types in that no file is saved, instead the object is exported back onto the canvas.

export PNG
Save the current object as a PNG file.

Syntax:

export PNG
{
 Filename: "<string>"
 CanvasArea: NO|YES
 Gamma: 1.0
 Interlace: NO|YES
 Mask: NO|YES
 Shadow: NO|YES
 Palettise: NO|YES
 CheckMask: NO|YES
 TrimMask: NO|YES
 CheckGrey: NO|YES
 More: "<string>"
}

Where:
CheckMask: if YES, an attempt will be made to simplify any mask.
TrimMask: if YES, transparent rows/columns will be trimmed.
CheckGrey: if YES, an attempt will be made to produce a 1 channel greyscale PNG.
More: if present, the supplied string will be added to the spr2png command line allowing for additional command options (for more information on these options, see the Spr2Png documentation).

export Sprite
Save the current object as a Sprite file.

Syntax:

export Sprite
{
 Filename: "<string>"
 CanvasArea: NO|YES
 Mask: 0|1|2 (none, 1bpp, alpha)
 Append: NO|YES
 Spritename: "<spritename>"
 Dither: NO|YES
 BlendCanvas: NO|<value>
 OutputFSI: NO|YES
 # if yes :
 CFSICols: 0|1|2|3|4|5 (16m, 32k, 256, 256g, 16c, b/w)
 CFSIScale: <scale>
 # and/or :
 CFSIx: <scale>
 CFSIy: <scale>
 CFSIAspect: NO|YES
 CFSISharp: NO|<value>
 CFSISmooth: NO|<value>
 CFSIGamma: NO|<value>
 CFSIDither: NO|YES
 CFSIRange: NO|YES
}

Where:
CFSICols: can take one of six values, for which there are several synonyms :
  0, "16m", "millions" – 16M colour sprite
  1, "32k", "thousands" – 32K colour sprite
  2, "256", "riscos", "255" – 256 colour RISC OS palette
  3, "256g","greys","greyscale" – 256 grey sprite
  4, "16c", "16", "riscos16" – 16 colour RISC OS desktop sprite
  5, "b/w", "b&w", "mono", "black and white" – b/w sprite

NB. To export as a 16 colour sprite, the desktop must first be placed in a 16 colour mode (this is a ChangeFSI requirement).

export JPEG
Save the current object as a JPEG file.

Syntax:

export JPEG
{
 Filename: "<string>"
 CanvasArea: NO|YES
 Quality: <number>
 Progressive: NO|YES
}

export GIF
Save the current object as a GIF file.

Syntax:

export GIF
{
 Filename: "<string>"
 CanvasArea: NO|YES
 Palette: 0|1|2 (Best, RISC OS, NetScape)
 Mask: NO|BLEND|<value>
 BlendCanvas: NO|<value>
 DitherMask: NO|YES
 DitherSprite: NO|YES
 Interlace: NO|YES
 TrimToMask: NO|YES
}

export Clear
Save the current object as a Clear file.

Syntax:

export Clear
{
 Filename: "<string>"
 CanvasArea: NO|YES
}

export PBM
Save the current object as a PBM file.

Syntax:

export PBM
{
 Filename: "<string>"
 CanvasArea: NO|YES
}

export TGA
Save the current object as a TGA file.

Syntax:

export TGA
{
 Filename: "<string>"
 CanvasArea: NO|YES
}

export PSD
Save the current object as a PSD file.

Syntax:

export PSD
{
 Filename: "<string>"
 CanvasArea: NO|YES
}

export BMP
Save the current object as a BMP file.

Syntax:

export BMP
{
 Filename: "<string>"
 CanvasArea: NO|YES
}

Only uncompressed 24bpp BMPs at present.

export ToCanvas
This produces a new canvas object (if enough memory is free) from the currently selected object. It is like saving an image and then reloading it (as a new object with default attributes).

If CanvasArea: is specified and defined as YES then the result will be flattened - ie a single object containing the results of all the layered objects present within the selected object's bounding box.

This command is particularly useful with AOIs, to make a single bitmap object (ie a Sprite) from whatever is on the canvas within the AOI's bounding box (with the option of composited masks).

Syntax:

export tocanvas
{
 Filename: "<string>"
 CanvasArea: NO|YES
 Mask: 0|1|2 (none, 1bpp, alpha)
 At: <x>,<y>
}

Either AsObject or Object can be used as synonyms for ToCanvas.

Note that for this export type Filename: should be just the leafname for the new object (any path element will be ignored).

If Mask: is present and set to '2' then all of the masks present in the target area (the PSO) will be combined and given to the new object.

If the At: line is present the bottom left of the new image will be placed at the specified pixel coordinates otherwise it will be at 0,0 (bottom left of the canvas).

Example applications of export tocanvas include : image stacking (where a number of dark frames are added together to produce a well exposed image), and using a script to produce an average of a series of frames (eg. digital camera sensor noise reduction).

  Back to Contents

loadimage

This command loads a graphics object. There are two forms, depending on whether the object is a bitmap image file, or a vector (Draw/Artworks) file.

Syntax: (bitmap files)

loadimage <filename>

Syntax: (vector files)

loadimage <filename>
{
 Vector: YES|NO
 Scale: <scale>
 Angle: <deg>
 Automask: NO|YES
 Border: <bx>,<by>
}

Where:
<scale> (integer) – the scale factor to be applied, as a percentage.
<deg> (integer) – the amount of rotation (degrees). Negative is clockwise.
<bx>, <by> (integer) – the amount of additional surrounding space (pixels).

If any options are omitted, or even if the first form is used with a Draw/Artworks file, default values are used. These are :

Vector: YES
Scale: 100%
Angle: 0
Automask: NO
Border: 0,0

If the second form is used with a bitmap file, the values given are ignored.

  Back to Contents

ifexists

This function checks for the existence of an object.

Example:

ifexists "text1" then
 proc something
endif

This tests for the existence of an object called 'text1'.

You can use else with this construct, and even elseif if you can think of a use for it.

  Back to Contents

makeaoi

Creates an area of interest (AOI) on the canvas. This has no effect on any underlying image on the canvas.

Once created, an AOI may be selected, moved, resized, exported, just like any other object in CompoScript.

Currently, masks (shadows, tints, etc) for AOIs are undefined, so avoid using mask-related commands with AOIs.

Syntax:

makeaoi <xlow> <ylow> <width> <height> ["<name>"]

Where:
<xlow>, <ylow> (integer) – the left x and bottom y canvas coordinates for the AOI.
<width>, <height> (integer) – the width and height of the AOI (pixels).
<name> (string) – the name for the AOI. If no name is provided one is automatically generated.

  Back to Contents

maketext

Create a text object or modify the current object. Which of these two actions is performed is determined by whether the object name is specified. Ie.

maketext <title>
{
 options
}

will create a new text object with the name specified in <title>. Any options that are omitted will be given default values.

Whereas :

maketext
{
 options
}

will modify an existing (the currently selected) object.

The action in this case depends on the type of object selected :

Syntax:

maketext (<title>)
{
 Text: <text>
 Font: <fontname>
 Size: <w>x<h>
 At: <x> <y>
 Angle: <deg>
 KeepCentre: YES|NO
 Colour: <textcolour>
 Texture: OFF|<filename>
 Border: <bx>,<by>
 # To disable rubout :
 Rubout: OFF
 # or to enable it :
 Rubout: (<opacity>%) <backcolour>
 Tracking: <tx> <ty>
 Shear: <sx> <sy>
}

Where:
<title> (string) – the text object's name. If present a new text object will be created; if absent an existing object will be modified.
<text>, <fontname> (string) – the textual content and the name of the font to be used.
<w>, <h> (integer / pseudo-real) – the text width and height (pts). If only one parameter is given, this will specify both width and height (ie 100% aspect ratio). When masking a sprite the text size field has been enhanced to support fitting, whereby either or both width and height may be replaced with the keyword FIT, which will set the font size to fit into the sprite (taking account of any borders you specify).
<x>, <y> (integer) – the position on the canvas at which to place the text object (bottom left corner).
<deg> (integer) – the amount of rotation (degrees). Negative is clockwise.
<textcolour>, <backcolour> (integer) – 24-bit colour values (&rrggbb).
<bx>, <by> (integer) – the amount of additional surrounding space (pixels).
<opacity> (integer) – the amount of transparency (0-100%). The % symbol is required. This parameter can be omitted, in which case a value of 100% will be assumed.
<tx>, <ty> (integer) – the amount of x and y tracking.
<sx>, <sy> (integer) – the amount of x and y shear (%).

Size:FIT – fits as best as possible (but keeping a 100% text aspect ratio).
Size:FIT,FIT – fits exactly (allowing a non-100% text aspect ratio).

KeepCentre: is only of use when modifying a text object such that the width changes. When ON, the text will remain centred about the same point. When OFF, the left edge will remain fixed.

Texture:OFF and Rubout:OFF are only needed when modifying text and you wish to explicitly remove either option. There is no ON associated with these options - just specifying them will do that. If Texture: is not specified (or is set OFF, or the texture file cannot be found), then the <textcolour> will be used. Note that OFF, 0 and FALSE are all synonymous.

Compo is supplied with a directory of textures (in <Compo$Resources>.textures) which may be added to, though any tileable image file may be used with the Texture: option.

Several dot variables are set if the selected object is a text object (ie if .istext = 1). Currently these are all read-only, though this may change in a future release. It is possible however to pass them in as part of a modifying maketext command. As in this example script that doubles the size of all text objects on a canvas.

Examples:

let yellow = &FFFF00
maketext "Titletext"
{
 Text: "Squat red text"
 Font: Homerton.Bold
 Size: 50x10
 At: 64 64
 Colour: &ff0000
 Border: 16,16
 Rubout: 50% <yellow>
}


maketext "line1"
{
 Text: "12.5 pt text"
 Font: Homerton.Medium
 Size: 12.5
 Colour: &aa00aa
 At: 50 50
}


maketext "banner"
{
 Text: "Fluffy Clouds Inc"
 Font: Homerton.Bold
 Size: 60 40
 At: 50 50
 Texture: "<Compo$Resources>.textures.n056/jpg"
}


select "sometext"
# Force rubout off for this piece of text
maketext
{
 Rubout: off
}

  Back to Contents

makemask

This creates a mask for the current object. It can either be a copy of another mask (belonging to the same object), or a blank white or black mask.

Syntax: (copy)

makemask <newmask> copy <mask> 

Syntax: (blank)

makemask <newmask> <colour>

Where:
<newmask>, <mask> is one of : Blend | Tint | Curve | Shadow | Displace | Texture
<colour> is one of : White | Black

Examples:

makemask Tint copy Blend
makemask Blend white
makemask Shadow black

  Back to Contents

loadmask

Load an image file into the specified mask for the current object. There is an extended form that allows the image to be scaled and/or mixed during the load operation.

Syntax: (normal)

loadmask <mask> <filename>

Syntax: (extended form)

loadmask <mask> <filename>
{
 Mix: <mix>
 Scale: <scale>
}

Where:
<mask> is one of : Blend | Tint | Curve | Shadow | Displace | Texture
<mix> is one of : No | Yes | Invert
<scale> is one of : No | Yes | Aspect

The default for both <mix> and <scale> is No.

There are various synonyms for the mix and scale parameters :
Mix : no,none,0   yes,true,1   invert,inverse,2
Scale : no,none,0   yes,fit,tofit,exact,1   aspect,aspectlock,toaspect,2

If AspectLock is used with vector objects, they are rendered centred in the mask.

Example:

loadmask BLEND "adfs::4.$.Images.softvignette"

  Back to Contents

savemask

This saves the specified mask of the current object.

Syntax:

savemask <mask> <filename> (<filetype>)

Where:
<mask> is one of : Blend | Tint | Curve | Shadow | Displace | Texture | Data
<filetype> is one of : Sprite | JPEG | PNG | Squash

If <filetype> is omitted, a Sprite will be saved.

The vector file data for vector in sprite objects may be extracted by saving the Data mask, in which case <filetype> is ignored as it will save a Draw or ArtWorks file, as appropriate. This will not work with TopModel files, as they are heavily modified when loaded.

Examples:

savemask BLEND "adfs::4.$.Images.Spider" JPEG
savemask Data "adfs::4.$.Images.ViSMask"

  Back to Contents

processmask

Apply image processing to the specified mask of the current object. There are three forms : a single-line form for mask processing operations, a single-line form for alpha channel operations, and a multi-line form solely for graduated fills.

Most of the processes from Compo's Edit Mask menu are available, with any submenu options being specified as additional parameter(s).

Note that any (single) parameters that are made up of more than one word (ie space separated) must be quoted.

Syntax: (process)

processmask <mask> <process> (<processparams>)

Where:
<mask> is one of : Blend | Tint | Curve | Shadow | Displace | Texture
<process> is one of : Antialias | Darken | Edge | Ghost | Invert | Lighten | Sharpen
Filter is a synonym for Antialias.
<processparams> depends on the process :

Antialias | Filter
One of : Silk | Soften | Smooth | Smudge | InvGaussian | "Smudge horizontal" | "Smudge vertical" | "Gaussian blur" | Emboss | BigEmboss | Vaseline | SuperSmooth | Froody | "Edge detect" | "Edge enhance"
Silk, Soften, Smooth and Smudge can each take an optional second parameter :
One (or none) of : All | AllButBlack | AllButWhite | AllButWhiteOrBlack | OnlyBlack | OnlyWhite
Specifying All is the same as specifying nothing.

Darken
One (or none) of : All | AllButBlack | AllButWhite | AllButWhiteOrBlack | OnlyBlack | OnlyWhite

Edge
One of : Minimum | Median | Maximum

Ghost
No parameters

Invert
No parameters

Lighten
One (or none) of : All | AllButBlack | AllButWhite | AllButWhiteOrBlack | OnlyBlack | OnlyWhite

Sharpen
One (or none) of : All | AllButBlack | AllButWhite | AllButWhiteOrBlack | OnlyBlack | OnlyWhite | Cutoff
Cutoff requires a second parameter : <value> (0-255). This passes a cutoff filter over the specified mask : values in the mask below the specified value are set to zero (transparent), those equal to or above are set to 255 (solid).

The list of processes is extendable – any of the filters specified in the '!Compo.Resources.Filters' file may be used, though it's not immediately obvious which can be used as a process in their own right, and which are a sub-process of Antialias.

Examples:

processmask shadow antialias smudge
processmask blend edge maximum
processmask tint antialias smooth allbutblack
processmask blend antialias "edge detect"
processmask blend sharpen cutoff 128

Syntax: (alpha channel)

processmask <mask> readalpha

To read the alpha channel into the specified mask.

processmask <mask> writealpha

To write the specified mask to the alpha channel of the image.

Where:
<mask> is one of : Blend | Tint | Curve | Shadow | Displace | Texture

Syntax: (graduated fill)

processmask <mask> GradFill
{
 Type: Circular|Angled
 Blended: YES
 Opacity: <opacity>

 # If Circular :
 Centre: <cx>,<cy>
 Size: <size>
 EdgeIntensity: <ei>
 CentreIntensity: <ci>

 # If Angular :
 Startpos: <x1>,<y1>
 Endpos: <x2>,<y2>
 StartIntensity: <i1>
 EndIntensity: <i2>
}

Where:
<opacity> (integer) – transparency (0-255)
<cx>, <cy> (integer) – centre coordinates (pixels)
<size> (integer) – radius (pixels)
<x1>, <y1>, <x2>, <y2> (integer) – start and end positions (pixels)
<ei>, <ci>, <i1>, <i2> (integer) – intensity levels (0-255)

  Back to Contents

shadow

Creates a shadow mask for the current object.

Syntax:

shadow ON
{
 Type: <type>
 Opacity: <opacity>
 Colour: &rrggbb
 XOffset: <xoff>
 YOffset: <yoff>
 3D: OFF|ON,<shear>,<shrink>
}

Where:
<type> is one of : Normal | Subtractive | Blend
<opacity> (integer) – transparency value (0-255).
<xoff>, <yoff> (integer) – displacement of the shadow (pixels).
<shear> (pseudo-real) – amount of shear.
<shrink> (pseudo-real) – amount of shrinkage.

If values for <shear> and <shrink> are omitted, a value of zero will be assigned, even when setting 3D Off.

Note that the 3D: option is the sole exception in CompoScript in that its parameters must be comma separated (for the time being, at least).

The shadow's opacity can be linked to the opacity of the object itself, using the .shadow dotvar.

Example:

shadow ON
{
 Type: Normal
 Opacity: 255
 Colour: &a0a0a0
 XOffset: 3
 YOffset: 3
 3D: OFF,0.30,0.50
}

  Back to Contents

readpixel

Reads the specified pixel from the current object. This is of the original image - before any of Compo's effects are applied (so opacity/mask/shadow/math settings have no effect on the returned values).

Syntax:

readpixel <x> <y>

Where:
<x>, <y> (integer) – the coordinates of the pixel to read.

Note that readpixel and writepixel are slow in execution, and hence not recommended for processing an entire image. An alternative approach would be to write a BASIC/C/ARM program to process an image and call that.

Following a readpixel command, several dot variables are set.

  Back to Contents

writepixel

Sets the specified pixel in the current object. It has two forms.

Syntax:

writepixel <x> <y> (<p>)

writepixel <x> <y> (<r> <g> <b>)

Where:
<x>, <y> (integer) – the coordinates of the pixel to be written.
<p> (integer) – the pixel value (Acorn 32-bit sprite format, &XXbbggrr)
<r>, <g>, <b> (integer) – the red, green and blue colour components (0-255).

The dot variables set after a call to readpixel will be used by default in a writepixel command if you don't specify them.

Note that readpixel and writepixel are slow in execution, and hence not recommended for processing an entire image. An alternative approach would be to write a BASIC/C/ARM program to process an image and call that. See the star command for details.

  Back to Contents

mouseover

This is an exceptionally powerful command. It allows procedures to be attached to mouse events. It makes possible the creation of presentations using CompoScript.

Note that currently you can't switch off a mouseover. Also, active mouseovers impact on execution speed.
***Limit of 10 active at once***

Syntax:

mouseover <object> on <event> proc <procname>

Where:
<object> (string) – the name of the object to associate the mouseover event with.
<event> is one of : Click | Over
<procname> (string) – the name of the procedure to be called when the mouseover event occurs.

Examples:

mouseover "fred" on over proc flash
mouseover "fred" on click proc something

When the pointer is over the bounding box of the object called "fred", proc flash will be called, and when there is a mouse click on this object, proc something will be called.

Within the called procedure, the variable .mouseover will hold the name of the object that the pointer was over / clicked on. The usual variables can then be used.

This is best illustrated by a complete script.

  Back to Contents

include | library

The commands include and library are synonyms. They both take a single parameter which should resolve to a string pointing to the library file to include.

Syntax:

include "<filename>"

library "<filename>"

Libraries are text files containing CompoScript procedures. When searching for a proc to execute, Compo will first search the main script and then the libraries (in the order they were included) for the name of the procedure.

NB. Scripts which use libraries should be properly formed (ie. end with an end or stop command) otherwise execution may stray into the libraries with unexpected results (BASIC does the same).

A new system variable (Compo$Scripts) is defined, which points to the scripts directory within Compo. It is suggested that library files be stored in a directory (called 'libs') within this directory. A command to include a library of functions then takes the form :

library "<Compo$Scripts>.libs.shadow"

This avoids problems inherent with fully specified paths (disc names changing etc).

  Back to Contents

scriptoptions

This allows global script options to be set, of which there are several.

scriptoptions HideCanvas
Moves the canvas to the back of the window stack.

scriptoptions HidePanes
Hides the pane windows.

scriptoptions ShowPanes
Show the pane windows.

scriptoptions FullScreen "X800 Y600 C32K"
Select the given screen mode, remove title and scrollbars, centre canvas around display. An error is returned if the desired mode cannot be selected.

scriptoptions ShowPointer
scriptoptions HidePointer
scriptoptions BigPointer
Pointer control.

scriptoptions HourGlassOn
scriptoptions HourGlassOff
Hourglass control.

scriptoptions CT_Cols
Use ColourTrans colours.

  Back to Contents

Lenny, 21 Oct 2003