# `gAT` — `gY`

## Contents

- `gAT` — Sets the drawing position using absolute co-ordinates
- `gBORDER` — Draws a border
- `gBOX` — Draws a box
- `gBUTTON` — Draws a 3D button
- `gCIRCLE` — Draws a circle
- `gCLOCK` — Draws or removes a clock
- `gCLOSE` — Closes a drawable
- `gCLS` — Clears the current drawable
- `gCOLOR` — Sets the pen colour
- `gCOLORBACKGROUND` — Sets the background colour
- `gCOLORINFO` — Gets the EPOC device’s colour information
- `gCOPY` — Copies a rectangular area
- `gCREATE` — Creates a window
- `gCREATEBIT` — Creates a bitmap
- `gELLIPSE` — Draws an ellipse
- `GEN$` — Converts a number to a string
- `GET` — Waits for and returns the keycode for the next key pressed
- `GET$ —` Waits for and returns the next key pressed as a string
- `GETCMD$` — Gets new command line arguments
- `GETDOC$` — Gets the name of the current document
- `GETEVENT` — Deprecated version of `GETEVENT32`
- `GETEVENT32` — Synchronous wait for event
- `GETEVENTA32` — Waits for an event asynchronously
- `GETEVENTC` — Cancels an outstanding `GETEVENT32`
- `gFILL` — Draws a filled rectangle
- `gFONT` — Sets the current drawable’s font
- `gGMODE` — Sets the effect of subsequent drawing commands
- `gGREY` — Changes pen colour between black and grey
- `gHEIGHT` — Height of the current drawable
- `gIDENTITY` — ID of the current drawable
- `gINFO32` — Gets information about the current drawable
- `gINVERT` — Draws an inverted rectangle
- `GIPRINT` — Displays an information message
- `gLINEBY` — Draws a line
- `gLINETO` — Draws a line to an absolute position
- `gLOADBIT` — Loads a bitmap
- `gLOADFONT` — Loads a font
- `GLOBAL` — Declares global variables
- `gMOVE` — Moves the current position
- `gORDER` — Moves the selected window
- `gORIGINX` — Window’s X position
- `gORIGINY` — Window’s Y position
- `GOTO` — Jumps to a labelled line
- `GOTOMARK` — Makes a bookmarked record the current record
- `gPATT` — Draws a pattern-filled rectangle
- `gPEEKLINE` — Reads a horizontal line from a drawable
- `gPOLY` — Draws a polygon
- `gPRINT` — Prints a list into a drawable
- `gPRINTB` — Prints text into a cleared box
- `gPRINTCLIP` — Prints text which fits within defined area
- `gRANK` — Gets foreground/background position of the current window
- `gSAVEBIT` — Saves the current drawable
- `gSCROLL` — Scrolls pixels
- `gSETPENWIDTH` — Sets the pen width
- `gSETWIN` — Changes position/size of the current window
- `gSTYLE` — Sets the style of text used in subsequent print commands
- `gTMODE` — Sets the character display mode
- `gTWIDTH` — Calculates the screen width of a string
- `gUNLOADFONT` — Unloads a font
- `gUPDATE` — Controls screen updates
- `gUSE` — Sets the current drawable
- `gVISIBLE` — Sets the visibility of the current window
- `gWIDTH` — Current drawable’s width
- `gX` — X position in the current drawable
- `gXBORDER` — Draws a border
- `gXPRINT` — Prints a string with precise highlighting or underlining
- `gY` — Y position in the current drawable

## `gAT` — Sets the drawing position using absolute co-ordinates

Usage: `gAT x%,y%`

Sets the current position using absolute co-ordinates. `gAT 0,0` moves to the top left of the current drawable.

See also `gMOVE`.

## `gBORDER` — Draws a border

Usage: `gBORDER flags%,width%,height%
`or `gBORDER flags%`

`gBORDER` is included for compatibility with older versions of OPL, however it is recommended that programmers use `gCREATE` and `gXBORDER` in preference to this function (see below).

Draws a one-pixel wide, black border around the edge of the current drawable. If `width%` and `height%` are supplied, a border shape of this size is drawn with the top left corner at the current position. If they are not supplied, the border is drawn around the whole of the current drawable.

`flags%` controls three attributes of the border: a shadow to the right and beneath, a one-pixel gap all around, and the type of corners used. Its value can be built from:

`KBordSglShadow%` | 1 | Single pixel shadow.
`KBordSglGap%` | 2 | Removes a single pixel shadow.
`KBordDblShadow%` | 3 | Double pixel shadow.
`KBordDblGap%` | 4 | Removes a double pixel shadow.
`KBordGapAllRound%` | $100 | One pixel gap all round.
`KBordRoundCorners%` | $200 | More rounded corners.
`KBordLosePixel%` | $400 | Less rounded corners (only one pixel missing at the corner).

These constants are supplied in `Const.oph`.

These shadows do not appear in the same way that shadows on other objects such as dialogs and menu panes appear. To display such shadows on a window, you must specify them when using `gCREATE`. Hence you should use `gCREATE` (and `gXBORDER`) in preference to `gBORDER`.

You can combine the values to control the three different effects. (1, 2, 3 and 4 are mutually exclusive you cannot use more than one of them.) For example, for rounded corners and a double pixel shadow, use `flags%=$203`.

Set `flags%=0` for no shadow, no gap, and sharper corners.

For example, to de-emphasise a previously emphasised border, use `gBORDER` with the shadow turned off:

        gBORDER 3             REM show border
        GET
        gBORDER 4             REM border off
        ...

See also `gXBORDER`.

## `gBOX` — Draws a box

Usage: `gBOX width%,height%`

Draws a box from the current position, `width%` to the right and `height%` down. The current position is unaffected.

## `gBUTTON` — Draws a 3D button

Usage: any of

        gBUTTON text$,type%,w%,h%,state%
        gBUTTON text$,type%,w%,h%,state%,bmpId&
        gBUTTON text$,type%,w%,h%,state%,bmpId&,maskId&
        gBUTTON text$,type%,w%,h%,state%,bmpId&,maskId&,layout%

Draws a 3-D black and grey button at the current position in a rectangle of the supplied width `w%` and height `h%`, which fully encloses the button in all its states. `text$` specifies up to 64 characters to be drawn in the button in the current font and style. You must ensure that the text will fit in the button.

The `type%` argument specifies the type of button to be drawn. For EPOC, this `type%` should be `KButtS5%`, although different values are supported by `gBUTTON` for backwards compatibility. Not all button states are supported by older button types.

`KButtS5%` | 2 | The standard EPOC button type. This is the style of button used on the Psion Series 5 and other EPOC devices.

The `state%` argument gives the button state:

`KButtS5Raised%` | 0 | A raided button.
`KButtS5SemiPressed%` | 1 | A semi-depressed (flat) button.
`KButtS5Sunken%` | 2 | A fully-depressed (sunken) button.

These constants, as well as the constants for legacy buttons are provided in `Const.oph`.

#### Button bitmaps

Bitmaps may be used on buttons. Three extra optional arguments can be passed which give the bitmap ID, the mask ID and the layout for the button respectively. `maskId%` can be 0 to specify no mask, but `bmpId%` must always be specified.

The `layout%` argument specifies the relative positions of text and icon on a button:

`KButtLayoutTextRightPictureLeft%` | 0 | Text on right, picture on left.
`KButtLayoutTextBottomPictureTop%` | 1 | Text below, picture above.
`KButtLayoutTextTopPictureBottom%` | 2 | Text above, picture below.
`KButtLayoutTextLeftPictureRight%` | 3 | Text on left, picture on right.

The following constants can be added to `layout%` above to specify how a button’s excess space is to be allocated:

`KButtExcessShare%` | $00 | Excess space is shared equally.
`KButtExcessToText%` | $10 | Excess is allocated to text only.
`KButtExcessToPicture%` | $20 | Excess goes to the picture only.

