GNUbik

Node:Symbolic interface, Next:Developer tips, Previous:Raw interface, Up:Writing scripts

FLUBRD symbolic interface for 3x3x3 cubes

The following functions provide access to a cube object in a way which hides the gory details of the representation. This makes it easier for human beings to write code, and also guards against changes in the low-level API described in the previous chapter.

Unfortunately, it currently only works on 3x3x3 cubes.

The interface uses the common FLUBRD notation to refer to the various faces and panels on the cube. The letters correspond respectively to the words front, left, up, back, right and down, and where up and down can be read as top and bottom, respectively.

Looking at the colours on the faces

The following procedure returns the colour on the panel addressed symbolically by the letters of a given string.

get-colour-symbolic cube symbol Procedure

The symbol is a string consisting of one, two or three letters. If one letter is supplied, the colour of the panel at the centre of the face indicated by the letter is returned. If two letters are supplied, the colour returned is of the edge panel touching the face given by the second letter. If three letters are supplied, it is the colour of the corner panel which touches the edges indicated by the second two letters.

Note that the letters of the symbol must all be lower case. A corresponding function is supplied to make changes to the cube object.

set-colour-symbolic! cube symbol colour Procedure

This procedure sets the colour of the panel indicated by symbol, defined as above, to colour.

Note that changing the colour of a cube does not cause any other changes to take effect. In particular, no rotations of the on-screen cube are initiated.

Moving the faces

The following function allows scripts to request that faces of the cube are rotated by a quarter turn.

move-face cube symbol Procedure

Here, symbol is a string of one or two characters. The first character should always be a lower case letter which indicates which face to move. The default is to turn the face clockwise. This will also occur if the second character supplied is a space or a +. Only if a second character is supplied and is a - will the face be turned anti-clockwise.

Once a script has finished declaring moves in this way, GNUbik will send them to the display buffer for on-screen animation after the script calls

execute-move-buffer! Procdure

Cause all moves created with the move-face procedure to be applied to the on-screen cube.

Note that the on-screen cube will not actually display any change until the script exits.

The move buffer can be accessed directly via the symbol move-buffer. It is a list of moves that the low-level procedure gnubik-rotate-animated expects. Accessing and manipulating it directly before calling execute-move-buffer! may allow a script to perform some post-processing optimizations on the list of moves, for example. Alternatively, if the script decides to duck out or start again, the following procedure may be called to clear the buffer without sending any move notifications to GNUbik.

clear-move-buffer! Procedure

Empty the move-buffer without sending any move requests to the GNUbik program.