Teletext Wimp Messages (&51C46)

A Wimp message interface was introduced with version 1.51 to allow the software to be controlled by an external application.

The message action is &51C46. This is part of the message block (officially) allocated to me for "BudgieMgr"; however by using an extra marker word, I can make the block &51C40-&51C7F support 64 different applications!
The codes described below are written to block%!20. Refer to the example for more details.

Messages TO !Teletext...

0 - Teletext_Enquiry

If Teletext is present, it'll reply with message 20.

1 - Teletext_RunScript

$(block%+24) is the null terminated name of the script to run.
The script MUST be present in the Teletext scripts directory.
Begins running the script if it is found and is not already running a script.
If a script is run, Teletext sends message 21 (and does not, if no script is run).

2 - Teletext_Channel

block%!24 = New channel (1-9)

block%!28 = 0

This selects a channel. If you want to retune the channel, set block%!28 to a value from 21 to 69 (the UHF channel). The fine tuning value is always set to zero.

3 - Teletext_FindPage

block%!24 = Page number in &xxx form (ie, p100 is &100 not 100).
This sets Teletext searching for a page.
Teletext replies with message 23 when page found.

4 - Teletext_TransferPage

block%!24 = Pointer to 1080 byte block to transfer page into.
This transfers the current page into your memory block.

5 - Teletext_CacheOp

block%!24 = Cache tidy operation:
  0 - Tidy the cache (remove expired pages).
  1 - Flush the cache (remove EVERYTHING).

This performs operations on the Teletext cache.

Messages FROM !Teletext...

20 - Teletext_Status

block%!24 = &58545452 ("RTTX"), check word.
block%!28 = Teletext version * 100
block%!32 = Script version * 100
block%!36 = Current channel (1-9)
block%!40 = Current page simple (&xxxyyyy form)
block%!44 = Flags:
              bit 0 - Set if running a script
              bit 1 - Set if in configuration mode
              bit 2 - Set if browser is open [not implemented]
              bit 3 - Set if cache is in use

This is sent in response to a Teletext_Enquiry request.

21 - Teletext_RunningScript

$(block%+24) = Name of script being executed (in scripts directory).
This is broadcast when Teletext runs a script.

22 - Is not used.

23 - Teletext_PageFound

block%!24 = Page number, in &xxxyyyy form.
This is broadcast whenever a page is downloaded.

24 - Is not used.

25 - Is not used.

The message system...

The message system is primarily to allow you to write simple programs to fire off scripts at certain times, like fetch the news hourly, and the channel/page stuff was added for good measure. Channel changes and page requests behave as if you typed them into the viewer, or clicked the control panel - they are NOT transparent activities.
The replies are broadcasts. No reply, except Teletext_Status is sent back specifically to the callee; but do not assume this behaviour.

The messages to !Teletext have been tested, those back from !Teletext have not been tested yet.

Please note that !Teletext will not include a 'cron' or 'alarm' system. There is plenty of software that can run a task at a defined, possibly repetetive, time...and it isn't difficult to cobble together an application to fire off the appropriate Wimp messages.

Wimp message example...

REM >WIMPmsgEX
REM
REM by Rick Murray, 22nd June 2003
REM
REM This is an example program that will communicate
REM with !Teletext using the Wimp message protocol
REM to:
REM   a. Tidy the cache
REM and:
REM   b. Run the "!startup" script.
REM

DIM block% 256

REM Begin...
SYS "Wimp_Initialise", 200, &4B534154, "WIMPmsgEX" TO ,task%

REM The WIMP sends us a few messages (ie, can this
REM app cope with resizable slot, etc etc) so we'll
REM poll until we get a non-event event.
REPEAT
  SYS "Wimp_Poll", 0, block% TO reason%
UNTIL reason% = 0
REM (we aren't a 'real' WIMP app, so we'll just
REM  ignore anything the WIMP asks of us...)

REM First, tidy the cache.
block%!0  = 28
block%!12 = 0
block%!16 = &51C46
block%!20 = 5
block%!24 = 0 : REM or '1' to flush the cache
SYS "Wimp_SendMessage", 17, block%, 0, 0

REM Poll a few times, let's say ten times.
FOR loop% = 0 TO 9
  SYS "Wimp_Poll", 0, block% TO reason%
NEXT

REM Now get the script running. ALL scripts must be
REM relative to "<Teletext$Scripts>". This script
REM name is actually 'poked' into the script array,
REM so you can generate scripts on-the-fly and then
REM run them...without needing to re-start !Teletext
REM to force a script re-scan. As long as the script
REM exists, it'll be okay.
block%!0  = 256
block%!12 = 0
block%!16 = &51C46
block%!20 = 1
$(block%+24) = "!startup"
SYS "Wimp_SendMessage", 17, block%, 0, 0

REM Well, that's it. Playtime's over.
SYS "Wimp_CloseDown", task%, &4B534154
END

Return to Teletext software index