From 537f131ee3617614cba46dae2d893d209c0a95e3 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Tue, 23 Mar 2021 23:44:59 +0000 Subject: [PATCH] extend teh implementing a new frontend document --- docs/implementing-new-frontend.md | 79 +++++++++++++++++++++++++++---- 1 file changed, 70 insertions(+), 9 deletions(-) diff --git a/docs/implementing-new-frontend.md b/docs/implementing-new-frontend.md index 1b4e43817..4bda47af0 100644 --- a/docs/implementing-new-frontend.md +++ b/docs/implementing-new-frontend.md @@ -184,7 +184,7 @@ operations: 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 availble as a single commit (`git show 04900e82e65f8669675538a66a01b56a3e473cb2`) in the NetSurf source repository. Alternatively it can be [viewed in a web browser](https://git.netsurf-browser.org/netsurf.git/commit/?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2). +This is availble as a single commit (`git show 28ecbf82ed3024f51be4c87928fd91bacfc15cbc`) in the NetSurf source repository. Alternatively it can be [viewed in a web browser](https://git.netsurf-browser.org/netsurf.git/commit/?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc). This represents the absolute minimum implementation to get a browser window on screen (and be able to click visible links). It is @@ -193,28 +193,28 @@ equivalent implementation in other languages should be obvious. ## Building -The [frontends/Makefile.hts](https://git.netsurf-browser.org/netsurf.git/diff/frontends/Makefile.hts?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) +The [frontends/Makefile.hts](https://git.netsurf-browser.org/netsurf.git/diff/frontends/Makefile.hts?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) 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](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) +[Makefile](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) this shows how the flags are extended to add the fltk headers and library. Additionaly the list of sources are built here, as teh comment suggests it is important the SOURCES variable is not expanded here so the S_FRONTEND variable is used to allow expansion at teh correct time in the build process. -[Makefile.defaults](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.defaults?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) +[Makefile.defaults](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.defaults?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) has the default setting to control the build parameters and file locations. These can be overriden by the `Makefile.config` at compile time. -[Makefile.tools](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.tools?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) +[Makefile.tools](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.tools?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) 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](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/main.cpp?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) module. +In our example program entry is the classical `main()` in the [main.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/main.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) module. This implements the six stage process outlined previously. @@ -256,7 +256,7 @@ 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 scheduleing in the [misc.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/misc.cpp?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) module to ensure callbacks get made at the apropriate time. +The function `nsfltk_run()` runs the toolkit event loop. In this case it is using the generic scheduleing in the [misc.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/misc.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) module to ensure callbacks get made at the apropriate time. There is a `nsfltk_done` boolean global checked here so when all the browser windows are closed the program will exit. @@ -284,7 +284,7 @@ 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](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/window.cpp?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) module. +Amongst all the boilerplate of the default implementation the only novel code is in the window operation table in the [window.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/window.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) module. ### `nsfltk_window_create` @@ -333,13 +333,74 @@ This obtains the fltk widget width and height and returns them. 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](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/plotters.cpp?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2) +implemented in [plotters.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/plotters.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) 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 exmaine 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](https://git.netsurf-browser.org/netsurf.git/commit/?h=vince/fltk&id=bc546388ce428be5cfa37cecb174d549c7b30320). + +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](docs/core-window-interface.md) allows a +frontend to use inbuilt rendering for several interfaces gaining a +great deal of functionality for very litte code. This one interface +set gives a cookie viewer,a local and global history viewer and a +hotlist(bookmarks) viewer. + # Conclusion Hopefully this breif overview and worked example should give the