fix spelling errors in documentation

This commit is contained in:
Vincent Sanders 2023-12-05 10:20:46 +00:00
parent a9f13decf4
commit 35a1f27a3f

View File

@ -54,14 +54,14 @@ cookie, bookmark, history windows which require only minimal frontend
support with the [core window API](docs/core-window-interface.md).
A frontend developer is free to implement any and all of this generic
functionality thelselves in a manner more integrated into a toolkit.
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 impementation using a differnt
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
@ -80,7 +80,7 @@ included from the core Makefile):
- `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 devloper desires within the
Source code modules can be named as the developer desires within the
frontend directory and should be added to the SOURCES variable as
desired.
@ -94,16 +94,16 @@ The usual shape for the `main()` function is a six step process:
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 teh apropriate time.
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
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 achive the desired operation some
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.
@ -113,22 +113,22 @@ 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 mandantory (misc, window, fetch,
structures. Only five of these are mandatory (misc, window, fetch,
bitmap and layout).
In this context mandantory means the tables must be non NULL and do
not have a suitable default. Each of the mandantory sets contain
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 mandantory operation in this table is schedule.
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
miliseconds.
milliseconds.
This callback is typicaly driven through the toolkits event loop and
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
@ -143,27 +143,27 @@ 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 mandantory window operations are:
The mandatory window operations are:
- create - create a new browsing context widget in the frontend toolkit
- destroy - destoy a previously created `gui_window`
- 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
- 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 mandantory operations are:
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 mandantory only because
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.
@ -173,7 +173,7 @@ 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 mandantory
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.
@ -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 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 is available 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
@ -201,13 +201,13 @@ 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=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
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 teh
here so the S_FRONTEND variable is used to allow expansion at the
correct time in the build process.
[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.
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](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.
@ -224,21 +224,21 @@ 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
indivial operation set, this allows for all the operation functions to
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
before NetSurf itself. In some toolkits this would require calling the
toolkit initialisation (e.g. `gtk_init()`).
It is nessesary to initialise netsurf logging and user options at this
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
### 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.
@ -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=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) 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 scheduling 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 appropriate time.
There is a `nsfltk_done` boolean global checked here so when all the
browser windows are closed the program will exit.
@ -265,7 +265,7 @@ 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 futher optimisation would be to obtain the set of file descriptors
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.
@ -276,7 +276,7 @@ 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 chnages are to be made persistant `nsoption_finalise()`
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
@ -293,7 +293,7 @@ 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 sublass
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.
@ -303,11 +303,11 @@ more extensive implementation would add other window furniture here
The implementation subclasses `Fl_Widget` implementing the draw
method to render the browsing context and the handle method to handle
mouse events to allow teh user to click.
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 cooridinates and maps
teh mouse button state. The core is informed of these events using
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
@ -317,7 +317,7 @@ 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 achived by altering these offsets.
required this is achieved by altering these offsets.
### `nsfltk_window_invalidate()`
@ -343,7 +343,7 @@ colour and performs the appropriate fltk draw function (`fl_line`,
# Worked Example next steps
The previous section outlined the absolute minimum
implementation. Here we can exmaine some next steps taken to extend
implementation. Here we can examine some next steps taken to extend
the frontend.
## Improving the user interface
@ -397,17 +397,17 @@ perceived functionality.
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
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 breif overview and worked example should give the
prospectinve frontend developer enough information to understand how
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 actualy very little novel code necessary to
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.