RISC OS Front-End

Since there's been some discussion over in the ROOL forums about the RISC OS
front-end, it might be useful to provide some kind of overview of how it's
structured.

Remember that the RISC OS front-end is a work in progress: there's been a
lot of restructuring done to tidy things up, but there's a lot still to do.
Some parts have had copious amounts of sticky-tape applied to keep them
working while bits around them have been updated.

This is really only scratching the surface. If (when) there are any
questions, please ask: this list is probably the best place, but it might
take a couple of days for me to reply if I'm busy.

Anyway, here goes... I've found the handy guide that JMB gave me back in
2009

http://listmaster.pepperfish.net/pipermail/netsurf-dev-netsurf-browser.org/2009-August/001472.html

and updated it to reflect where things are at present.

In the NetSurf source, the RISC OS front-end lives in netsurf/riscos/. At
present, the files in there look something like this:

> -rw-rw-r-- 1 steve steve 6399 Mar 2 19:56 401login.c

HTTP authentication dialogue.

> -rw-r--r-- 1 steve steve 1183 Feb 24 2013 assert.c

Implementation of a custom assertion function that opens the log file in
a text editor.

> -rw-rw-r-- 1 steve steve 13658 Mar 2 19:56 bitmap.c
> -rw-r--r-- 1 steve steve 1211 Oct 3 2013 bitmap.h

Representation of a bitmap image. Will be plotted with Tinct.

> -rw-r--r-- 1 steve steve 7575 Jun 9 2014 buffer.c
> -rw-r--r-- 1 steve steve 965 Feb 24 2013 buffer.h

Redraw buffering (redirects to a sprite, then blits the sprite)

> drwx------ 2 steve steve 4096 Mar 2 19:56 configure

Directory containing implementation of configuration dialogues. I'll
return to this later.

> -rw-r--r-- 1 steve steve 11812 Jun 9 2014 configure.c
> -rw-r--r-- 1 steve steve 996 Oct 3 2013 configure.h

Implementation of the main configuration filer-like window.

> drwx------ 2 steve steve 4096 Jun 9 2014 content-handlers

Handlers for different types of page content (drawfile, sprite, ArtWorks).

> -rw-r--r-- 1 steve steve 10165 Jun 9 2014 cookies.c
> -rw-r--r-- 1 steve steve 1173 Oct 3 2013 cookies.h

RISC OS wrapper around the core's cookie viewer.

> -rw-rw-r-- 1 steve steve 22213 Mar 2 19:56 dialog.c
> -rw-r--r-- 1 steve steve 1993 Jun 9 2014 dialog.h

Implementation of generic dialogue boxes. Also includes a bunch of other
UI stuff that probably shouldn't be in here.

> drwx------ 5 steve steve 4096 Mar 2 19:56 distribution

The files that go into a download archive alongside !NetSurf itself.

> -rw-rw-r-- 1 steve steve 44555 Mar 2 19:56 download.c

Download window implementation.

> -rw-r--r-- 1 steve steve 9011 Jun 9 2014 filetype.c
> -rw-rw-r-- 1 steve steve 3268 Mar 2 19:56 filetype.h

Miscellaneous filetype functions -- maps RISC OS filetypes to NetSurf
content types and vice versa.

> -rw-rw-r-- 1 steve steve 15907 Mar 2 19:56 font.c
> -rw-r--r-- 1 steve steve 1437 Jun 9 2014 font.h

Font handling. Mostly a veneer over RUfl.

> -rw-rw-r-- 1 steve steve 11443 Mar 2 19:56 global_history.c
> -rw-r--r-- 1 steve steve 1272 Oct 3 2013 global_history.h

RISC OS wrapper around the core's global history viewer.

> drwx------ 2 steve steve 4096 Mar 2 19:56 gui

Directory containing gui widget implementations. I'll return to this
later, too.

> -rw-rw-r-- 1 steve steve 62862 Mar 2 19:56 gui.c
> -rw-rw-r-- 1 steve steve 8198 Mar 2 19:56 gui.h

Most of the generic GUI code. Includes Wimp_Poll(Idle) calls and a bunch
of message handling. Probably contains other odds and sods, too. Again,
could usefully be split up into multiple files.

> -rw-rw-r-- 1 steve steve 10550 Mar 2 19:56 help.c
> -rw-r--r-- 1 steve steve 1038 Feb 24 2013 help.h

RISC OS help protocol implementation.