These constants are provided in `Const.oph`.

When the layout is such that the text is at the top or the bottom, then text and picture are centred vertically and horizontally in the space allotted to them. If the layout has text to the left or right, then the text is left aligned in the space allotted to it and the picture is right or left aligned respectively. Both text and picture are centred vertically in this case.

For a picture only with no text use `text$=""`.

‘Invalid arguments’ error is raised if you use OPL windows for `gBUTTON`. Read-only bitmaps may also be loaded using the Bitmap OPX. See `Bmp.opx` — Sprites and bitmaps for more details of how to do this.

N.B.: a button is a purely graphical entity and so doesn’t own the bitmaps. Therefore the bitmap may not be unloaded while the button is still in use.

## `gCIRCLE` — Draws a circle

Usage:`gCIRCLE radius%
`or`gCIRCLE radius%,fill%`

Draws a circle with the centre at the current position in the current drawable. If the value of `radius%` is negative then no circle is drawn.

If `fill%` is supplied and if `fill%`<>0 then the circle is filled with the current pen colour.

See gELLIPSE, gCOLOR.

## `gCLOCK` — Draws or removes a clock

Usage: any of

        gCLOCK ON/OFF
        gCLOCK ON,mode%
        gCLOCK ON,mode%,offset&
        gCLOCK ON,mode%,offset&,format$
        gCLOCK ON,mode%,offset&,format$,font&
        gCLOCK ON,mode%,offset&,format$,font&,style%

Displays or removes a clock showing the system time. The current position in the current window is used. Only one clock may be displayed in each window.

`mode%` controls the type of clock:

`KgClockS5System%` | 6 | Black and grey medium, system setting.
`KgClockS5Analog%` | 7 | Black and grey medium, analog.
`KgClockS5Digital%` | 8 | Second type medium, digital.
`KgClockS5LargeAnalog%` | 9 | Black and grey, extra large, analog.
`KgClockS5Formatted%` | 11 | Formatted digital.

The digital clock (`mode%=KgClockS5Digital%`) automatically displays the day of the week and day of the month below the time. The extra large analog clock (`mode%=KgClockS5LargeAnalog%`) automatically displays a second hand.

Warning: Do not use `gSCROLL` to scroll the region containing a clock. When the time is updated, the old position would be used. The whole window may, however, be moved using `gSETWIN`.

Digital clocks display in 24-hour or 12-hour mode according to the system-wide setting.

`offset&` specifies an offset in minutes from the system time to the time displayed. This allows you to display a clock showing a time other than the system time. A flag which has the value $100, may be ORed with `mode%` so that `offset&` may be specified in seconds rather than minutes. The offset is a long integer to enable a whole day to be specified when the offset is in seconds.

If these arguments are not supplied, `mode%` is taken as 1, and `offset&` as 0.

The system setting for the clock type (i.e. digital or analog) can be changed by an OPL program using the procedure `LCSETCLOCKFORMAT`: in the Date OPX (see `Date.opx` — Date and time manipulation). This function should be used to implement, for example, tapping a toolbar clock to change its type as in the built-in EPOC applications.

`format$`, `font%` and `style%` are used only for formatted digital clocks (`mode%` 11 on EPOC). The values for `font&` and `style%` are as for `gFONT` and `gSTYLE`. The default font for `gCLOCK` is the system font. The default style is normal (0).

For the formatted digital clock, a format string (up to 255 characters long) specifies how the clock is to be displayed. The format string contains a number of format specifiers in the form of a `%` followed by a letter. Upper or lower case may be used.

The format string may contain the following symbols to obtain the required effects:

`%%` | Insert a single `%` character in the string
`%*` | Abbreviate following item. (The asterisk should be inserted between the `%` and the number or letter, e.g. `%*1`). In most cases this amounts to omitting any leading zeros, for example if it is the first of the month `"%F %*M"` will display as `1` rather than `01`.
`%:n` | Insert a system time separator character. `n` is an integer between zero and three inclusive which indicates which time separator character is to be used. For European time settings, only `n=1` and `n=2` are used, giving the hours/minutes separator and minutes/seconds separator respectively.
`%/n` | Insert a system date separator character. `n` is an integer between zero and three inclusive which indicates which date separator character is to be used. For European time settings, only `n=1` and `n=2` are used, giving the day/month separator and month/year separator respectively.
`%1` | Insert the first component of a three component date (i.e. a date including day, month and year) where the order of the components is determined by the system settings. The possibilities are: dd/mm/yyyy, (European), mm/dd/yyyy (American), yyyy/mm/dd (Japanese).
`%2` | Insert the second component of a three component date where the order has been determined by the system settings. See `%1`.
`%3` | Insert the third component of a three component date where the order has been determined by the system settings. See `%1`.
`%4` | Insert the first component of a two component date (i.e. a date including day and month only) where the order has been determined by system settings. The possibilities are: dd/mm, (European), mm/dd (American), mm/dd (Japanese).
`%5` | Insert the second component of a two component date where the order has been determined by the system settings. See `%4`.
`%A` | Insert `am` or `pm` according to the current language and time of day. Text is printed even if 24 hour clock is in use. Text may be specified to be printed before or after the time, and a trailing or leading space as appropriate will be added. The abbreviated version (`%*A`) removes this space. Optionally, a minus or plus sign may be inserted between the `%` and the `A`. This operates as follows: `%-A` causes am/pm text to be inserted only if the system setting of the am/pm symbol position is set to display before the time. Similarly, `%+A` causes am/pm text to be inserted only if the system setting of the am/pm symbol is set to display after the time. No am/pm text will be inserted before the time if a + is inserted in the string. For example you could use, `"%-A%H%:1%T%+A"` to insert the am/pm symbol either before or after the time, according to the system setting. `%+A` and `%-A` cannot be abbreviated.
`%B` | As `%A`, except that the am/pm text is only inserted if the system clock setting is 12 hour. (This should be used in conjunction with `%J`.)
`%D` | Insert the two-digit day number in month (in conjunction with `%1` etc.).
`%E` | Insert the day name. Abbreviation is language specific (3 letters in English).
`%F` | Use this at the beginning of a format string to make the date/time formatting independent of the system setting. This fixes the order of the following day/month/year component(s) in their given order, removing the need to use `%1` to `%5`, allowing individual components of the date to be printed. (No abbreviation.)
`%H` | Insert the two-digit hour component of the time in 24 hour clock format.
`%I` | Insert the two-digit hour component of the time in 12 hour clock format. Any leading zero is automatically suppressed, regardless of whether an asterisk is inserted or not.
`%J` | Insert the two-digit hour component of time in either 12 or 24 hour clock format depending on the corresponding system setting. When the clock has been set to 12 hour format, the hour’s leading zero is automatically suppressed regardless of whether an asterisk has been inserted between the `%` and `J`.
`%M` | Insert the two-digit month number (in conjunction with `%1` etc.).
`%N` | Insert the month name (in conjunction with `%1` etc.). When using system settings (i.e. not using `%F`) this causes all months following `%N` in the string to be written in words. When using fixed format (i.e. when using `%F`) `%N` may be used alone to insert a month name. Abbreviation is language specific (3 letters in English).
`%S` | Insert the two-digit second component of the time.
`%T` | Insert the two-digit minute component of the time.
`%W` | Insert the two-digit week number in year, counting the first (part) week as week 1.
`%X` | Insert the date suffix. When using system settings (i.e. not using `%F`), this causes a suffix to be put on any date following `%X` in the string. When using fixed format (i.e. using `%F`), `%X` following any date appends a suffix for that particular date. Cannot be abbreviated.
`%Y` | Insert the four digit year number (in conjunction with `%1` etc.). The abbreviation is the last two digits of the year.
`%Z` | Insert the three digit day number in year.

