|
NetSurf
|
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 userinterface" 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 <em>start</em> by getting the @ref /var/lib/jenkins/workspace/docs-netsurf/docs/using-monkey.md "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 <em>importantly</em> 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. @section autotoc_md92 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 @ref /var/lib/jenkins/workspace/docs-netsurf/docs/core-window-interface.md "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. @section autotoc_md93 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. <tt>frontends/fltk</tt> The only file outside this directory that much be changed is the <tt>frontends/Makefile.hts</tt> where a new entry must be added to the valid targets list. @subsection autotoc_md94 Build system A frontend must provide three GNU Makefile fragments (these will be included from the core Makefile): - <tt>Makefile</tt> - 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 - <tt>Makefile.defaults</tt> - allows setting frontend specific makefile variables and overriding of the default core build variables. - <tt>Makefile.tools</tt> - 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. @subsection autotoc_md95 Program entry Generally the entry point from the OS is the <tt>main()</tt> function and several frontends have a <tt>main.cpp</tt> where some have used <tt>gui.c</tt>. The usual shape for the <tt>main()</tt> 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. @subsection autotoc_md96 NetSurf operations tables The frontend will generally call NetSurf interfaces to get a desired behaviour e.g. <tt>browser_window_create()</tt> to create a new browsing context (the <tt>browser_window_</tt> 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 <tt>netsurf_exit()</tt> 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. @subsubsection autotoc_md97 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. @subsubsection autotoc_md98 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 <tt>gui_window</tt> 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 <tt>browser_window</tt> 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 <tt>gui_window</tt> - 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 @subsubsection autotoc_md99 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: - <tt>filetype</tt> - allows the file scheme to obtain a mime type from a file path e.g. <tt>a.file.name.png</tt> would result in <tt>image/png</tt> - <tt>get_resource_url</tt> - maps resource scheme paths to URL e.g. <tt>resource:default.css</tt> to <tt>file:///usr/share/netsurf/default.css</tt> @subsubsection autotoc_md100 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. @subsubsection autotoc_md101 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: - <tt>width</tt> - Calculate the width of a string. - <tt>position</tt> - Find the position in a string where an x coordinate falls. - <tt>split</tt> - Find where to split a string to make it fit a width. @section autotoc_md102 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 (<tt>git show 28ecbf82ed3024f51be4c87928fd91bacfc15cbc</tt>) in the NetSurf source repository. Alternatively it can be <a href="https://git.netsurf-browser.org/netsurf.git/commit/?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >viewed in a web browser</a>. 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. @subsection autotoc_md103 Building The <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/Makefile.hts?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >frontends/Makefile.hts</a> had the fltk target added to the VLDTARGET variable. This allows NetSurf to be built for this frontend with <tt>make TARGET=fltk</tt> As previously described the three GNU Make files are added: <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >Makefile</a> 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. <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.defaults?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >Makefile.defaults</a> has the default setting to control the build parameters and file locations. These can be overridden by the <tt>Makefile.config</tt> at compile time. <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.tools?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >Makefile.tools</a> allows the configuration of additional tools necessary to build for the target as a minimum pkg-config is usually required to find libraries. @subsection autotoc_md104 Program entry In our example program entry is the classical <tt>main()</tt> in the <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/main.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >main.cpp</a> module. This implements the six stage process outlined previously. @subsubsection autotoc_md105 Operations table registration The <tt>netsurf_table</tt> structure is initialised and passed to <tt>netsurf_register()</tt>. 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. @subsubsection autotoc_md106 Frontend specific initialisation Her it is implemented in <tt>nsfltk_init()</tt> 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. <tt>gtk_init()</tt>). 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. @subsubsection autotoc_md107 NetSurf initialisation This is simply the call to <tt>netsurf_init()</tt> from this point the browser is fully operational and operations can and will be called. @subsubsection autotoc_md108 Frontend specific startup Although the browser is running it has not yet been told to open a window or navigate to a page. Here <tt>nsfltk_start()</tt> examines the command line and environment to determine the initial page to navigate to and calls <tt>browser_window_create()</tt> 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. @subsubsection autotoc_md109 Toolkit run loop The function <tt>nsfltk_run()</tt> runs the toolkit event loop. In this case it is using the generic scheduling in the <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/misc.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >misc.cpp</a> module to ensure callbacks get made at the appropriate time. There is a <tt>nsfltk_done</tt> 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 <tt>fetch_fdset()</tt>) for active fetches allowing for activity based fetch progress instead of the fallback polling method. @subsubsection autotoc_md110 finalisation This simply finalises the browser stopping all activity and cleaning up any resource usage. After the call to <tt>netsurf_exit()</tt> 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 <tt>nsoption_finalise()</tt> should be called. The finalisation of logging will ensure that any output buffers are flushed. @subsection autotoc_md111 The window operation table Amongst all the boilerplate of the default implementation the only novel code is in the window operation table in the <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/window.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >window.cpp</a> module. @subsubsection autotoc_md112 <tt>nsfltk_window_create</tt> The create operation instansiates a new <tt>NS_Window</tt> object and references it in the gui_window structure which it returns to the caller. Technically we could simply return the <tt>NS_Window</tt> object as the gui_window pointer but this implementation is avoiding the cast. Secondly <tt>Fl_Double_Window</tt> is subclassed as <tt>NS_Widget</tt>. The subclass allows the close callback to be accessed so the global <tt>nsfltk_done</tt> boolean can be set during the destructor method. The NS_Window creates an instance of <tt>NS_Widget</tt> in its constructor, a more extensive implementation would add other window furniture here (scroll bars, url bar, navigation elements, etc.) The implementation subclasses <tt>Fl_Widget</tt> implementing the draw method to render the browsing context and the handle method to handle mouse events to allow the user to click. The <tt>NS_Widget::handle()</tt> 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 <tt>browser_window_mouse_click()</tt> The <tt>NS_Widget::draw</tt> method similarly translates the fltk toolkits clip rectangle, builds a plotting context and calls <tt>browser_window_redraw()</tt> 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. @subsubsection autotoc_md113 <tt>nsfltk_window_invalidate()</tt> This simply calls the damage method on the <tt>Fl_Widget</tt> class with the appropriate coordinate translation. @subsubsection autotoc_md114 <tt>nsfltk_window_get_dimensions()</tt> This obtains the fltk widget width and height and returns them. @subsection autotoc_md115 The plotting interface When the <tt>NS_Widget::draw</tt> method was discussed it was noted that a plotting context is built containing an operation table. That table is implemented in <a href="https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/plotters.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc" >plotters.cpp</a> 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 (<tt>fl_line</tt>, <tt>fl_rect</tt> and <tt>fl_draw</tt> respectively) @section autotoc_md116 Worked Example next steps The previous section outlined the absolute minimum implementation. Here we can examine some next steps taken to extend the frontend. @subsection autotoc_md117 Improving the user interface The example discussion is based on a commit (<tt>git show bc546388ce428be5cfa37cecb174d549c7b30320</tt>) in the NetSurf source repository. Alternatively it can be <a href="https://git.netsurf-browser.org/netsurf.git/commit/?h=vince/fltk&id=bc546388ce428be5cfa37cecb174d549c7b30320" >viewed in a web browser</a>. This changes a single module <tt>window.cpp</tt> where the <tt>NS_Window</tt>, <tt>NS_Widget</tt> and <tt>NS_URLBar</tt> classes are used to create a basic browsing interface. The static window operation functions are moved inside the <tt>NS_Window</tt> class and the <tt>gui_window</tt> 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 <tt>NS_Window</tt> 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 <tt>NS_Widget</tt> allowing it to track the current scroll offsets which are subsequently used in the drawing and user input handling methods. @subsection autotoc_md118 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. @subsection autotoc_md119 Implementing bitmap rendering There was no bitmap rendering so no pretty pictures. @subsection autotoc_md120 Implementing the user messages API This immediately allows the browser to use the existing language translations for many internal strings. @subsection autotoc_md121 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. @subsection autotoc_md122 Implementing corewindow The @ref /var/lib/jenkins/workspace/docs-netsurf/docs/core-window-interface.md "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. @section autotoc_md123 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.
1.9.4