netsurf/docs/implementing-new-frontend.md

Implementing a new frontend

[TOC]

Introduction

NetSurf is divided into a series of frontends which provide a user interface around common core functionality.

Each frontend is a distinct implementation for a specific GUI toolkit.

The existing frontends are covered in the user interface documentation.

Note implementing a new frontend implies using a toolkit distinct from one of those already implemented and is distinct from porting NetSurf to a new operating system platform.

It is recommend, in the strongest terms, that if the prospective developer is porting to both a new platform and toolkit that they start by getting the monkey frontend building and passing at least the basic integration tests on their platform.

Experience has shown that attempting to port to a platform and implement a toolkit at the same time generally results in failure to achieve either goal.

NetSurf is built using GNU make and frontends are expected to integrate with this buildsystem.

Implementation languages have historically been limited to C, C++ and objective C. However any language that can call C functions and importantly be called back from C code ought to be usable. For example there have been experiments with JAVA using JNI but no current frontend is implemented using it.

Implementation complexity

An absolutely minimal "proof of concept" frontend implementation (like the FLTK frontend that will be used as an example) is around 1,000 lines of C code. Basic functionality like the windows frontend is around 7,000 lines. A complete fully functional frontend such as the one for GTK is closer to 15,000 lines.

It should be noted the majority of the minimal implementation can simply be copied and the names changed as appropriate from an existing example. The actual amount of new code that needs to be provided is very small.

NetSurf provides a great deal of generic functionality for things like cookie, bookmark, history windows which require only minimal frontend support with the core window API.

A frontend developer is free to implement any and all of this generic functionality themselves in a manner more integrated into a toolkit.

Implementation

A frontend is generally named for the toolkit it is implementing (i.e gtk for the GTK+ toolkit). It is advisable to be as specific as possible e.g. the frontend for the windows operating system should have been named win32 allowing for an implementation using a different toolkit (e.g mfc)

All the files needed for the frontend are contained in a single sub-directory in the NetSurf source tree e.g. frontends/fltk

The only file outside this directory that much be changed is the frontends/Makefile.hts where a new entry must be added to the valid targets list.

Build system

A frontend must provide three GNU Makefile fragments (these will be included from the core Makefile):

• Makefile - This is used to extend CFLAGS, CXXFLAGS and LDFLAGS variables as required. The executable target is set with EXETARGET and the browser source files are listed in the SOURCES variable
• Makefile.defaults - allows setting frontend specific makefile variables and overriding of the default core build variables.
• Makefile.tools - allows setting up frontend specific build tooling (as a minimum a tool for the package configuration in PKG_CONFIG)

Source code modules can be named as the developer desires within the frontend directory and should be added to the SOURCES variable as desired.

Program entry

Generally the entry point from the OS is the main() function and several frontends have a main.cpp where some have used gui.c.

The usual shape for the main() function is a six step process:

1. The frontends operation tables are registered with NetSurf
2. The toolkit specific initialisation is performed (which may involve calling NetSurf provided utility functions for support operations like logging, message translations etc.)
3. Initialise the NetSurf core. After this point all browser functionality is available and registered operations can be called.
4. Perform toolkiit setup, usually opening the initial browsing window (perhaps according to user preferences)
5. Run the toolkits main loop while ensuring the NetSurf scheduled operations are also run at the appropriate time.
6. Finalisation on completion.

NetSurf operations tables

The frontend will generally call NetSurf interfaces to get a desired behaviour e.g. browser_window_create() to create a new browsing context (the browser_window_ prefix is historical and does not necessarily create a window e.g. on gtk it is more likely to open a tab in an existing window). To achieve the desired operation some operations need to be performed by the frontend under control of NetSurf, these operations are listed in tables.

The operation tables should be registered with the NetSurf core as one of the first operations of the frontend code. The functions in these tables (and the tables themselves) must remain valid until netsurf_exit() is called.

There are (currently) twelve sets of operation tables held in separate structures. Only five of these are mandatory (misc, window, fetch, bitmap and layout).

In this context mandatory means the tables must be non NULL and do not have a suitable default. Each of the mandatory sets contain function pointers to implement operations.

misc operation table

The only mandatory operation in this table is schedule.

When schedule is called the frontend must arrange for the passed callback to be called with the context parameter after a number of milliseconds.

This callback is typically driven through the toolkits event loop and it is important such callbacks are not attempted from an operation.

