|
|
|
|
|
|
|
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.
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:
|
1 |
Single pixel shadow. |
|
|
2 |
Removes a single pixel shadow. |
|
|
3 |
Double pixel shadow. |
|
|
4 |
Removes a double pixel shadow. |
|
|
$100 |
One pixel gap all round. |
|
|
$200 |
More rounded corners. |
|
|
$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.
Usage: gBOX width%,height%
Draws a box from the current position, width% to the right and height% down. The current position is unaffected.
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.
|
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:
|
0 |
A raided button. |
|
|
1 |
A semi-depressed (flat) button. |
|
|
2 |
A fully-depressed (sunken) button. |
These constants, as well as the constants for legacy buttons are provided in Const.oph.
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:
|
0 |
Text on right, picture on left. |
|
|
1 |
Text below, picture above. |
|
|
2 |
Text above, picture below. |
|
|
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:
|
$00 |
Excess space is shared equally. |
|
|
$10 |
Excess is allocated to text only. |
|
|
$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.
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.
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:
|
6 |
Black and grey medium, system setting. |
|
|
7 |
Black and grey medium, analog. |
|
|
8 |
Second type medium, digital. |
|
|
9 |
Black and grey, extra large, analog. |
|
|
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.
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.
Usage: gCLS
Clears the whole of the current drawable and sets the current position to 0,0, its top left corner.
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.
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
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.
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:
|
1 |
Default window mode. |
|
|
2 |
Number of colours supported. |
|
|
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:
|
0 |
|
|
|
1 |
Two greys. |
|
|
2 |
Four greys. |
|
|
3 |
16 greys. |
|
|
4 |
256 greys. |
|
|
5 |
16 colours. |
|
|
6 |
256 colours. |
|
|
7 |
65,536 colours (16-bit colour). |
|
|
8 |
16,777,216 colours (24-bit colour). |
|
|
9 |
|
|
|
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
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.
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:
|
0 |
Set. |
|
|
1 |
Clear. |
|
|
2 |
Invert. |
|
|
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.
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:
|
0 |
Invisible window. |
|
|
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.
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%:
|
$0000 |
2 grey mode. |
|
|
$0001 |
|
|
|
$0002 |
|
|
|
$0003 |
256 grey mode. |
|
|
$0004 |
16 colour mode. |
|
|
$0005 |
256 colour mode. |
|
|
$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.
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.
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.
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".
See also FIX$, NUM$, SCI$.
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.
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$.
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:
|
"C" |
Close down the current file, and create the specified new file. |
|
|
"O" |
Close down the current file, and open the specified existing file. |
|
|
"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.
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.
Usage: docname$=GETDOC$
Returns the name of the current document.
See also SETDOC.
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.
Section Contents
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&():
|
1 |
Type of the event. |
|
|
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.
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.
|
&400 |
Masks out non-keypress events. |
The index values for a key event are:
|
|
1 |
Key code (cooked). |
|
|
3 |
Scan code (raw). |
|
4 |
Index for the key modifier. |
|
|
5 |
Index for the repeat value. |
ev&(KEvATime%) is the time stamp, as with any other event.
For these events, ev&(KEvAType%) is one of:
|
&401 |
Program has moved to foreground. |
|
|
&402 |
Program has moved to background. |
|
|
&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.
This kind of event should be handled specially by programmers. For this event, ev&(KEvAType%) is
|
&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.
For these events, ev&(KEvAType%) is either of:
|
&406 |
Key pressed down. |
|
|
&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. |
For pen events, ev&(KEvAType%) is one of:
|
&408 |
Pen event. |
|
|
&409 |
Pen point enters a window. |
|
|
&40A |
Pen point leaves a window. |
The ev&() for a pointer event is a nine-element array indexed by the following values:
|
3 |
ID of parent window. |
|
|
3 |
Synonym for KEvAPtrOplWindowId%. |
|
|
4 |
Type of pointer event (see below). |
|
|
5 |
Modifiers. |
|
|
6 |
X coordinate. |
|
|
7 |
Y coordinate. |
|
|
8 |
X coordinate relative to the parent window. |
|
|
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:
|
0 |
Pen down. |
|
|
1 |
Pen up. |
|
|
0 |
Button 1 down. |
|
|
1 |
Button 1 up. |
|
|
2 |
Button 2 down. |
|
|
3 |
Button 2 up. |
|
|
4 |
Button 3 down. |
|
|
5 |
Button 3 up. |
|
|
6 |
Pointer drag (while button held down). |
|
|
7 |
Pointer move (without any button being pressed). |
|
|
8 |
Button repeat. |
|
|
9 |
Machine turned on by a screen touch. |
See also GETEVENTA32.
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.
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.
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.
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.
Usage: gGMODE mode%
Sets the effect of all subsequent drawing commands gLINEBY, gBOX etc. on the current drawable.
|
0 |
Pixels will be set. |
|
|
1 |
Pixels will be cleared. |
|
|
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.
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.
Usage: height%=gHEIGHT
Returns the height of the current drawable.
Usage: id%=gIDENTITY
Returns the ID of the current drawable.
The default window has ID=1.
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.
Usage: gINVERT width%,height%
Inverts the rectangle width% to the right and height% down from the cursor position, except for the four corner pixels.
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 "".
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.
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.
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.
|
0 |
Read-only access |
|
|
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.
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.
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:
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.
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.
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.
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.
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.
Usage:
GOTO label or GOTO label::
...
label::
Goes to the line following the label:: and continues from there. The label
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.
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.
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.
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:
|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
|
|
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%()
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.
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:
|
1 |
Right alignment. |
|
|
2 |
Left alignment. |
|
|
2 |
Default alignment (left). |
|
|
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.
|
0 |
Default top clearance. |
|
|
0 |
Default bottom clearance. |
|
|
0 |
Default margin. |
These constants are supplied in Const.oph.
See also gPRINT, gPRINTCLIP, gTWIDTH, gXPRINT.
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.
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.
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.
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.
Usage: gSETPENWIDTH width%
Sets the pen width in the current drawable to width% pixels.
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.
Usage: gSTYLE style%
Sets the style of text displayed in subsequent gPRINT, gPRINTB and gPRINTCLIP commands on the current drawable. Values for style%:
|
0 |
Normal. |
|
|
1 |
Bold. |
|
|
2 |
Underline. |
|
|
4 |
Inverse. |
|
|
8 |
Double height. |
|
|
16 |
Monospaced font. |
|
|
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.
Usage: gTMODE mode%
Sets the way characters are displayed by subsequent gPRINT and gPRINTCLIP commands on the current drawable. Values for mode%:
|
0 |
Pixels will be set. |
|
|
1 |
Pixels will be cleared. |
|
|
2 |
Pixels will be inverted. |
|
|
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.
Usage: width%=gTWIDTH(text$)
Returns the width of text$ in the current font and style.
See also gPRINT, gPRINTB, gPRINTCLIP, gXPRINT.
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.
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.
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).
Usage: gVISIBLE ON
or gVISIBLE OFF
Makes the current window visible or invisible.
Raises an error if the current drawable is a bitmap.
Usage: width%=gWIDTH
Returns the width of the current drawable.
Usage: x%=gX
Returns the x current position (in from the left) in the current drawable.
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:
See also gBORDER.
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:
|
0 |
Normal, as with gPRINT. |
|
|
1 |
Inverse. |
|
|
2 |
Inverse, omitting corner pixels. |
|
|
3 |
Thin inverse. |
|
|
4 |
Thin inverse, omitting corner pixels. |
|
|
5 |
Underlined. |
|
|
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.
Usage: y%=gY
Returns the y current position (down from the top) in the current drawable.
|
|
|
|
|
|
|