Some examples of the use of these format strings are as follows. The example use is 1:30:05 pm on Wednesday, 1st January 1997, with the system setting of European dates and with am/pm after the time:

`"%-A%I:%T:%S%+A"` will print the time in 12 hour clock, including seconds, with the am/pm either inserted before or after the time, depending on the system setting. So the example time would appear as, `1:30:05 pm`.

`"%F%E %*D%X %N %Y"` will print the day of the week followed by the date with suffix, the month as a word and the year. For example, `Wednesday 1st January 1997`.

`"%E %D%X%N%Y %1 %2 %3"` will use the locale setting for ordering the elements of the date, but will use a suffix on the day and the month in words. For example, `Wednesday 01st January 1997`.

`"%*E %*D%X%*N%*Y %1 %2 '%3"` will be similar to 3., but will abbreviate the day of the week, the day, the month and the year, so the example becomes `"Wed 1st Jan 97"`.

`"%M%Y%D%1%/0%2%/0%3"` will appear as `01/01/1997`. This demonstrates that the ordering of the `%D`, `%M` and `%Y` is irrelevant when using locale-dependent formatting. Instead the ordering of the date components is determined by the order of the `%1`, `%2`, and `%3` formatting commands.

`style%` may take any of the values used to specify `gSTYLE`, other than 2 (underlined).

A note should also be made that a ‘General Failure’ error will result if you attempt to use an invalid format. Invalid formats include using `%:` and `%/` followed by 0 or 3 when in European locale setting (when these separators are without meaning) and using `%+` and `%-` followed by characters other than A or B.

## `gCLOSE` — Closes a drawable

Usage: `gCLOSE id%`

Closes the specified drawable that was previously opened by `gCREATE`, `gCREATEBIT` or `gLOADBIT`.

If the drawable closed was the current drawable, the default window (ID=1) becomes current.

An error is raised if you try to close the default window.

## `gCLS` — Clears the current drawable

Usage: `gCLS`

Clears the whole of the current drawable and sets the current position to 0,0, its top left corner.

## `gCOLOR` — Sets the pen colour

Usage: `gCOLOR red%,green%,blue%`

Sets the pen colour of the current window. The `red%,green%,blue%` values specify a colour which will be mapped to white, black or one of the greys on non-colour screens. Note that if the values of `red%`, `green%` and `blue%` are equal, then a pure grey results, ranging from black (0) to white (255).

See also `gCOLORBACKGROUND`, `gCOLORINFO`.

## `gCOLORBACKGROUND` — Sets the background colour

Usage: `gCOLORBACKGROUND red%,green%,blue%`

Sets the background, or ‘paper’ colour of the current graphics window. Subsequent graphics commands in the window will use this background colour. The `red%,green%,blue%` values specify a colour which will be mapped to white, black or one of the greys on non-colour screens. Note that if the values of `red%`, `green%` and `blue%` are equal, then a pure grey results, ranging from black (0) to white (255).

For example:

        gUSE 1
        gCOLOR $ff,0,0
        gCOLORBACKGROUND 0,0,$ff
        gAT 20,20
        gPRINTB "Red text on a blue background",250

#### Compatibility

`gCOLORBACKGROUND` does not exist in EPOC releases before ER5. If `gCOLORBACKGROUND` is used, the translated OPL program will not run correctly under ER3 or earlier EPOC releases, and the OPL source will not be translatable under ER3.

See also `gCOLORINFO`, `gCOLOR`, and testColorSupport.opl in `gCOLORINFO`’s Compatibility note.

## `gCOLORINFO` — Gets the EPOC device’s colour information

Usage: `gCOLORINFO var cinfo&()`

Interrogates the system to find the maximum number of colours available on the EPOC device. `cinfo&()` must be at least seven elements long, and on `gCOLORINFO`’s return will contain information indexed by the following values:

`gColorInfoADisplayMode%` | 1 | Default window mode.
`gColorInfoANumColors%` | 2 | Number of colours supported.
`gColorInfoANumGreys%` | 3 | Number of greys supported.

The remaining four elements are reserved for future use.

The default window mode will be one of the following values:

`KDisplayModeNone%` | 0 |
`KDisplayModeGray2%` | 1 | Two greys.
`KDisplayModeGray4%` | 2 | Four greys.
`KDisplayModeGray16%` | 3 | 16 greys.
`KDisplayModeGray256%` | 4 | 256 greys.
`KDisplayModeColor16%` | 5 | 16 colours.
`KDisplayModeColor256%` | 6 | 256 colours.
`KDisplayModeColor64K%` | 7 | 65,536 colours (16-bit colour).
`KDisplayModeColor16M%` | 8 | 16,777,216 colours (24-bit colour).
`KDisplayModeRGB%` | 9 |
`KDisplayModeColor4K%` | 10 | 4,096 colours (12-bit colour).

For example, to find out about the colour depth of the display on your EPOC device:

        include "Const.oph"
        proc ColTest:
              local c&(3)
              gColorInfo c&()
              print c&(gColorInfoADisplayMode%),
              print c&(gColorInfoANumColors%),
              print c&(gColorInfoANumGreys%)
              get
        endp

#### Compatibility

ER5 colour support keywords such as `gCOLORINFO` keyword cannot be used if the program is expected to run on earlier EPOC devices, as the program will report an error when the unsupported keyword is reached. However, this error can be anticipated and the program structured to cope accordingly:

        REM testColorSupport.opl
        REM (C) 1998-1999 Symbian Ltd. All rights reserved.

        INCLUDE "Const.oph"

        DECLARE EXTERNAL
        EXTERNAL Main:
        EXTERNAL ColorAvailable%:

        PROC Main:
          REM This will run on ER1 to ER5 devices (but will only
          REM translate on ER5).
          REM Attempt to find the color capabilities of the device.
          IF ColorAvailable%:
            PRINT "This device has color support."
          ELSE
            PRINT "No color support on this device."
          ENDIF
          GET
        ENDP

        PROC ColorAvailable%:
          LOCAL cinfo&(7)
          ONERR ErrorHandler::
          gCOLORINFO cInfo&()
          IF cInfo&(gColorInfoANumColors%)
            RETURN KTrue%
          ENDIF
          RETURN KFalse%
        ErrorHandler::
          ONERR OFF
          IF ERR=-96 REM Illegal Opcode
            REM gCOLORINFO not supported
            RETURN KFalse% REM No color support.
           ENDIF
          RAISE ERR       REM Not expecting this error.
        ENDP

See also `gCOLORBACKGROUND`, `gCOLOR`.

## `gCOPY` — Copies a rectangular area

Usage: `gCOPY id%,x%,y%,w%,h%,mode%`

Copies a rectangle of the specified size (width `w%`, height `h%`) from the point `x%,y%` in drawable `id%`, to the current position in the current drawable.

It is inadvisable to use `gCOPY` to copy from windows as it is very slow. It should only be used for copying from bitmaps to windows or other bitmaps.

As this command can copy both set and clear pixels, the same modes are available as when displaying text. Possible values for `mode%` are:

`KtModeSet%` | 0 | Set.
`KtModeClear%` | 1 | Clear.
`KtModeInvert%` | 2 | Invert.
`KtModeReplace%` | 3 | Replace.

Set, Clear and Invert act only on set pixels in the pattern; Replace copies the entire rectangle, with set and clear pixels.

The current position is not affected in either window.

## `gCREATE` — Creates a window

Usage: either of:

        id%=gCREATE(x%,y%,w%,h%,v%)

        id%=gCREATE(x%,y%,w%,h%,v%,flags%)

Creates a window with specified position and size (width `w%`, height `h%`), and makes it both current and foreground. The current position is set initially to (0, 0), the top left corner.

The `v%` argument specifies whether the window is initially visible:

`KgCreateInvisible%` | 0 | Invisible window.
`KgCreateVisible%` | 1 | Visible window.