> -rw-rw-r-- 1 steve steve 8988 Mar 2 19:56 history.c

Local history window UI -- most logic is in the core.

> -rw-rw-r-- 1 steve steve 19042 Mar 2 19:56 hotlist.c
> -rw-r--r-- 1 steve steve 1641 Jun 9 2014 hotlist.h

RISC OS wrapper around the core's global hotlist viewer.

> -rw-rw-r-- 1 steve steve 6687 Mar 2 19:56 iconbar.c
> -rw-r--r-- 1 steve steve 971 Feb 24 2013 iconbar.h

Implementation of the iconbar icon and menu.

> -rw-rw-r-- 1 steve steve 6824 Mar 2 19:56 image.c
> -rw-r--r-- 1 steve steve 1205 Feb 24 2013 image.h

Bitmap image redraw code -- provides a veneer over Tinct/OS_SpriteOp.

> -rw-r--r-- 1 steve steve 996 Jun 9 2014 Makefile.defaults
> -rw-rw-r-- 1 steve steve 5767 Mar 2 19:56 Makefile.target

> -rw-rw-r-- 1 steve steve 26465 Mar 2 19:56 menus.c
> -rw-r--r-- 1 steve steve 4492 Jun 9 2014 menus.h

Implementation of core menu functions. It provides the code to build OS menu
structures from their definitions, display them and pass events on to
wimp_event.c for sending out to menu clients. Fairly tangled and unpleasant,
and a work in progress.

> -rw-rw-r-- 1 steve steve 6341 Mar 2 19:56 message.c
> -rw-r--r-- 1 steve steve 1513 Feb 24 2013 message.h

Generic dispatch and routing of Wimp messages to handler functions. Note
that older clients bypass this and still hang themselves directly off the
switch statement in ro_gui_user_message().

> -rw-rw-r-- 1 steve steve 8293 Mar 2 19:56 mouse.c
> -rw-rw-r-- 1 steve steve 3270 Mar 2 19:56 mouse.h

Routines for providing mouse tracking events to interested clients:
entering, movement over and leaving windows; drags.

> -rw-r--r-- 1 steve steve 2476 Jan 2 2014 options.h

RISC OS frontend specific options. These are loaded and saved by the
core options code.

> -rw-r--r-- 1 steve steve 1436 Feb 24 2013 oslib_pre7.h

Compatibility header for versions of OSLib before OSLib 7.00 (i.e. all
current OSLib releases).

> -rw-r--r-- 1 steve steve 8203 Feb 24 2013 palettes.c
> -rw-r--r-- 1 steve steve 1095 Feb 24 2013 palettes.h

Default sprite palettes.

> -rw-rw-r-- 1 steve steve 13790 Mar 2 19:56 plotters.c

Drawing primitives. These functions are called by the core when it's
redrawing something.

> -rw-rw-r-- 1 steve steve 25670 Mar 2 19:56 print.c
> -rw-r--r-- 1 steve steve 1104 Jun 9 2014 print.h

Printing UI and RISC OS printing protocol implementation.

> -rw-r--r-- 1 steve steve 10574 Jun 9 2014 query.c
> -rw-r--r-- 1 steve steve 1573 Jun 9 2014 query.h