window operation table

The window operations (poorly named as already mentioned) are where the frontend is called to actually manipulate widgets in the toolkit. This is mediated through a gui_window context pointer which is typed as a structure.

This context pointer is passed to all window operations and is generally assumed to contain at least a reference to the underlying browser_window which is provided in the initial create operation to allow subsequent use of various core functionality.

The mandatory window operations are:

• create - create a new browsing context widget in the frontend toolkit
• destroy - destroy a previously created gui_window
• invalidate - mark an area of the browsing context viewport as requiring redraw (note no redraw should be attempted from here)
• get_scroll - get the scroll offsets from the toolkit drawing widget
• set_scroll - set the scroll offsets on the toolkit drawing widget
• get_dimensions - get the dimensions of the toolkit drawing widget
• event - deal with various window events from NetSurf which have no additional parameters

fetch operation table

The fetch operations allow the built in scheme fetchers (file, about, resource) to obtain additional information necessary to complete their operation.

The two mandatory operations are:

• filetype - allows the file scheme to obtain a mime type from a file path e.g. a.file.name.png would result in image/png
• get_resource_url - maps resource scheme paths to URL e.g. resource:default.css to file:///usr/share/netsurf/default.css

bitmap operation table

The bitmap table and all of its operations are mandatory only because the empty defaults have not been included as it is assumed a browser will want to display images.

All operations may be provided by stubs that return the failure codes until full implementations are made.

layout operation table

The layout table is used to layout text. All operations are given strings to manipulate encoded in UTF-8. There are three mandatory operations:

• width - Calculate the width of a string.
• position - Find the position in a string where an x coordinate falls.
• split - Find where to split a string to make it fit a width.

Worked Example

Rather than attempt to describe every aspect of an implementation we will rather work from an actual minimal example for the FLTK toolkit.

This is available as a single commit (git show 28ecbf82ed3024f51be4c87928fd91bacfc15cbc) in the NetSurf source repository. Alternatively it can be viewed in a web browser.

This represents the absolute minimum implementation to get a browser window on screen (and be able to click visible links). It is implemented in C++ as that is the FLTK implementation language but an equivalent implementation in other languages should be obvious.

Building

The frontends/Makefile.hts had the fltk target added to the VLDTARGET variable. This allows NetSurf to be built for this frontend with make TARGET=fltk

As previously described the three GNU Make files are added:

Makefile this shows how the flags are extended to add the fltk headers and library. Additionally the list of sources are built here, as the comment suggests it is important the SOURCES variable is not expanded here so the S_FRONTEND variable is used to allow expansion at the correct time in the build process.

Makefile.defaults has the default setting to control the build parameters and file locations. These can be overridden by the Makefile.config at compile time.

Makefile.tools allows the configuration of additional tools necessary to build for the target as a minimum pkg-config is usually required to find libraries.

Program entry

In our example program entry is the classical main() in the main.cpp module.

This implements the six stage process outlined previously.

Operations table registration

The netsurf_table structure is initialised and passed to netsurf_register(). It should be noted that the approach taken here and in most frontends is to have a source module for each operation table. The header for each module exposes just the pointer to the individual operation set, this allows for all the operation functions to be static to their module and hence helps reduce global symbol usage.

Frontend specific initialisation

Her it is implemented in nsfltk_init() this function performs all the operations specific to the frontend which must be initialised before NetSurf itself. In some toolkits this would require calling the toolkit initialisation (e.g. gtk_init()).

It is necessary to initialise NetSurf logging and user options at this point. A more fully featured implementation would also initialise the message translation system here.

NetSurf initialisation

This is simply the call to netsurf_init() from this point the browser is fully operational and operations can and will be called.

Frontend specific startup

Although the browser is running it has not yet been told to open a window or navigate to a page. Here nsfltk_start() examines the command line and environment to determine the initial page to navigate to and calls browser_window_create() with the url, this will cause the browser to open a new browsing context and start the navigation.

A frontend may choose to implement more complex logic here but the example here is a good start.

Toolkit run loop

The function nsfltk_run() runs the toolkit event loop. In this case it is using the generic scheduling in the misc.cpp module to ensure callbacks get made at the appropriate time.

There is a nsfltk_done boolean global checked here so when all the browser windows are closed the program will exit.

A more fully featured port might use the toolkits scheduling rather than open coding a solution with a linked list as is done here.