`gCREATE` returns the ID of the window. Window IDs are used as arguments to other functions and keywords, and refer to the newly created window.

#### Window mode flags

The flags% argument specifies the graphics mode and shadowing style to use on the window. The defaults are 2-colour, with no shadow.

It is simplest to specify `flags%` as a hexadecimal number, as its value is a bitwise OR of significant values.

The least significant four bits of `flags%` (masked by $000F) gives the colour mode. The next 4 bits (masked by $00F0) specify the window’s shadowing. The following constant values can be added, or ORed to give the first eight bits of `flags%`:

`KColorgCreate2GrayMode%` | $0000 | 2 grey mode.
`KColorgCreate4GrayMode%` | $0001 |
`KColorgCreate16GrayMode%` | $0002 |
`KColorgCreate256GrayMode%` | $0003 | 256 grey mode.
`KColorgCreate16ColorMode%` | $0004 | 16 colour mode.
`KColorgCreate256ColorMode%` | $0005 | 256 colour mode.
`KgCreateHasShadow%` | $0010 | Window has a shadow.

These constants are provided in Const.oph. The old constants, `KgCreate2ColourMode%`, `KgCreate4ColourMode%`, and `KgCreate16ColourMode%` are still retained for backwards compatibility.

Note: It is not an error to create a window with features not supported on the hardware, but it is inefficient and should be avoided. This is similar to the concept of copying a 4-grey bitmap into a 2-grey window on greyscale machines: processor time is wasted dithering the colours down to the same level as the window.)

Bits 8-11 (masked by $0F00) give the shadow height relative to the window behind it as a left-shifted four-bit number. A height of N units gives a shadow of N * 2 pixels.

Examples:

`flags%` | description
`$412` | 16 colour-mode ($2), shadowed window ($1), with height 4 units ($4) above the previous window with a shadow of 8 pixels.
`$010` | 2 colour-mode (black and white) shadowed window at the same height as the previous window.
`$101` | 4 colour mode window with no shadow (height ignored if shadow disabled).
`$111` | 4 colour mode window with shadow of 1 unit above window behind, i.e. 2 pixel shadow.

Note that 63 windows may be open at any time and it is recommended that you use many small windows rather than a few large ones.

See also `gCLOSE`, `gCOLOR`, `DEFAULTWIN`.

## `gCREATEBIT` — Creates a bitmap

Usage:

        id%=gCREATEBIT(w%,h%)

        id%=gCREATEBIT(w%,h%,mode%)

Creates a bitmap with the specified width and height, and makes it the current drawable. Sets the current position to 0,0, its top left corner.

Returns `id%` which identifies this bitmap for other keywords.

`gCREATEBIT` may be used with an optional third parameter which specifies the graphics mode of the bitmap to be created. The values of these are as given in `gCREATE`. By default the graphics mode of a bitmap is 2-colour.

See also `gCLOSE`, `gCREATE`.

## `gELLIPSE` — Draws an ellipse

Usage: `gELLIPSE hRadius%,vRadius%
`or`gELLIPSE hRadius%,vRadius%,fill%`

Draws an ellipse with the centre at the current position in the current drawable. `hRadius%` is the horizontal distance in pixels from the centre of the ellipse to the left (and right) of the ellipse. `vRadius%` is the vertical distance from the centre of the ellipse to the top (and bottom). If the length of either radius is less than zero, then no ellipse is drawn.

If `fill%` is supplied and if `fill%<>0` then the ellipse is filled with the current pen colour.

See `gCIRCLE`, `gCOLOR`.

## `GEN$` — Converts a number to a string

Usage: `g$=gen$(x,y%)`

Returns a string representation of the number `x`. The string will be up to `y%` characters long.

Example `GEN$(123.456,7)` returns "`123.456`" and `GEN$(243,5)` returns "`243`".

- If `y%` is negative then the string is right-justified - for example `GEN$(1,-6)` returns " `1`" where there are five spaces to the left of the `1`.
- If `y%` is positive then no spaces are added for example `GEN$(1,6)` returns "`1`".
- If the number `x` will not fit in the width specified by `y%`, then the string will just be asterisks, for example `GEN$(256.99,4)` returns "`****`".

See also `FIX$`, `NUM$`, `SCI$`.

## `GET` — Waits for and returns the keycode for the next key pressed

Usage: `g%=GET`

Waits for a key to be pressed and returns the character code for that key.

For example, if the A key is pressed with Caps Lock off, the integer returned is 97 (`a`), or 65 (`A`) if A was pressed with the Shift key down.

The character codes of special keys, such as Pg Dn, are given in Appendix D.

You can use `KMOD` to check whether modifier keys (Shift, Ctrl, Fn and Caps) were used.

See also `KEY` and Character codes.

## `GET$ —` Waits for and returns the next key pressed as a string

Usage: `g$=GET$`

Waits until a key is pressed and then returns which key was pressed, as a string.

For example, if the A key is pressed in lower case mode, the string returned is `"a"`.

You can use `KMOD` to check whether any modifier keys (Shift, Ctrl, Fn and Caps) were used.

See also `KEY$`.

## `GETCMD$` — Gets new command line arguments

Usage: `w$=GETCMD$`

Returns new command-line arguments to an OPL application, after a `change files` or `quit` event has occurred. Usually this is called after `GETEVENT32` has returned a system command.

The command line arguments are returned as a string. The first character of the return value has the following meaning:

`KGetCmdLetterCreate$` | `"C"` | Close down the current file, and create the specified new file.
`KGetCmdLetterOpen$` | `"O"` | Close down the current file, and open the specified existing file.
`KGetCmdLetterExit$` | `"X"` | Close down the current file (if any) and quit the app.

These constants are defined in Const.oph.

If the first character is `KGetCmdLetterCreate$` or `KGetCmdLetterOpen$`, then the rest of the returned string is a filename.

You can only call `GETCMD$` once for each system message.

EPOC Connect now restarts applications after closing them for a backup. OPL applications will receive a `KGetCmdLetterExit$` when the application is closed by EPOC Connect, and a `KGetCmdLetterOpen$` when the application is reopened, but applications which already understand these system commands will require no code changes.

#### Compatibility

No code changes need to be made to use this additional functionality as `GETCMD$` exists in EPOC releases prior to ER5. Code translated under ER5 using `GETCMD$` will run on ER3 machines without re-translation.

See `CMD$`, and OPL applications for more details of OPL applications.

## `GETDOC$` — Gets the name of the current document

Usage: `docname$=GETDOC$`

Returns the name of the current document.

See also `SETDOC`.

## `GETEVENT` — Deprecated version of `GETEVENT32`

This keyword is included for compatibility with older versions of the OPL language.

It is strongly recommended that you use `GETEVENT32` rather than `GETEVENT`. `GETEVENT` is supported only for backward compatibility and cannot be used to handle pen events in a satisfactory way.

## `GETEVENT32` — Synchronous wait for event

Section Contents

- Keypress events
- Foreground, background and switch on events
- Command events (exit or file switch)
- Key down and key up events
- Pen point events
- Event notes

Usage: `GETEVENT32 ev&()`

Waits for an event to occur, and returns with `ev&()` specifying the event. The data returned in `ev&()` depends on the type of event that occurred.

All events return a 32-bit time stamp. The window ID mentioned below refers to the value returned by the `gCREATE` keyword. The modifier values and scancode values for a keypress (which specify a location on the keyboard) are given in the Character codes.

Const.oph supplies the following constants for indexing `ev&()`:

`KEvAType%` | 1 | Type of the event.
`KEvATime%` | 2 | 32-bit time stamp.

These event index numbers and their meanings are the same for all possible kinds of event. `ev&(KEvAType%)` is always the event type, and `ev&(KEvATime%)` is always the time stamp for the event. The meanings of other values in `ev&()` are dependant on the type of the event.

#### Keypress events

