WebLink
=======

version 0.00 4 Dec 1996 Gert-Jan de Vos, devos@eb.ele.tue.nl

WebLink is FreeWare, use the code in anyway you like, but please only
distribute the original set of files.


What is it?
-----------
A couple of days ago, David McCormack proposed a very good idea on the
comp.sys.acorn newsgroups. The idea is to somehow provide an URL link in the
info box of applications. By clicking on this link, the author of the
software can provide up to date versions and docs for that application. Most
people are very positive about this idea and it may become a new standard
for RISC OS applications. A standard way to provide the links is still under
discussion on the newsgroups at this moment.

My idea was to implement the click-link functionality in a module. It is
then possible to add links by just adding the required URLs to the Template
definitions. The module can then send the URL request to a suitable
application. My preliminary result is this:

WebLink   - The module.
!WebLink  - A simple application which has some links in its info box.
!ReadMe   - What WebLink is all about.
ModSource - The source of the module.

WebLink only requires the WebLink module to be loaded. It takes up 396 bytes
of module and 256 bytes of workspace. It is not much use however if a
webbrowser is not loaded also (which is usually a bit bigger).


How to use it
-------------
If you know how to use a template editor, you can add links to any icon you
like. Suppose you have selected the icon you want to link to
www.acorn.co.uk:

- Make sure the icon is clickable: set its buton type to Click.
- Make sure the icon has a validation string: select the 'Text' and
  'Indirected' flags.
- Add the URL to the validation string: Uhttp://www.acorn.co.uk

This is enough to make WebLink send a message when you click the icon. You
will probably also want to indicate to the user that this icon is a link. I
think the following steps are a good way to do that:

- If it is a text icon, set the foreground colour to dark blue (8).
- If the link is indicated by an icon, you may like to have a look at:
  http://www.aberry.demon.co.uk/icons/
  This site gives the latest news on the attempt to design a standard link
  icon for use in the info box.

- Add Pptr_link to the validation string. An example ptr_link sprite is in
  the !WebLink demo application's !Sprites file.

Note that the total size of indirected data can increase considerably when
adding URLs to an existing Template file. This may cause problems when you
try to update an existing application. The code will probably set aside a
certain fixed size buffer for indirected data. If you add more, it will fail
to load the Templates. You can either try to decrease the size of indirected
data in the Templates until it just loads, or try to patch the !RunImage.


How the module works
--------------------
It is simple really. The module sets up a WimpPostFilter for click events.
Whenever a click is received, the module checks if it is a click on a valid
icon which has a validation string. Then the validation string is scanned
for a 'U' command of URL. If a 'U' command is found, anything following the
U up to the end of the validation string or the next command, is copied to a
message block. This message with message code &4AF80 is then broadcast. This
message is the standard way to request an URL fetch from any RISC OS web
browser. The URL is included in the message as an ASCII-0 terminated string
at offset 20 in the message block. If a web browser is loaded, it will start
to fetch the requested URL.


Remaining problems
------------------
- I'm not sure if the 'U' validation command is not in use by any of the
  wimp extension modules around. If it is, can anyone tell me a free command
  which sounds reasonable as an URL specifier? Maybe 'W' from web? It is
  easy to reassemble ModSource with another validation string command if you
  like.
- The filter reacts on any click. This makes editing the templates quite
  fun! Maybe it should ignore Menu and Shift, Ctrl or Adjust clicks?
- What if no application which handles the fetch request message is running?
  As it is now, nothing happens. Maybe it is logical to assume the user only
  wants to fetch the link when the browser is running, and the machine is
  online. It would also be possible to somehow launch an appropriate
  application. According to the latest news, ART are working on a standard
  way to launch URL handling applications. It's best to wait for their
  proposal, it may just replace this system completely.