Query dialogues (e.g. "There are downloads remaining, are you sure you
want to quit?")

> -rw-rw-r-- 1 steve steve 37865 Mar 2 19:56 save.c
> -rw-rw-r-- 1 steve steve 1881 Mar 2 19:56 save.h

Save dialogue and drag&drop protocol implementation.

> -rw-rw-r-- 1 steve steve 11702 Mar 2 19:56 save_draw.c
> -rw-r--r-- 1 steve steve 945 Feb 24 2013 save_draw.h

Draw export implementation.

> -rw-r--r-- 1 steve steve 1643 Feb 24 2013 save_pdf.c
> -rw-r--r-- 1 steve steve 970 Feb 24 2013 save_pdf.h

PDF export frontend binding.

> -rw-rw-r-- 1 steve steve 3712 Mar 2 19:56 schedule.c

Callback scheduler (used for e.g. animated gif redraw)

> drwx------ 2 steve steve 4096 Mar 2 19:56 scripts

Directory containing obey scripts which need preprocessing before they
can be used.

> -rw-rw-r-- 1 steve steve 13166 Mar 2 19:56 search.c

Free-text search UI which wraps around the core search functionality.

> -rw-r--r-- 1 steve steve 742 Feb 24 2013 searchweb.c

Unused?

> -rw-rw-r-- 1 steve steve 9602 Mar 2 19:56 sslcert.c
> -rw-r--r-- 1 steve steve 1064 Jun 9 2014 sslcert.h

SSL certificate verification failed dialogue.

> drwx------ 2 steve steve 4096 Mar 2 19:56 templates

Directory containing templates files in text form for processing with
CCres. To edit these, run CCRes over them to convert to Template format,
edit with your favourite template editor, then convert back to text.

> -rw-rw-r-- 1 steve steve 29284 Mar 2 19:56 textarea.c
> -rw-r--r-- 1 steve steve 1838 Feb 24 2013 textarea.h

Generic UTF-8 textarea implementation. The core now has one of these, so
this one should disappear (or become a very thin veneer over the core
implementation)

> -rw-rw-r-- 1 steve steve 16653 Mar 2 19:56 textselection.c
> -rw-r--r-- 1 steve steve 1810 Apr 5 2014 textselection.h

Text selection implementation.

> -rw-rw-r-- 1 steve steve 19759 Mar 2 19:56 theme.c
> -rw-r--r-- 1 steve steve 3856 Feb 24 2013 theme.h

UI themeing. Much voodoo that the current developers have never
comprehended.

> -rw-rw-r-- 1 steve steve 6094 Mar 2 19:56 theme_install.c

Theme installation.

> -rw-rw-r-- 1 steve steve 10138 Mar 2 19:56 thumbnail.c
> -rw-r--r-- 1 steve steve 952 Feb 24 2013 thumbnail.h

Thumbnail image management.

> -rw-r--r-- 1 steve steve 4524 Feb 24 2013 tinct.h

Tinct API.

> -rw-rw-r-- 1 steve steve 46156 Mar 2 19:56 toolbar.c
> -rw-rw-r-- 1 steve steve 13888 Mar 2 19:56 toolbar.h

Implementation of widget-based toolbars, as used by the browser, hotlist,
history and cookies windows. The widgets themselves live inside gui/

> -rw-r--r-- 1 steve steve 33866 Jun 9 2014 treeview.c
> -rw-r--r-- 1 steve steve 1813 Sep 7 2013 treeview.h

A wrapper around the core's treeview support, to make it work in a RISC OS
window.

> -rw-rw-r-- 1 steve steve 24671 Mar 2 19:56 ucstables.c
> -rw-r--r-- 1 steve steve 1089 Apr 5 2014 ucstables.h

Lookup tables for conversion from Unicode to legacy 8bit character sets.
Also utility functions to convert text to/from the current system
alphabet.

> -rw-rw-r-- 1 steve steve 3191 Mar 2 19:56 uri.c
> -rw-r--r-- 1 steve steve 967 Feb 24 2013 uri.h

URI protocol implementation.

> -rw-rw-r-- 1 steve steve 21282 Mar 2 19:56 url_complete.c
> -rw-r--r-- 1 steve steve 2415 Sep 8 2013 url_complete.h

URL complete dropdown widget.

> -rw-rw-r-- 1 steve steve 5209 Mar 2 19:56 url_protocol.c
> -rw-r--r-- 1 steve steve 1073 Feb 24 2013 url_protocol.h

ANT URL protocol implementation.

> -rw-rw-r-- 1 steve steve 6009 Mar 2 19:56 url_suggest.c
> -rw-r--r-- 1 steve steve 1172 Feb 24 2013 url_suggest.h

Implementation of the URL suggestion pop-up menu (used to the right of the
browser window URL bar).

> -rw-rw-r-- 1 steve steve 28046 Mar 2 19:56 wimp.c
> -rw-r--r-- 1 steve steve 3328 Feb 24 2013 wimp.h

Various useful veneers over Wimp SWIs.

> -rw-rw-r-- 1 steve steve 46816 Mar 2 19:56 wimp_event.c
> -rw-r--r-- 1 steve steve 4951 Sep 8 2013 wimp_event.h

WIMP event dispatch. All new widgets etc should be using this. Think
Toolbox EventLib and you're pretty close to what this does. It also
dispatches menu events, in a form that's abstracted above what RISC OS
itself provides.

> -rw-r--r-- 1 steve steve 1956 Feb 24 2013 wimputils.h

Nasty hacks to deal with OSLib's API breaking C's aliasing rules.

> -rw-rw-r-- 1 steve steve 132959 Mar 2 19:56 window.c
> -rw-rw-r-- 1 steve steve 1265 Mar 2 19:56 window.h

Main browser window UI.

The configuration widgets, in riscos/configure/ and used by configure.c, are
as follows:

> -rw-rw-r-- 1 steve steve 3415 Mar 2 19:56 con_cache.c

Cache configuration dialogue.

> -rw-r--r-- 1 steve steve 8335 Aug 23 2013 con_connect.c

Connection.

> -rw-r--r-- 1 steve steve 3910 Jun 9 2014 con_content.c

Content.

> -rw-r--r-- 1 steve steve 1519 Oct 3 2013 configure.h

Header containing initialisation function names for configuration
widgets. These are called by the main configuration filer-like widget.

> -rw-rw-r-- 1 steve steve 6881 Mar 2 19:56 con_fonts.c

Fonts.

> -rw-r--r-- 1 steve steve 3766 Jun 9 2014 con_home.c

Homepage.

> -rw-r--r-- 1 steve steve 8238 Jun 9 2014 con_image.c

Image rendering settings.

> -rw-r--r-- 1 steve steve 5604 Jun 9 2014 con_inter.c

UI configuration.

> -rw-r--r-- 1 steve steve 4304 Jun 9 2014 con_language.c

Language options.

> -rw-r--r-- 1 steve steve 2780 Jun 9 2014 con_secure.c

Security options.

> -rw-r--r-- 1 steve steve 12806 Jun 9 2014 con_theme.c

Theme configuration.

The GUI widgets in riscos/gui/ and used by toolbar.c are as follows:

> -rw-r--r-- 1 steve steve 30667 Jun 9 2014 button_bar.c
> -rw-rw-r-- 1 steve steve 10380 Mar 2 19:56 button_bar.h

A configurable and user-customisable button bar.

> -rw-r--r-- 1 steve steve 13119 Jun 9 2014 progress_bar.c
> -rw-r--r-- 1 steve steve 1640 Feb 24 2013 progress_bar.h

Generic progress bar widget. Currently unused, afaiaa.

> -rw-rw-r-- 1 steve steve 16062 Mar 2 19:56 status_bar.c
> -rw-r--r-- 1 steve steve 1671 Feb 24 2013 status_bar.h

The status bar used at the foot of browser windows.

> -rw-r--r-- 1 steve steve 10258 Jun 9 2014 throbber.c
> -rw-rw-r-- 1 steve steve 4307 Mar 2 19:56 throbber.h

The throbber used in browser toolbars.

> -rw-rw-r-- 1 steve steve 34538 Mar 2 19:56 url_bar.c
> -rw-rw-r-- 1 steve steve 9063 Mar 2 19:56 url_bar.h

The URL field used in browser toolbars.

A little later, that lot was followed by a second post detailing the basic
flow of execution:

http://listmaster.pepperfish.net/pipermail/netsurf-dev-netsurf-browser.org/2009-August/001475.html

I think a lot of that is now irrelevant: from what I can see of the code,
the sequence is now as follows (all in gui.c):

main() gets the application going, setting up the hooks that the core needs
to work with the front-end and calling various core initialisation along the
way. Debug logging and user options are set up, along with other 'low level'
bits, before netsurf_init() is called to let the core initialise.

Once the core's initialisation is complete, main() calls gui_init() which
does most of the front-end specific initialisation.

If this also goes OK, main() then loops to repeatedly call riscos_poll().
This contains calls to Wimp_Poll(Idle), which is what makes an application
multitask on RISC OS.

The events returned from the OS to riscos_poll() are passed to
ro_gui_handle_event(), which sends them on to interested parties. Mostly
this is done by sending them to wimp_event.c, mouse.c, menus.c or messages.c
for dispatch on to those modules' clients; user messages also have a lot of
legacy things hanging off ro_gui_user_message(), which probably ought to be
clients of message.c in an ideal world.

riscos_poll() also calls schedule_run() to allow scheduled events to take
place. This allows both the front-end and the core to do "background" tasks.

Once the poll loop exits (riscos_done gets set true on receipt of a
Message_Quit from the OS in gui.c, or by the user choosing Quit from the
iconbar menu in iconbar.c), netsurf_exit() is called to allow the core to
tidy up. As part of this, the core will call gui_quit() back in the RO
front-end, to let us tidy up.

--
Steve Fryatt - Leeds, England

http://www.stevefryatt.org.uk/