Note that keycodes are returned in the first element of `ev&()`, `ev&(`KEvAType%`)`. To recognise a keypress event, you have to use a bit mask. Keypress events are masked by `KEvNotKeyMask&`.

For a keypress event, `(ev&(`KEvAType%`) AND KEvNotKeyMask&)` is always 0.

`KEvNotKeyMask&` | &400 | Masks out non-keypress events.

The index values for a key event are:

| 1 | Key code (cooked).
| 3 | Scan code (raw).
`KEvAKMod%` | 4 | Index for the key modifier.
`KEvAKRep%` | 5 | Index for the repeat value.

`ev&(KEvATime%)` is the time stamp, as with any other event.

#### Foreground, background and switch on events

For these events, `ev&(KEvAType%)` is one of:

`KEvFocusGained&` | &401 | Program has moved to foreground.
`KEvFocusLost&` | &402 | Program has moved to background.
`KEvSwitchOn&` | &403 | Machine is switched on.

Note that `KEvSwitchOn&` is only returned by `GETEVENT32` if the appropriate flag is set by a call to `SETFLAGS`. `GETEVENT32` ignores the machine being switched on if the flag is not set.

#### Command events (exit or file switch)

This kind of event should be handled specially by programmers. For this event, `ev&(KEvAType%)` is

`KEvCommand&` | &404 | A command.

A command is passed to an application when the EPOC machine wants the application to switch files or exit. If this event is received, `GETCMD$` should be called to find out what action should be taken.

#### Key down and key up events

For these events, `ev&(KEvAType%)` is either of:

`KEvKeyDown&` | &406 | Key pressed down.
`KEvKeyUp&` | &407 | Key released.

It is only possible to extract the scancode of a key up or key down event. However, for each user keypress, three events are generated: Key up, key down and key press. The keycode can be extracted from the key press event (see above).

`ev&()` indices for these event types are:

| 3 | Key down or key up event’s scancode.
| 4 | Key modifiers.

#### Pen point events

For pen events, `ev&(KEvAType%)` is one of:

`KEvPtr&` | &408 | Pen event.
`KEvPtrEnter&` | &409 | Pen point enters a window.
`KEvPtrExit&` | &40A | Pen point leaves a window.

The `ev&()` for a pointer event is a nine-element array indexed by the following values:

`KEvAPtrOplWindowId%` | 3 | ID of parent window.
`KEvAPtrWindowId%` | 3 | Synonym for KEvAPtrOplWindowId%.
`KEvAPtrType%` | 4 | Type of pointer event (see below).
`KEvAPtrModifiers%` | 5 | Modifiers.
`KEvAPtrPositionX%` | 6 | X coordinate.
`KEvAPtrPositionY%` | 7 | Y coordinate.
`KEvAPtrScreenPosX%` | 8 | X coordinate relative to the parent window.
`KEvAPtrScreenPosY%` | 9 | Y coordinate relative to the parent window.

`ev&(KEvAPtrType%)` contains the type of the pointer event. A given EPOC device may not support all types of pointer event type because of the wide range of possible pointer input devices. `ev&(KEvAPtrType%)` will contain one of tje following values:

`KEvPtrPenDown&` | 0 | Pen down.
`KEvPtrPenUp&` | 1 | Pen up.
`KEvPtrButton1Down&` | 0 | Button 1 down.
`KEvPtrButton1Up&` | 1 | Button 1 up.
`KEvPtrButton2Down&` | 2 | Button 2 down.
`KEvPtrButton2Up&` | 3 | Button 2 up.
`KEvPtrButton3Down&` | 4 | Button 3 down.
`KEvPtrButton3Up&` | 5 | Button 3 up.
`KEvPtrDrag&` | 6 | Pointer drag (while button held down).
`KEvPtrMove&` | 7 | Pointer move (without any button being pressed).
`KEvPtrButtonRepeat&` | 8 | Button repeat.
`KEvPtrSwitchOn&` | 9 | Machine turned on by a screen touch.

#### Event notes

- Constants for event codes and subscripts are supplied in Const.oph.
- Some pointer events, and pointer enters and exits, can be filtered out to avoid being swamped by unwanted event types. See `POINTERFILTER`.

- For unknown events, `ev&(1)` contains &1400 added to the code returned by the window server. `ev&(2)` is the timestamp, `ev&(3)`is the window ID, and the rest of the data returned by the window server is put into `ev&(4)`, `ev&(5)`, etc.
- If a non-key event such as ‘foreground’ occurs while a keyboard keyword such as `GET`, `INPUT`, `MENU` or `DIALOG` is being used, the event is discarded. So `GETEVENT` must be used if non-key events are to be monitored. If you need to use these keywords in applications, use `LOCK ON` / `LOCK OFF` around them, so that the System screen won’t send messages to switch files or shutdown while the application cannot respond.

See also `GETEVENTA32`.

## `GETEVENTA32` — Waits for an event asynchronously

Usage: `GETEVENTA32 status%,ev&()`

Asynchronous version of `GETEVENT32`. `GETEVENTA32` returns the same codes to the array `ev&()` as `GETEVENT32`.

The exist status of `GETEVENTA32` is placed into `status%` when an event is received. For this reason, `status%` should probably be a global variable.

See `GETEVENTC`, `GETEVENT32`, `GETEVENT`. See also Asynchronous requests and semaphores for details of asynchronous I/O functions.

## `GETEVENTC` — Cancels an outstanding `GETEVENT32`

Usage: `GETEVENTC(var stat%)`

Cancels the previously called `GETEVENTA32` function with status `stat%`. Note that `GETEVENTC` consumes the signal (unlike `IOCANCEL`), so `IOWAITSTAT` should not be used after `GETEVENTC`.

See the Asynchronous requests and semaphores for details.

## `gFILL` — Draws a filled rectangle

Usage: `gFILL width%,height%,gMode%`

Fills a rectangle of the specified size from the current position, according to the graphics mode specified.

The current position is unaffected.

## `gFONT` — Sets the current drawable’s font

Usage: `gFONT fontUid&`

Sets the font for current drawable to `fontId&`. The font may be one of the predefined fonts in the ROM or a user-defined font. See Graphics for more details of fonts.

Constants for the font UIDs are supplied in Const.oph.

User-defined fonts must first be loaded by `gLOADFONT`, then the font UIDs of the loaded fonts may be used with `gFONT`. Note that this is not the ID returned by `gLOADFONT` (which is the font file ID), but the UID defined in the font file itself.

See also `gLOADFONT`, `FONT`.

## `gGMODE` — Sets the effect of subsequent drawing commands

Usage: `gGMODE mode%`

Sets the effect of all subsequent drawing commands `gLINEBY`, `gBOX` etc. on the current drawable.

`KgModeSet%` | 0 | Pixels will be set.
`KgModeClear%` | 1 | Pixels will be cleared.
`KgModeInvert%` | 2 | Pixels will be inverted.

These constants are supplied in Const.oph.

When you first use drawing commands on a drawable, they set pixels in the drawable. Use `gGMODE` to change this. For example, if you have drawn a black background, you can draw a white box outline inside it with either `gGMODE 1` or `gGMODE 2`, followed by `gBOX`.

## `gGREY` — Changes pen colour between black and grey

Usage: `gGREY mode%`

Changes the pen colour between black and grey. `mode%` has the following effects:

`mode%=1` sets the foreground colour of the current drawable to light grey. This is the same colour as would be achieved by using `gCOLOR $aa,$aa,$aa`.

`mode%` of any other value sets the foreground colour to black (the default).

See also `DEFAULTWIN` and `gCREATE`.

## `gHEIGHT` — Height of the current drawable

Usage: `height%=gHEIGHT`

Returns the height of the current drawable.

## `gIDENTITY` — ID of the current drawable

Usage: `id%=gIDENTITY`

Returns the ID of the current drawable.

The default window has ID=1.

## `gINFO32` — Gets information about the current drawable

