|
|
|
|
|
|
System.opx — EPOC system functionsTo use this OPX, you must included the header file System.oxh, which contains the following declaration:
DECLARE OPX SYSTEM,KUidOpxSystem&,KOpxSystemVersion%
BackLightOn&: : 1
SetBackLightOn:(state&) : 2
SetBackLightOnTime:(seconds&) : 3
SetBacklightBehavior:(behaviour&) : 4
IsBacklightPresent&: : 5
SetAutoSwitchOffBehavior:(behaviour&) : 6
SetAutoSwitchOffTime:(seconds&) : 7
SetActive:(state&) : 8
ResetAutoSwitchOffTimer: : 9
SwitchOff: : 10
SetSoundEnabled:(state&) : 11
SetSoundDriverEnabled:(state&) : 12
SetKeyClickEnabled:(state&) : 13
SetPointerClickEnabled:(state&) : 14
SetDisplayContrast:(value&) : 15
MaxDisplayContrast&: : 16
IsReadOnly&:(file$) : 17
IsHidden&:(file$) : 18
IsSystem&:(file$) : 19
SetReadOnly:(file$,state&) : 20
SetHiddenFile:(file$,state&) : 21
SetSystemFile:(file$,state&) : 22
VolumeSize&:(drive&) : 23
VolumeSpaceFree&:(drive&) : 24
VolumeUniqueID&:(drive&) : 25
MediaType&:(drive&) : 26
GetFileTime:(file$,DateTimeId&) : 27
SetFileTime:(file$,DateTimeId&) : 28
DisplayTaskList: : 29
SetComputeMode:(State&) : 30
RunApp&:(lib$,doc$,tail$,cmd&) : 31
RunExe&:(name$) : 32
LogonToThread:(threadId&,BYREF statusWord&) : 33
TerminateCurrentProcess:(reason&) : 34
TerminateProcess:(proc$,reason&) : 35
KillCurrentProcess:(reason&) : 36
KillProcess:(proc$,reason&) : 37
PlaySound:(file$,volume&) : 38
PlaySoundA:(file$,volume&,BYREF statusWord&) : 39
StopSound&: : 40
Mod&:(left&,right&) : 41
XOR&:(left&,right&) : 42
LoadRsc&:(file$) : 43
UnLoadRsc:(id&) : 44
ReadRsc$:(id&) : 45
ReadRscLong&:(id&) : 46
CheckUid$:(Uid1&,Uid2&,Uid3&) : 47
SetPointerGrabOn:(WinId&,state&) : 48
MachineName$: : 49
MachineUniqueId:(BYREF high&,BYREF low&) : 50
EndTask&:(threadId&,previous&) : 51
KillTask&:(threadId&,previous&) : 52
GetThreadIdFromOpenDoc&:(doc$,BYREF previous&) : 53
GetThreadIdFromAppUid&:(uid&,BYREF previous&) : 54
SetForeground: : 55
SetBackground: : 56
SetForegroundByThread&:(threadId&,previous&) : 57
SetBackgroundByThread&:(threadId&,previous&) : 58
GetNextWindowGroupName$:(threadId&,BYREF previous&) : 59
GetNextWindowId&:(threadId&,previous&) : 60
SendKeyEventToApp&:(threadId&,previous&,code&,scanCode&,modifiers&,repeats&) : 61
IrDAConnectToSend&:(protocol$,port&) : 62
IrDAConnectToReceive:(protocol$,port&,BYREF statusW&) : 63
IrDAWrite:(chunk$,BYREF statusW&) : 64
IrDARead$: : 65
IrDAReadA:(stringAddr&,BYREF statusW&): 66
IrDAWaitForDisconnect: : 67
IrDADisconnect: : 68
MainBatteryStatus&: :69
BackupBatteryStatus&: :70
CaptureKey&:(keyCode&,mask&,modifier&) :71
CancelCaptureKey:(handle&) :72
SetPointerCapture:(winId&,flags&) :73
ClaimPointerGrab:(winId&,state&) :74
OpenFileDialog$:(seedFile$,uid1&,uid2&,uid3&) : 75
CreateFileDialog$:(seedPath$) : 76
SaveAsFileDialog$:(seedPath$,BYREF useNewFile%) : 77
END DECLARE
ER5 WINS OPXs are not useable on the ER3 EPOC Emulator, and ER3 WINS OPXs will not work on the ER5 Emulator. However, ER5 MARM OPXs will work on ER3 EPOC devices, and ER3 MARM OPXs will work under ER5.
Usage: backLight&=BACKLIGHTON&:
Returns -1 if the backlight is switched on or 0 if it is switched off.
Usage: SETBACKLIGHTON:(state&)
Switches the backlight on if state&=1 or off if state&=0.
Usage: SETBACKLIGHTONTIME:(seconds&)
Sets the time in seconds (seconds&) that the backlight should remain on after it has been switched on.
Usage: SETBACKLIGHTBEHAVIOR:(behavior&)
Sets the backlight’s turning off behaviour.
behavior&=0 sets the turning off of the backlight to be on a timer,
behavior&=1 sets the backlight not to be on a timer.
Usage: ret&=ISBACKLIGHTPRESENT&:
Returns -1 if there is a backlight present and 0 if there is not.
Usage: SETAUTOSWITCHOFFBEHAVIOR:(behavior&)
Sets the machine’s auto switch off behaviour.
|
behavior& |
|
|
0 |
disables the machine’s auto switch off mechanism. |
|
1 |
sets the machine auto switch off to occur only when its batteries are low. |
|
2 |
sets the machines auto switch off to occur always. |
Usage: SETAUTOSWITCHOFFTIME:(seconds&)
Sets the time in seconds (seconds&) for which the machine may remain switched on when it is not being used.
Usage: SETACTIVE:(state&)
Sets the current process active if state&=1 or not active if state&=0. This will determine whether or not the machine can automatically turn off when the user is not using the machine: if the process is active then the machine will not automatically turn off.
Usage: RESETAUTOSWITCHOFFTIMER:
‘Tickles’ the machine’s auto-switch-off timer, restarting its count down to switching off. This is useful when using the serial port for a long task, for example; but use of this feature in a loop when the termination condition is never met can lead to power drain.
Usage: SWITCHOFF:
Switches off the machine.
As with the keyword OFF, you should be careful not to use SWITCHOFF: in a loop. If you do, it may be impossible to switch the machine back on, and you may then have to reset it.
Usage: SETSOUNDENABLED:(state&)
Enables the machine’s sound if state&=1 or disables it if state&=0.
Usage: SETSOUNDDRIVERENABLED:(state&)
Switches the machines sound driver on if state&=1 or off if state&=0.
Usage: SETKEYCLICKENABLED:(state&)
Determines whether or not a keypress makes a click. state&=1 enables the click and state&=0 disables it.
Usage: SETPOINTERCLICKENABLED:(state&)
Determines whether or not a pointer event makes a click. (A pointer event occurs whenever the machine’s screen is pressed.) state&=1 enables the click and state&=0 disables it.
Usage: SETDISPLAYCONTRAST:(value&)
Sets the contrast on the machine’s screen. value& specifies the contrast value, which can be between zero and the maximum display contrast.
See MAXDISPLAYCONTRAST&:.
Usage: maxContrast&=MAXDISPLAYCONTRAST&:
Returns the maximum value to which the machines display contrast can be set.
See SETDISPLAYCONTRAST:.
Usage: readOnly&=ISREADONLY&:(file$)
Returns -1 if the file, file$, is a read-only file and 0 if it is not.
Usage: hidden&=ISHIDDEN&:(file$)
Returns -1 if the file, file$, is hidden by the system and 0 if it is not.
Usage: system&=ISSYTEM&:(file$)
Returns -1 if the file, file$, is a system file and 0 if it is not.
Usage: SETREADONLY:(file$,state&)
Sets the file, file$, to be read only if state&=1 or not read-only if state&=0.
Usage: SETHIDDENFILE:(file$,state&)
Sets the file, file$, to be hidden by the system if state&=1 or not to be hidden if state&=0.
Usage: SETSYSTEMFILE:(file$,state&)
Sets the file, file$, to be a system file if state&=1 or not to be a system file if state&=0.
Usage: VOLUMESIZE&:(drive&)
Returns the size in bytes of the storage space on the drive specified by drive&. drive& can take values 0 to 25. 0 specifies the A:, 1 specifies B:, 2 specifies C: and so on.
Usage: free&=VOLUMESPACEFREE&:(drive&)
Returns the size in bytes of the storage space that is available for use on the drive specified by drive&. drive& can take values 0 to 25. 0 specifies the A:, 1 specifies B:, 2 specifies C: and so on.
Usage: volUid&=VOLUMEUNIQUEID&:(drive&)
Returns the unique identification number of the media on the drive specified by drive&. drive& can take values 0 to 25. 0 specifies the A:, 1 specifies B:, 2 specifies C: and so on.
See MEDIATYPE&:.
Usage: media&=MEDIATYPE&:(drive&)
Returns the media type present on the drive specified by drive&. drive& can take values 0 to 25. 0 specifies the A:, 1 specifies B:, 2 specifies C: and so on. The value returned may be any of the following,
|
value |
meaning |
constant declaration in System.oxh |
|
0 |
no media present |
CONST KMediaNotPresent&=0 |
|
1 |
media unknown |
CONST KMediaUnknown&=1 |
|
2 |
floppy disk |
CONST KMediaFloppy&=2 |
|
3 |
hard disk |
CONST KMediaHardDisk&=3 |
|
4 |
CD-ROM |
CONST KMediaCdRom&=4 |
|
5 |
RAM |
CONST KMediaRam&=5 |
|
6 |
flash |
CONST KMediaFlash&=6 |
|
7 |
ROM |
CONST KMediaRom&=7 |
|
8 |
remote |
CONST KMediaRemote&=8 |
Usage: GETFILETIME:(file$,dateTimeId&)
Returns the time that the file, file$, was last modified into dateTimeId&. It is necessary to pass this procedure the ID of a date/time object which the procedure will then set to the required time. To obtain and read a date/time object, see the ‘Date OPX’ section.
Usage: SETFILETIME:(file$,dateTimeId&)
Sets the time that the file, file$, was last modified to dateTimeId&. It is necessary to pass this procedure the ID of a date/time object which the procedure will use to set the time. To get a date/time object, which provides microsecond accuracy, see Date.opx — Date and time manipulation.
Usage: DISPLAYTASKLIST:
Displays the system-wide task list. The user may then close a file, go to another task or close the dialog.
Usage: SETCOMPUTEMODE:(state&)
Changes the priority control for the current program.
The following values are available for state&:
|
value |
meaning |
constant declaration in System.oxh |
|
0 |
compute mode disabled |
CONST KComputeModeDisabled&=0 |
|
1 |
compute mode on |
CONST KComputeModeOn&=1 |
|
2 |
compute mode off |
CONST KComputeModeOff&=2 |
This puts the current process into compute mode (state&=KComputeModeOn&) or takes it out of compute mode (state&=KComputeModeOff&). In compute mode, a process runs at the lower background priority even when it is the foreground process. Disabling compute mode control (state&=KComputeModeDisabled&) prevents the window server from changing the program’s priority when it moves between background and foreground.
OPL runs in compute mode by default to support simple OPOs which cannot always be assumed to be well-behaved programs.
This default behaviour is necessary because OPL programs would not otherwise give any background programs a chance to run, simply by running in a tight loop. If your program doesn’t run in a tight loop, i.e. if it calls GETEVENT32, GET, etc. regularly, you can use SETCOMPUTEMODE:(KComputeModeOff&).
Note that TBarInit: in Toolbar.opo sets compute mode off, since any program that has a toolbar shouldn’t be running in a tight loop at any time. (See Toolbars.)
Usage: thread&=RUNAPP&:(lib$,doc$,tail$,cmd&)
Runs an application and returns a thread ID for the application. The thread ID can be used to logon to the application, to find out when and why it finished. This ID can also be used to locate the window group, end the task etc.
lib$ is the C++ application name.
doc$ is the document name, if any, to pass to the application.
tail$ is the tail end, needed only by certain applications such as OPL.
cmd& can take values:
|
value |
meaning |
|
0 |
open |
|
1 |
create |
|
2 |
run |
|
3 |
background |
The values 0, 1 and 2 are the same as for CMD$(3) (see Keyword Reference). The value 3 will run the application in the background.
For example, to run an OPL program:
k&=RUNAPP&:("OPL","","RZ:\System\Opl\Toolbar.opo",2)
Note that tail$ contains a leading R: this is required by OPL.
To open the Data help file:
k&=RUNAPP&:("Data","Z:\System\Data\Help","",0)
See also OPL applications.
See LOGONTOTHREAD:.
Usage: RUNEXE&:(file$)
Runs an executable EXE file file$ and returns its thread ID. The thread ID can then be used to logon to the thread and find out when and why it finished.
See LOGONTOTHREAD:.
Usage: LOGONTOTHREAD:(threadId&,statusWord&)
Logs on to the thread with ID threadId& and sets the status word statusWord& when the thread has completed. As for other 32-bit status words, statusW& will be set to &80000001 for pending and 0 for successful completion.
Usage: TERMINATEPROCESS:(reason&)
Terminates the current process giving it the reason reason&. This causes the process to receive a shutdown message. reason& may take any value, with zero used to mean no errors.
Usage: TERMINATEPROCESS:(proc$,reason&)
Terminates the process proc$ giving it the reason reason&. This causes the process to receive a shutdown message. reason& may take any value, with zero used to mean no errors.
Usage: KILLCURRENTPROCESS:(reason&)
Kills the current process giving it the reason reason&. The process is killed without receiving a shutdown message. reason& may take any value, with zero used to mean no errors.
Usage: KILLPROCESS:(proc$,reason&)
Kills the process proc$ giving it the reason reason&. The process is killed without receiving a shutdown message. reason& may take any value, with zero used to mean no errors.
Usage: PLAYSOUND:(file$,volume&)
Plays the file file$, which may be a sound file or an alarm file. Does not return until the sound has completed.
volume& specifies the volume at which the file should be played, 0 specifies no volume and 3 specifies maximum volume. The play will be synchronous (i.e. the OPL program will stop running until the file has finished playing). For asynchronous sound playing see PLAYSOUNDA:.
Usage: PLAYSOUNDA:(file$,volume&,statusWord&)
Plays the file file$, which may be a sound file or an alarm file, asynchronously. It returns immediately, with the status word being set on completion or cancellation of the sound.
volume& specifies the volume at which the file should be played, 0 specifies no volume and 3 specifies maximum volume. The play will be asynchronous (i.e. the OPL program will continue running while the sound file is playing). statusWord& is the variable which will contain information about the state of the sounds file play. For synchronous sound playing see PLAYSOUND:.
It should be noted that the asynchronous signal must always be consumed with any of IOYIELD, IOWAIT or IOWAITSTAT32 before another PLAYSOUNDA: or PLAYSOUND: is used.
Usage: STOPSOUND&:
Stops the sound file that is currently playing. The return value is 1 if there was a sound file playing and 0 if not.
See PLAYSOUND:, PLAYSOUNDA:.
Usage: rem&=MOD&:(left&,right&)
Returns left& modulo right& (i.e. the remainder of left& divided by right&).
Usage: res&=XOR&:(left&,right&)
Returns the exclusive OR of left& and right&. A bit in the result has value 1 if the corresponding bit is set in either left& or in right&, but not in both, otherwise it is 0.
E.g. with left&=5 (binary 00000101) and right&=3 (binary 00000011), XOR&:(left&,right&) returns 6 (binary 00000110).
|
left& |
00000101 |
|
right& |
00000011 |
|
XOR&:(left&,right&) |
00000110 |
This is often used to invert particular bits in an integer. So left&=XOR&:(left&,3) inverts bits 0 and 1 in left&, where bit 0 is the rightmost bit, and leaves the other bits alone.
Usage: id&=LOADRSC&:(file$)
Loads the resource file file$ and returns a handle for it.
See UNLOADRSC:, READRSC$:.
Usage: UNLOADRSC:(id&)
Unloads the resource file whose handle is id&.
See LOADRSC&:.
Usage: string$=READRSC$:(id&)
Reads the resource in a resource file specified by id& which must already be loaded.
See LOADRSC&:.
Usage: long&=READRSCLONG&:(id&)
Reads a 32-bit value from a resource file specified by the id& which must already be loaded.
See LOADRSC&:.
Usage: CHECKUID$:(Uid1&,Uid2&,Uid3&)
Returns a string which is a unique product of the three supplied UIDs.
Usage: SETPOINTERGRABON:(WinId&,state&)
Enables (or disables) pointer grabs in a window. After this function has been called with state&=1, any "down" event in this window will cause a pointer grab, terminated by the next corresponding "up" event. The terminating "up" event is also sent to the window with the grab.
This function would typically be used for "drag-and-drop", and would typically be called after window creation so that pointer grab is enabled for the lifetime of the window.
state&=0 disables the grab.
See CLAIMPOINTERGRAB:.
Usage: name$=MACHINENAME$:
Returns the machine name.
Usage: MACHINEUNIQUEID:(BYREF high&,BYREF low&)
Sets high& and low& (which are passed BYREF) to high and low parts of the machine's unique ID.
Usage: ret&=ENDTASK&:(threadId&,previous&)
Sends a shutdown message to a window group in the thread, threadId&.
previous& specifies the window group in the thread that is previous to the one required. Hence, setting previous& to 0 will specify the first window group in the thread.
The value returned by this procedure is the value of the window group on which action was taken, or -1 if a window group following that specified by previous& was not present. This return value could be passed back to this procedure to end the next window group in the thread.
An error will be raised if the window group is busy, does not respond to such requests or is in a system thread.
See KILLTASK&:.
Usage: ret&=KILLTASK&:(threadId&,previous&)
Shuts down the window group that follows the window group specified by previous& in the thread, threadId&. It will ignore any wishes of the window group not to be shutdown.
The value returned by this procedure is the value of the window group on which action was taken, or -1 if a window group following that specified by previous& was not present. This return value could be passed back to this procedure to end the next window group in the thread.
See ENDTASK&:.
Usage: threadId&=GETTHREADIDFROMOPENDOC&:(doc$,BYREF previous&)
Returns the thread ID threadId& of the thread that contains the open document doc$.
doc$ should contain the full path of the open document and could for example be c:\opl\prog.opo.
previous&, passed by reference, is useful for situations where the document may be open more than once. Setting previous& to zero will cause this procedure to find the first window group that contains doc$. If one is found, previous& will be set to the window group value of that found document. This value could then passed back to this procedure as previous&, so the next window group instance of doc$ will be found, and so on. If this procedure sets previous& to -1 then doc$ could not be found after previous&. An error will also be raised if the open document is not found.
Usage: threadId&=GETTHREADIDFROMAPPUID&:(uid&,BYREF previous&)
Returns the thread ID threadId& of the thread that contains a running instance of the application with UID uid&.
previous&, passed by reference, is useful for situations where the application may be running more than once. Setting previous& to zero will cause this procedure to find the first window group that is an instance of this application. If one is found, previous& will be set to the value of that window group. This value could then passed back to this procedure as previous&, so the next instance of the application can be found, and so on. If no instance of this application can be found following previous& then previous& will be set to -1. An error will also be raised if a running instance of the application is not found.
Usage: SETFOREGROUND:
Moves the calling process to foreground.
See SETBACKGROUND:.
Usage: SETBACKGROUND:
Moves the calling process to background.
See SETFOREGROUND:.
Usage: ret&=SETFOREGROUNDBYTHREAD&:(threadId&,previous&)
Moves the window group after previous& in the thread threadId& to foreground. Using previous&=0 specifies the first window group in the thread.
The value returned will be the window group on which action was taken, or -1 if the following window group was not found. This return value could be passed back to this procedure as previous& to put the next window group in threadId& to foreground.
See SETBACKGROUNDBYTHREAD&:.
Usage: ret&=SETBACKGROUNDBYTHREAD&:(threadId&,previous&)
Moves the window group after previous& in the thread threadId& to background. Using previous&=0 specifies the first window group in the thread.
The value returned will be the window group on which action was taken, or -1 if the following window group was not found. This return value could be passed back to this procedure again as a value for previous& to put the next window group in threadId& to background.
See SETFOREGROUNDBYTHREAD&:.
Usage: name$=GETNEXTWINDOWGROUPNAME$:(threadId&,BYREF previous&)
Returns the name of the window group that follows the window group previous& in the thread threadId&. If previous&=0 the procedure will return the name of the first window group found.
See GETNEXTWINDOWID&:.
Usage: winId&=GETNEXTWINDOWID&:(threadId&,BYREF previous&)
Returns the ID of the window group that follows the window group previous& in the thread threadId&. If previous& is 0 the procedure will return the ID of the first window group found.
See GETNEXTWINDOWGROUPNAME$:.
Usage: SENDKEYEVENTTOAPP&:(threadId&,previous&,code&,scanCode&, modifiers&,repeats&)
Sends a key event to the window group (application) that follows the window group with ID previous& (or the first window group if previous&=0), in the thread with ID threadId&. The key event is specified by code&, scanCode&, modifiers& and repeats&.
The value returned is the window group to which the key was sent.
Usage: IRDACONNECTTOSEND&:(protocol$,port&)
Synchronously sends out an infrared (IR) beam which looks for another infrared device. If another infrared device is looking to receive a beam then the devices will connect, otherwise this procedure will raise an error after a couple of seconds.
protocol$ can take either of the constants defined in System.oxh. These are KIrTinyTP$, used for communicating with other EPOC devices and KIrmux$ which is used for IR printing.
The value 8 is recommended for port& when communicating with other EPOC devices. Both devices will need to be using the same value for port&. port& must be 2 for connecting to IR printers.
If connecting to another EPOC device with this procedure the other device must connect by using IRDACONNECTTORECEIVE&:.
After connecting to another EPOC device you can both send and receive information.
After connecting to an IR printer use IRDAWRITE: to send text. When IRDADIASCONNECT: is called the printer will begin printing.
See IRDACONNECTTORECEIVE:, IRDAWRITE:, IRDAREAD:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:.
Usage: IRDACONNECTTORECEIVE:(protocol$,port&,BYREF statusW&)
Asynchronously waits, without timing-out, for another EPOC device to attempt to connect via infrared (IR). This procedure takes the status word statusW&. When connection occurs the status word is set to zero.
Both EPOC devices must be using the same port which is specified by port&. The recommended port is 8.
One of the devices must connect with this procedure and the other with IRDACONNECTTOSEND&.
protocol$ specifies the IR protocol and should take the constant KIrTinyTP$, defined in System.oxh, when communicating with other EPOC devices.
After connecting to another EPOC device you can both send and receive information.
See IRDAWRITE:, IRDAREAD:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:.
Usage: IRDAWRITE:(chunk$, BYREF statusW&)
Sends a string chunk$ via infrared to another device after connection has been made. The procedure is asynchronous and the success of sending the string is reported in statusW&.
See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDAREAD:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:.
Usage: chunk$=IRDAREAD$:
Reads a text string via infrared from another device after connection has been made. The procedure is synchronous.
See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDWRITE:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:.
Usage: IRDAREADA:(stringAddr&, BYREF statusW&)
Reads a text string via infrared from another device after connection has been made. The procedure is asynchronous with status word statusW&. The string passed by address should have a maximum length of 255 bytes. To pass a string by address use, ADDR(string$).
See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDWRITE:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:.
Usage: IRDAWAITFORDISCONNECT:
Verifies, when disconnecting from another IR device, that the other device has received everything sent. It should therefore be called by the device that last sends some information.
This procedure should not be used with printers: use IRDADISCONNECT: instead.
See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:.
Usage: IRDADISCONNECT:
Disconnects from another IR device. It should be called by the device that is the last to receive some information. IRDAWAITFORDISCONNECT: is used by the last device to send some information, except when printing via IR when IRDADISCONNECT: should be used to disconnect from the printer and commence printing.
See IRDACONNECTTOSEND&:, IRDACONNECTTORECEIVE:, IRDADISCONNECT:, IRDAWAITFORDISCONNECT:.
Usage: MAINBATTERYSTATUS&:
Returns the current power of the main batteries. The following possible return values are supplied as constants in System.oxh:
CONST KBatteryZero&=0
CONST KBatteryVeryLow&=1
CONST KBatteryLow&=2
CONST KBatteryGood&=3
Usage: BACKUPBATTERYSTATUS&:
Returns the current power of the backup batteries. The following possible return values are supplied as constants in System.oxh:
CONST KBatteryZero&=0
CONST KBatteryVeryLow&=1
CONST KBatteryLow&=2
CONST KBatteryGood&=3
Usage: CAPTUREKEY&:(keyCode&,mask&,modifier&)
Allows the program that calls it to capture keys when it is not in foreground. The keys to be captured are specified using keycode&, mask& and modifier&. The value returned is a handle which can be passed to CANCELCAPTUREKEY: to cancel the capture.
The following constants are supplied in System.oxh to be used in conjunction with this procedure:
CONST KModifierAutorepeatable&=&00000001
CONST KModifierKeypad&=&00000002
CONST KModifierLeftAlt&=&00000004
CONST KModifierRightAlt&=&00000008
CONST KModifierAlt&=&00000010
CONST KModifierLeftCtrl&=&00000020
CONST KModifierRightCtrl&=&00000040
CONST KModifierCtrl&=&00000080
CONST KModifierLeftShift&=&00000100
CONST KModifierRightShift&=&00000200
CONST KModifierShift&=&00000400
CONST KModifierLeftFunc&=&00000800
CONST KModifierRightFunc&=&00001000
CONST KModifierFunc&=&00002000
CONST KModifierCapsLock&=&00004000
CONST KModifierNumLock&=&00008000
CONST KModifierScrollLock&=&00010000
CONST KModifierKeyUp&=&00020000
CONST KModifierSpecial&=&00040000
CONST KModifierDoubleClick&=&00080000
CONST KModifierPureKeycode&=&00100000
CONST KAllModifiers&=&001fffff
See CANCELCAPTUREKEY&:.
Usage: CANCELCAPTUREKEY:(handle&)
Cancels an outstanding key capture which is specified by the handle handle&.
See CAPTUREKEY&:.
Usage: SETPOINTERCAPTURE:(WinId&,flags&)
Sets the (OPL) window with window ID winId& to capture pointer events.
flags& can take a summed combination of the following:
|
value |
meaning |
|
0 |
capture disabled |
|
&01 |
capture enabled |
|
&02 |
capture (not drag-and-drop) |
When a window captures pointer events, the position of any events received will be relative to its origin, i.e. the top left corner of that window, i.e. the window’s 0,0 co-ordinate becomes the origin for pointer events. Events don’t need to be inside the window to be registered. For example, if the screen was touched 1 pixel above and 1 pixel to the left of a window that was capturing pointer events, the pointer event would be returned with the position of the event being -1,-1 .
"Capture (not drag-and-drop)" will cause events of the "drag-and-drop" nature to be sent to the window that would have received them had the pointer not been captured..
Usage: CLAIMPOINTERGRAB:(WinId&,state&)
Claims the pointer grab for the window with ID winId& from another window, if a pointer grab is already in effect in the other window. All subsequent events will be delivered to this window, instead of the window that originally had the pointer grab. The next "up" event terminates the pointer grab, and is also delivered to the window that claimed the grab, if state& is set to 1.
This function would typically be used where clicking in a window pops up another window, and where the popped-up window wishes to grab the pointer as though the original click had been in that window.
To summarise the values of state& for the OPL window,
|
value |
meaning |
|
0 |
don't deliver the following "up" event to this window |
|
1 |
deliver the following "up" event to this window |
See SETPOINTERGRABON:
Usage: file$=OPENFILEDIALOG$:(seedFile$,uid1&,uid2&,uid3&)
Displays the standard ‘Open file’ dialog. seedFile$ provides a starting file which is displayed when the dialog is opened. So, for example, if seedFile$="C:\Documents\Myfile" then the file MyFile will be initially displayed in the ‘Name’ selector box, the Documents folder will be initially displayed in the ‘Folder’ selector box and C will be displayed in the disk selector. You must always seed the dialog: you cannot pass a null seedFile$ string to OPENFILEDIALOG$:. If seedFile$ does not include a drive name, then an error is raised.
The selection of files may be restricted by UID by specifying appropriate values for uid1&, uid2& and uid3& in exactly the same way as when using the dFILE keyword. See the ‘Alphabetic Listing’ section for details of this.
The return value is the filename, including the full path of the file selected to be opened.
Usage: file$=CREATEFILEDIALOG$:(seedPath$)
Displays the standard ‘Create new file’ dialog. seedPath$ provides a starting path which is displayed when the dialog is opened. So, for example, if seedPath$="C:\Documents\" then the Documents folder will be intially displayed in the ‘Folder’ selector box and C in the disk selector. If you supply a filename in seedPath$, then this will be displayed as a suggested filename in the ‘Name’ selector box. You must always seed the dialog: you cannot pass a null seedPath$ string to CREATEFILEDIALOG$:. If seedPath$ does not include a drive name, then an error is raised.
The return value is the filename, including the full path of the file to be created.
Usage: path$=SAVEASFILEDIALOG$:(seedPath$,BYREF useNewFile%)
Displays the standard ‘Save as’ dialog. seedPath$ provides a starting path which is displayed when the dialog is opened. So, for example, if seedPath$="C:\Documents\" then the Documents folder will be initially displayed in the ‘Folder’ selector box and C in the disk selector. If you supply a filename in seedPath$, then this will be displayed as a suggested filename in the ‘Name’ selector box. You must always seed the dialog: you cannot pass a null seedPath$ string to SAVEASFILEDIALOG$:. If seedPath$ does not include a drive name, then an error is raised.
UseNewFile% specifies the initial setting of the checkbox which determines whether a new file should be used when saving. This value is non-zero then the tick will be set initially, if it is zero, then it will not be. The procedure writes back a value to this variable which will be KTrue% if the symbol is set on exiting the dialog and KFalse% if not (see Const.oph). If you pass #0 as the value of this argument, then this item will not be displayed in the dialog at all (as in many EPOC applications) so that whether a new file is used on not is not decided by the user, but by the programmer.
The return value is the filename to save as, including the full path.
|
|
|
|
|
|