A further optimisation would be to obtain the set of file descriptors being used (with fetch_fdset()) for active fetches allowing for activity based fetch progress instead of the fallback polling method.

finalisation

This simply finalises the browser stopping all activity and cleaning up any resource usage. After the call to netsurf_exit() no more operation calls will be made and all caches used by the core will be flushed.

If user option changes are to be made persistent nsoption_finalise() should be called.

The finalisation of logging will ensure that any output buffers are flushed.

The window operation table

Amongst all the boilerplate of the default implementation the only novel code is in the window operation table in the window.cpp module.

nsfltk_window_create

The create operation instansiates a new NS_Window object and references it in the gui_window structure which it returns to the caller. Technically we could simply return the NS_Window object as the gui_window pointer but this implementation is avoiding the cast.

Secondly Fl_Double_Window is subclassed as NS_Widget. The subclass allows the close callback to be accessed so the global nsfltk_done boolean can be set during the destructor method.

The NS_Window creates an instance of NS_Widget in its constructor, a more extensive implementation would add other window furniture here (scroll bars, url bar, navigation elements, etc.)

The implementation subclasses Fl_Widget implementing the draw method to render the browsing context and the handle method to handle mouse events to allow the user to click.

The NS_Widget::handle() method simply translates the mouse press event from widget coordinates to NetSurf canvas coordinates and maps the mouse button state. The core is informed of these events using browser_window_mouse_click()

The NS_Widget::draw method similarly translates the fltk toolkits clip rectangle, builds a plotting context and calls browser_window_redraw() which will use the plotting operations in the plotting context to render the browsing context within the area specified. One thing to note here is the translation between the coordinates of the render area and the internal page canvas given as the second and third parameters to the draw call. When scrolling is required this is achieved by altering these offsets.

nsfltk_window_invalidate()

This simply calls the damage method on the Fl_Widget class with the appropriate coordinate translation.

nsfltk_window_get_dimensions()

This obtains the fltk widget width and height and returns them.

The plotting interface

When the NS_Widget::draw method was discussed it was noted that a plotting context is built containing an operation table. That table is implemented in plotters.cpp

The implementation here is as minimal as can be, only line, rectangle and text have any implementation at all and even that simply sets a colour and performs the appropriate fltk draw function (fl_line, fl_rect and fl_draw respectively)

Worked Example next steps

The previous section outlined the absolute minimum implementation. Here we can examine some next steps taken to extend the frontend.

Improving the user interface

The example discussion is based on a commit (git show bc546388ce428be5cfa37cecb174d549c7b30320) in the NetSurf source repository. Alternatively it can be viewed in a web browser.

This changes a single module window.cpp where the NS_Window, NS_Widget and NS_URLBar classes are used to create a basic browsing interface.

The static window operation functions are moved inside the NS_Window class and the gui_window structure is used to obtain an instance allowing normal methods to be called to implement functionality. This is purely to make the C++ code more idiomatic and obviously would be handled differently in other languages.

The NS_Window constructor builds additional widgets to just the browser drawing widget. It creates:

• a URL bar widget containing some navigation buttons and a widget to show the current url
• a vertical scrollbar
• a horizontal scrollbar
• a status text widget

The scrollbar widgets fltk callbacks (called when user interacts with the scrollbar) call a method on the NS_Widget allowing it to track the current scroll offsets which are subsequently used in the drawing and user input handling methods.

Improving rendering

Up to this point the rendering has been minimal and the text in a single face and size with incorrect width measurement. There was no proper handling of plotting styles and colours.

Implementing bitmap rendering

There was no bitmap rendering so no pretty pictures.

Implementing the user messages API

This immediately allows the browser to use the existing language translations for many internal strings.

Implementing a user settings dialog

Implementing a way for the user to change configuration options without having to edit a configuration file greatly improves the perceived functionality.

Implementing corewindow

The core window interface allows a frontend to use inbuilt rendering for several interfaces gaining a great deal of functionality for very little code. This one interface set gives a cookie viewer,a local and global history viewer and a hotlist(bookmarks) viewer.

Conclusion

Hopefully this brief overview and worked example should give the prospective frontend developer enough information to understand how to get started implementing a new frontend toolkit for NetSurf.

As can be seen there is actually very little novel code necessary to get started though I should mention that the move from "minimal" to "full" implementation is a large undertaking and it would be wise to talk with the NetSurf developers if undertaking such work.