Usage: `gINFO32 var i&()`

Gets general information about the current drawable and about the graphics cursor (whichever window it is in). changed. The information is returned in the array `i%()` which must be at least 32 integers long. `i&()` must have 48 elements, although elements 37 to 48 are currently unused.

`i%(1)` | Reserved.
`i%(2)` | Reserved.
`i%(3)` | Height of font.
`i%(4)` | Descent of font.
`i%(5)` | Ascent of font.
`i%(6)` | Width of '0' character.
`i%(7)` | Maximum character width.
`i%(8)` | Flags for font (see below).
`i%(9)` | The font UID as used in `gFONT`.
`i%(10-17)` | Unused.
`i%(18)` | Current graphics mode (`gGMODE`).
`i%(19)` | Current text mode (`gTMODE`).
`i%(20)` | Current style (`gSTYLE`).
`i%(21)` | Cursor state (ON=1,OFF=0).
`i%(22)` | ID of window containing cursor (-1 for text cursor).
`i%(23)` | Cursor width.
`i%(24)` | Cursor height.
`i%(25)` | Cursor ascent.
`i%(26)` | Cursor x position in window.
`i%(27)` | Cursor y position in window.
`i%(28)` | 1 if drawable is a bitmap.
`i%(29)` | Cursor effects.
`i%(30)` | Graphics colour mode of the current window. This will be one of the values described in `DEFAULTWIN`.
`i%(31)` | `gCOLOR` `red%` of foreground
`i%(32)` | `gCOLOR` `green%` of foreground
`i%(33)` | `gCOLOR` `blue%` of foreground
`i&(34)` | `gCOLOR` `red%` of background
`i&(35)` | `gCOLOR` `green%` of background
`i&(36)` | `gCOLOR` `blue%` of background

The value given for `i%(8)` is a combination of the following values:

`1` | Font uses standard ASCII characters (32-126).
`2` | Font uses Code Page 1252 characters (128-255).
`4` | Font is bold.
`8` | Font is italic.
`16` | Font has serifs.
`32` | Font is monospaced.
`$8000` | Font is stored expanded for quick drawing.

`i%(29)` has bit 1 set (`i%(29) AND 2`) if not the cursor is not flashing, and bit 2 set (`i%(29) AND 4`) if it is grey.

If the cursor is off (`i%(21)`=0), or is a text cursor (`i%(22)=-1`), `i%(23)` to `i%(27)` and `i%(29)`should be ignored.

See also `gFONT`, `gCOLOR`, `gCREATE`.

## `gINVERT` — Draws an inverted rectangle

Usage: `gINVERT width%,height%`

Inverts the rectangle `width%` to the right and `height%` down from the cursor position, except for the four corner pixels.

## `GIPRINT` — Displays an information message

Usage: `GIPRINT str$,c%`
or `GIPRINT str$`

Displays an information message for about two seconds, in the bottom right corner of the screen. For example, `GIPRINT "Not Found"` displays `Not Found`. If a string is too long for the screen, it will be clipped.

If `c%` is given, it controls the corner in which the message appears. Corner constants for the information message are as given for `BUSY`.

Only one message can be shown at a time. You can make the message go away - for example, if a key has been pressed - with `GIPRINT ""`.

## `gLINEBY` — Draws a line

Usage: `gLINEBY dx%,dy%`

Draws a line from the current position to a point `dx%` to the right and `dy%` down from the starting point. Negative `dx%` and `dy%` mean left and up respectively. The end point is not drawn, so for `gLINEBY dx%,dy%`, point `gX+dx%,gY+dy%` is not drawn. Note, however, that OPL specially plots the point when the start and end-point coincide.

The current position moves to the end of the line drawn. `gLINEBY 0,0` sets the pixel at the current position.

See also `gLINETO`, `gPOLY`.

## `gLINETO` — Draws a line to an absolute position

Usage: `gLINETO x%,y%`

Draws a line from the current position to the point `x%,y%`. The current position moves to `x%,y%`. The end point is not drawn, so for `gLINETO x%,y%`, point `x%,y%` is not drawn. Note, however, that OPL specially plots the point when the start and end-point coincide.

To plot a single point on all machines, use `gLINETO` to the current position (or `gLINEBY 0,0`).

See also `gLINEBY`, `gPOLY`.

## `gLOADBIT` — Loads a bitmap

Usage: any of

        id%=gLOADBIT(name$,write%,index%)
        id%=gLOADBIT(name$,write%)
        id%=gLOADBIT(name$)

Loads a bitmap from the named bitmap file and makes it the current drawable. Sets the current position to 0,0, its top left corner.

`gLOADBIT` loads EPOC Picture files, which are naturally in the same file format that is saved by `gSAVEBIT`. EPOC Picture files can also be generated by exporting files created by the Sketch application. These are called multi-bitmap files (MBMs), though often containing just one bitmap as in the case of `gSAVEBIT` or Sketch files, and are often given an extension `.MBM`.

The bitmap is kept as a local copy in memory.

`gLOADBIT` returns `id%` which identifies this bitmap for other keywords.

A `write%` argument of `KgLoadBitReadOnly%` sets read-only access. Attempts to write to the bitmap in memory will be ignored, but the bitmap can be used by other programs without using more memory. Using `KgLoadBitWriteable%` for `write%` allows you to write to and re-save the bitmap, which is the default.

`KgLoadBitReadOnly%` | 0 | Read-only access
`KgLoadBitWriteable%` | 1 | Read and write access.

Constants are supplied in `Const.oph`.

For bitmap files which contain more than one bitmap, `index%` specifies which one to load. For the first bitmap, use `index%`=0, which is also the default value.

See also `gCLOSE`.

## `gLOADFONT` — Loads a font

Usage: `fileId%=gLOADFONT(file$)`

Loads the user-defined fonts specified in the file `file$` and returns the file ID of the font file, which can be used only with `gUNLOADFONT`. The maximum number of font files which may be loaded at any one time is 16.

To use the fonts in a loaded font file you need to use their published UIDs which will be defined in the font file itself, for example:

        fileId%=gLOADFONT("Music1")
        gFONT KMusic1Font1&
        ...
        gUNLOADFONT fileId%

`gFONT` itself is very efficient, so you should normally load all required fonts at the start of a program.

Note that the built-in fonts are automatically available, and do not need loading.

See `gUNLOADFONT`.

## `GLOBAL` — Declares global variables

Usage: `GLOBAL variables`

Declares variables to be used in the current procedure (as does the `LOCAL` command) and (unlike `LOCAL`) in any procedures called by the current procedure, or procedures called by them.

The variables may be of 4 types, depending on the symbol they end with:

- Variable names not ending with `$`, `%`, `&` or `()` are floating-point variables, for example `price`, `x`
- Those ending with a `%` are integer variables, for example `x%`, `sales92%`
- Those ending with an `&` are long integer variables, for example `x&`, `sales92&`.
- Those ending with a `$` are string variables. String variable names must be followed by the maximum length of the string in brackets for example `names$(12)`, `a$(3)`

Array variables have a number immediately following them in brackets which specifies the number of elements in the array. Array variables may be of any type, for example: `x(6)`,`y%(5)`,`f$(5,12)`,`z&(3)`.

When declaring string arrays, you must give two numbers in the brackets. The first declares the number of elements, the second declares their maximum length. For example `surname$(5,8)` declares five elements, each up to 8 characters long.

Variable names may be any combination of up to 32 numbers and alphabetic characters and the underscore character. They must start with a alphabetic character or an underscore.

The length of a variable name includes the `%`, `&` or `$` sign, but not the `()` in string and array variables.

More than one `GLOBAL` or `LOCAL` statement may be used, but they must be on separate lines, immediately after the procedure name.

See also `LOCAL`.

## `gMOVE` — Moves the current position

Usage: `gMOVE dx%,dy%`

