Node:Symbolic interface, Next:Developer tips, Previous:Raw interface, Up:Writing scripts
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.
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.
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. |