Moves the current position `dx%` to the right and `dy%` downwards, in the current drawable.

A negative `dx%` causes movement to the left; a negative `dy%` causes upward movement.

See also `gAT`.

## `gORDER` — Moves the selected window

Usage: `gORDER id%,position%`

Sets the window specified by `id%` to the selected foreground/background position, and redraws the screen. Position 1 is the foreground window, position 2 is next, and so on. Any position greater than the number of windows is interpreted as the end of the list.

On creation, a window is at position 1 in the list.

Raises an error if `id%` is a bitmap.

See also `gRANK`.

## `gORIGINX` — Window’s X position

Usage: `x%=gORIGINX`

Returns the gap between the left side of the screen and the left side of the current window.

Raises an error if the current drawable is a bitmap.

## `gORIGINY` — Window’s Y position

Usage: `y%=gORIGINY`

Returns the gap between the top of the screen and the top of the current window.

Raises an error if the current drawable is a bitmap.

## `GOTO` — Jumps to a labelled line

Usage:

        GOTO label or  GOTO label::
        ...
        label::

Goes to the line following the `label::` and continues from there. The label

- Must be in the current procedure
- Must start with a letter and end with a double colon, although the double colon is not necessary in the `GOTO` statement
- May be up to 32 characters long, excluding the colons.

## `GOTOMARK` — Makes a bookmarked record the current record

Usage: `GOTOMARK b%`

Makes the record with bookmark `b%`, as returned by `BOOKMARK`, the current record. `b%` must be a bookmark in the current view.

## `gPATT` — Draws a pattern-filled rectangle

Usage: `gPATT id%,width%,height%,mode%`

Fills a rectangle of the specified size from the current position with repetitions of the drawable `id%`.

As with `gCOPY`, this command can copy both set and clear pixels, so the same modes are available as when displaying text. Set `mode%`=0 for set, 1 for clear, 2 for invert or 3 for replace. 0, 1 and 2 act only on set pixels in the pattern; 3 copies the entire rectangle, with set and clear pixels.

If you set `id%`=-1 a pre-defined grey pattern is used.

The current position is unaffected.

## `gPEEKLINE` — Reads a horizontal line from a drawable

Usage: `gPEEKLINE id%,x%,y%,d%(),ln%,mode%`

Reads a horizontal line from the black plane of the drawable `id%`, length `ln%`, starting at `x%,y%`. The leftmost 16 pixels are read into `d%(1)`, with the first pixel read into the least significant bit.

`gPEEKLINE` has an extra optional parameter `mode%` to specify the colour mode:

`mode%` | colour mode | colour of pixel which sets bits
-1 | black and white | black
0 | black and white | white
1 | 4-colour mode | white
2 | 16-colour mode | white

The default `mode%` is -1. For 4 and 16-colour modes, 2 and 4 bits per pixel respectively are used. This is to enable the colour of the pixel to be ascertained from the bits which are set. White results in all 2 or 4 bits being set, while black sets none of them. For example, in a 4-colour window, with the colour set by

        gCOLOR 16,16,16

a pixel of a line would peek as `0001` in binary. Similarly, a pixel of a line with the colour set to

        gCOLOR 80,80,80

would result in the value `0101` in binary when peeked.

The array `d%()` must be long enough to hold the data. You can work out the number of integers required with `((ln%+15)/16)` (using whole-number division).

If the optional parameter `mode%` is used, the array size allowed must be adjusted accordingly: it must be at least twice as long as the array needed for black and white if the line you wish to peek in 4-colour mode and four times as long in 16-colour mode.

## `gPOLY` — Draws a polygon

Usage: `gPOLY a%()`

Draws a sequence of lines, as if by `gLINEBY` and `gMOVE` commands.

The array is set up as follows:

`a%(1)` | starting x position
`a%(2)` | starting y position
`a%(3)` | number of pairs of offsets
`a%(4)` | `dx1%`
`a%(5)` | `dy1%`
`a%(6)` | `dx2%`
`a%(7)` | `dy2%` etc.
`...` | }
`...` | } Further pairs...

The following constants can be used for the first five array indices:

`KgPolyAStartX%` | 1
`KgPolyAStartY%` | 2
`KgPolyANumPairs%` | 3
`KgPolyANumDx1%` | 4
`KgPolyANumDy1%` | 5

Each pair of numbers `dx1%,dy1%`, for example specifies a line or a movement. To draw a line, `dy%` is the amount to move down, while `dx%` is the amount to move to the right multiplied by two.

To specify a movement (i.e. without drawing a line) work out the `dx%,dy%` as for a line, then add 1 to `dx%`.

(For drawing/movement up or left, use negative numbers.)

`gPOLY` is quicker than combinations of `gAT`, `gLINEBY` and `gMOVE`.

Example, to draw three horizontal lines 50 pixels long at positions 20,10, 20,30 and 20,50:

        a%(1)=20 :a%(2)=10             REM 20,10
        a%(3)=5                               REM 5 operations
        a%(4)=50*2  :a%(5)=0             REM draw right 50
        a%(6)=0*2+1 :a%(7)=20             REM move down 20
        a%(8)=-50*2 :a%(9)=0            REM draw left 50
        a%(10)=0*2+1 :a%(11)=20            REM draw left 50
        a%(12)=50*2 :a%(13)=0            REM draw right 50
        gPOLY a%()

## `gPRINT` — Prints a list into a drawable

Usage: `gPRINT` list of expressions

Displays a list of expressions at the current position in the current drawable. All variable types are formatted as for `PRINT`.

Unlike `PRINT`, `gPRINT` does not end by moving to a new line. A comma between expressions is still displayed as a space, but a semicolon has no effect. `gPRINT` without a list of expressions does nothing.

See also `gPRINTB`, `gPRINTCLIP`, `gTWIDTH`, `gXPRINT`, `gTMODE`.

## `gPRINTB` — Prints text into a cleared box

Usage: any of

        gPRINTB t$,w%,al%,tp%,bt%,m%
        gPRINTB t$,w%,al%,tp%,bt%
        gPRINTB t$,w%,al%,tp%
        gPRINTB t$,w%,al%
        gPRINTB t$,w%

Displays text `t$` in a cleared box of width `w%` pixels. The current position is used for the left side of the box and for the baseline of the text.

`al%` controls the alignment of the text in the box:

`KgPrintBRightAligned%` | 1 | Right alignment.
`KgPrintBLeftAligned%` | 2 | Left alignment.
`KgPrintBDefAligned%` | 2 | Default alignment (left).
`KgPrintBCentredAligned%` | 3 | Centred.

`tp%` and `bt%` are the clearances between the text and the top/bottom of the box. Together with the current font size, they control the height of the box. An error is raised if `tp%` plus the font ascent is greater than 255.

`m%` controls the margins. For left alignment, `m%` is an offset from the left of the box to the start of the text. For right alignment, `m%` is an offset from the right of the box to the end of the text. For centring, `m%` is an offset from the left or right of the box to the region in which to centre, with positive `m%` meaning left and negative meaning right.

`KgPrintBDefTop%` | 0 | Default top clearance.
`KgPrintBDefBottom%` | 0 | Default bottom clearance.
`KgPrintBDefMargin%` | 0 | Default margin.

These constants are supplied in `Const.oph`.

See also `gPRINT`, `gPRINTCLIP`, `gTWIDTH`, `gXPRINT`.

## `gPRINTCLIP` — Prints text which fits within defined area

Usage: `w%=gPRINTCLIP(text$,width%)`

Displays `text$` at the current position, displaying only as many characters as will fit inside `width%` pixels. Returns the number of characters displayed.

See also `gPRINT`, `gPRINTB`, `gTWIDTH`, `gXPRINT`, `gTMODE`.

## `gRANK` — Gets foreground/background position of the current window

Usage: `rank%=gRANK`

Returns the foreground/background position — from 1 to 64 — of the current window. Raises an error if the current drawable is a bitmap.

See also `gORDER`.

## `gSAVEBIT` — Saves the current drawable

Usage: `gSAVEBIT name$,width%,height%`
or `gSAVEBIT name$`

Saves the current drawable as the named bitmap file. If `width%` and `height%` are given, then only the rectangle of that size from the current position is copied.

`gSAVEBIT` does not add a default filename extension to the input argument name if none is provided on the EPOC machine.

## `gSCROLL` — Scrolls pixels

Usage: `gSCROLL dx%,dy%,x%,y%,wd%,ht%
`or `gSCROLL dx%,dy%`

Scrolls pixels in the current drawable by offset `dx%,dy%`. Positive `dx%` means to the right, and positive `dy%` means down. The drawable itself does not change its position.

If you specify a rectangle in the current drawable, at `x%,y%` and of size `wd%,ht%`, only this rectangle is scrolled.

The areas `dx%` wide and `dy%` deep which are "left behind" by the scroll are cleared.

The current position is not affected.

## `gSETPENWIDTH` — Sets the pen width

Usage: `gSETPENWIDTH width%`

Sets the pen width in the current drawable to `width%` pixels.

## `gSETWIN` — Changes position/size of the current window

Usage: `gSETWIN x%,y%,width%,height%
`or `gSETWIN x%,y%`

Changes position and, optionally, the size of the current window.

An error is raised if the current drawable is a bitmap.

The current position is unaffected.

If you use this command on the default window, you must also use the `SCREEN` command to ensure that the area for `PRINT` commands to use is wholly contained within the default window.

## `gSTYLE` — Sets the style of text used in subsequent print commands

Usage: `gSTYLE style%`

Sets the style of text displayed in subsequent `gPRINT`, `gPRINTB` and `gPRINTCLIP` commands on the current drawable. Values for `style%`:

`KgStyleNormal%` | 0 | Normal.
`KgStyleBold%` | 1 | Bold.
`KgStyleUnder%` | 2 | Underline.
`KgStyleInverse%` | 4 | Inverse.
`KgStyleDoubleHeight%` | 8 | Double height.
`KgStyleMonoFont%` | 16 | Monospaced font.
`KgStyleItalic%` | 32 | Italic.

You can combine these styles by adding their values for example, to set bold, underlined and double height, use:

        gSTYLE KgStyleBold%+KgStyleUnder%+KgStyleDoubleHeight%

This command does not affect non-graphics commands, like `PRINT`.

## `gTMODE` — Sets the character display mode

Usage: `gTMODE mode%`

Sets the way characters are displayed by subsequent `gPRINT` and `gPRINTCLIP` commands on the current drawable. Values for `mode%`:

`KtModeSet%` | 0 | Pixels will be set.
`KtModeClear%` | 1 | Pixels will be cleared.
`KtModeInvert%` | 2 | Pixels will be inverted.
`KtModeReplace%` | 3 | Pixels will be replaced.

When you first use graphics text commands on a drawable, each dot in a letter causes a pixel to be set in the drawable, i.e. the default `gTMODE` is `KtModeSet%`.

When `mode%` is clear or invert, graphics text commands work in a similar way, but the pixels are cleared or inverted. When `mode%` is replace, entire character boxes are drawn on the screen — pixels are set in the letter and cleared in the background box.

This command does not affect other text display commands.

Constants for the modes are supplied in Const.oph.

## `gTWIDTH` — Calculates the screen width of a string

Usage: `width%=gTWIDTH(text$)`

Returns the width of `text$` in the current font and style.

See also `gPRINT`, `gPRINTB`, `gPRINTCLIP`, `gXPRINT`.

## `gUNLOADFONT` — Unloads a font

Usage: `gULOADFONT fileId%`

Unloads a user-defined font that was previously loaded using `gLOADFONT`. Raises an error if the font has not been loaded.

The built-in fonts are not held in memory and cannot be unloaded.

See also `gLOADFONT`.

## `gUPDATE` — Controls screen updates

Usage: any of

        gUPDATE ON
        gUPDATE OFF
        gUPDATE

The screen is usually updated whenever you display anything on it. `gUPDATE OFF` switches off this feature. The screen will then be updated as few times as possible (though note that some keywords will always cause an update.) You can still force an update by using the `gUPDATE` command on its own.

This can result in a considerable speed improvement in some cases. You might, for example, use `gUPDATE OFF`, then a sequence of graphics commands, followed by `gUPDATE`. You should certainly use `gUPDATE OFF` if you are about to write exclusively to bitmaps.

`gUPDATE ON` returns to normal screen updating.

`gUPDATE` affects anything that displays on the screen. If you are using a lot of PRINT commands, `gUPDATE OFF` may make a noticeable difference in speed.

Note that with `gUPDATE OFF`, the location of errors which occur while the procedure is running may be incorrectly reported. For this reason, `gUPDATE OFF` is best used in the final stages of program development, and even then you may have to remove it to locate some errors.

## `gUSE` — Sets the current drawable

Usage: `gUSE id%`

Makes the drawable `id%` current. Graphics drawing commands will now go to this drawable. `gUSE` does not bring a drawable to the foreground (see `gORDER`).

## `gVISIBLE` — Sets the visibility of the current window

Usage: `gVISIBLE ON
`or `gVISIBLE OFF`

Makes the current window visible or invisible.

Raises an error if the current drawable is a bitmap.

## `gWIDTH` — Current drawable’s width

Usage: `width%=gWIDTH`

Returns the width of the current drawable.

## `gX` — X position in the current drawable

Usage: `x%=gX`

Returns the `x` current position (in from the left) in the current drawable.

## `gXBORDER` — Draws a border

Usage: `gXBORDER type%,flags%,w%,h%
`or `gXBORDER type%,flags%`

Draws a border in the current drawable of a specified type, fitting inside a rectangle of the specified size or with the size of the current drawable if no size is specified.

`type%` should always be the constant value `KgXBorderS5Type%`. Other border types are implemented for backwards compatibility, but should not be used under EPOC.

KgXBorderS5Type% | 2 | The standard EPOC border type.

Values for `flags%` are:

none | $00
single black | $01
shallow sunken | $42
deep sunken | $44
deep sunken with outline | $54
shallow raised | $82
deep raised | $84
deep raised with outline | $94
vertical bar | $22
horizontal bar | $2a

Constants for these flags and types are supplied in Const.oph. The following values of `flags%` apply to all border types:

- 0 for normal corners
- Adding $100 leaves 1 pixel gap around the border.
- Adding $200 for more rounded corners
- Adding $400 for losing a single pixel.
- If both $400 and $200 are mistakenly supplied, $200 has priority.

See also `gBORDER`.

## `gXPRINT` — Prints a string with precise highlighting or underlining

Usage: `gXPRINT string$,flags%`

Displays `string$` at the current position, with precise highlighting or underlining. The current font and style are still used, even if the style itself is inverse or underlined. If text mode 3 (replace) is used both set and cleared pixels in the text are drawn.

Possible values for `flags%` are:

`KgXPrintNormal%` | 0 | Normal, as with gPRINT.
`KgXPrintInverse%` | 1 | Inverse.
`KgXPrintInverseRound%` | 2 | Inverse, omitting corner pixels.
`KgXPrintThinInverse%` | 3 | Thin inverse.
`KgXPrintThinInverseRound%` | 4 | Thin inverse, omitting corner pixels.
`KgXPrintUnderlined%` | 5 | Underlined.
`KgXPrintThinUnderlined%` | 6 | Thin underlined.

These constants are supplied in Const.oph.

Where lines of text are separated by a single pixel, the thin options maintain the separation between lines.

`gXPRINT` does not support the display of a list of expressions of various types.

## `gY` — Y position in the current drawable

Usage: `y%=gY`

Returns the `y` current position (down from the top) in the current drawable.