Gitweb links:
...log
http://git.netsurf-browser.org/netsurf.git/shortlog/a11ad57bf64ae4e701e049ced1233cc4c7b22054
...commit
http://git.netsurf-browser.org/netsurf.git/commit/a11ad57bf64ae4e701e049ced1233cc4c7b22054
...tree
http://git.netsurf-browser.org/netsurf.git/tree/a11ad57bf64ae4e701e049ced1233cc4c7b22054
The branch, master has been updated
via a11ad57bf64ae4e701e049ced1233cc4c7b22054 (commit)
from 9a7e41d3ea966387eff8abd86198812244cd47bc (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commitdiff
http://git.netsurf-browser.org/netsurf.git/commit/?id=a11ad57bf64ae4e701e049ced1233cc4c7b22054
commit a11ad57bf64ae4e701e049ced1233cc4c7b22054
Author: Vincent Sanders <vi...@kyllikki.org>
Commit: Vincent Sanders <vi...@kyllikki.org>
fix headings to be in doxygen prefered format
diff --git a/docs/implementing-new-frontend.md
b/docs/implementing-new-frontend.md
index 03e6180..1b4e438 100644
--- a/docs/implementing-new-frontend.md
+++ b/docs/implementing-new-frontend.md
@@ -1,8 +1,9 @@
-# Implementing a new frontend
+Implementing a new frontend
+===========================
[TOC]
-## Introduction
+# Introduction
NetSurf is divided into a series of frontends which provide a user
interface around common core functionality.
@@ -35,7 +36,7 @@ objective C. However any language that can call C functions
and
example there have been experiments with JAVA using JNI but no current
frontend is implemented using it.
-## Implementation complexity
+# 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
@@ -55,7 +56,7 @@ 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.
-## Implementation
+# 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
@@ -70,7 +71,7 @@ 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
+## Build system
A frontend must provide three GNU Makefile fragments (these will be
included from the core Makefile):
@@ -83,7 +84,7 @@ Source code modules can be named as the devloper desires
within the
frontend directory and should be added to the SOURCES variable as
desired.
-### Program entry
+## 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`.
@@ -96,7 +97,7 @@ The usual shape for the `main()` function is a six step
process:
5. Run the toolkits main loop while ensuring the Netsurf scheduled operations
are also run at teh apropriate time.
6. Finalisation on completion.
-### NetSurf operations tables
+## 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
@@ -119,7 +120,7 @@ In this context mandantory means the tables must be non
NULL and do
not have a suitable default. Each of the mandantory sets contain
function pointers to implement operations.
-#### misc operation table
+### misc operation table
The only mandantory operation in this table is schedule.
@@ -130,7 +131,7 @@ miliseconds.
This callback is typicaly driven through the toolkits event loop and
it is important such callbacks are not attempted from an operation.
-#### window operation table
+### window operation table
The window operations (poorly named as already mentioned) are where
the frontend is called to actually manipulate widgets in the
@@ -152,7 +153,7 @@ The mandantory window operations are:
- event - deal with various window events from netsurf which have no
additional parameters
-#### fetch operation table
+### fetch operation table
The fetch operations allow the built in scheme fetchers (file, about,
resource) to obtain additional information necessary to complete their
operation.
@@ -160,7 +161,7 @@ The two mandantory 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
+### bitmap operation table
The bitmap table and all of its operations are mandantory only because
the empty defaults have not been included as it is assumed a browser
@@ -169,7 +170,7 @@ 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
+### 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
@@ -178,7 +179,7 @@ operations:
- `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
+# 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.
@@ -190,7 +191,7 @@ 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
+## Building
The
[frontends/Makefile.hts](https://git.netsurf-browser.org/netsurf.git/diff/frontends/Makefile.hts?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2)
had the fltk target added to the VLDTARGET variable. This allows
@@ -205,20 +206,19 @@ 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)
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)
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
+## 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.
This implements the six stage process outlined previously.
-#### Operations table registration
+### Operations table registration
The `netsurf_table` structure is initialised and passed to
`netsurf_register()`. It should be noted that the approach taken here
@@ -227,7 +227,7 @@ table. The header for each module exposes just the pointer
to the
indivial 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
+### Frontend specific initialisation
Her it is implemented in `nsfltk_init()` this function performs all
the operations specific to the frontend which must be initialised
@@ -238,12 +238,12 @@ It is nessesary 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.
-#### Frontend specific startup
+### 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
@@ -254,7 +254,7 @@ 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
+### 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.
@@ -269,7 +269,7 @@ A futher 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
+### finalisation
This simply finalises the browser stopping all activity and cleaning
up any resource usage. After the call to `netsurf_exit()` no more
@@ -282,11 +282,11 @@ should be called.
The finalisation of logging will ensure that any output buffers are
flushed.
-### The window operation table
+## 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.
-#### `nsfltk_window_create`
+### `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
@@ -320,16 +320,16 @@ the second and third parameters to the draw call. When
scrolling is
required this is achived by altering these offsets.
-#### `nsfltk_window_invalidate()`
+### `nsfltk_window_invalidate()`
This simply calls the damage method on the `Fl_Widget` class with the
appropriate coordinate translation.
-#### `nsfltk_window_get_dimensions()`
+### `nsfltk_window_get_dimensions()`
This obtains the fltk widget width and height and returns them.
-### The plotting interface
+## 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
@@ -340,7 +340,7 @@ 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)
-## Conclusion
+# Conclusion
Hopefully this breif overview and worked example should give the
prospectinve frontend developer enough information to understand how
-----------------------------------------------------------------------
Summary of changes:
docs/implementing-new-frontend.md | 56 ++++++++++++++++++-------------------
1 file changed, 28 insertions(+), 28 deletions(-)
diff --git a/docs/implementing-new-frontend.md
b/docs/implementing-new-frontend.md
index 03e6180..1b4e438 100644
--- a/docs/implementing-new-frontend.md
+++ b/docs/implementing-new-frontend.md
@@ -1,8 +1,9 @@
-# Implementing a new frontend
+Implementing a new frontend
+===========================
[TOC]
-## Introduction
+# Introduction
NetSurf is divided into a series of frontends which provide a user
interface around common core functionality.
@@ -35,7 +36,7 @@ objective C. However any language that can call C functions
and
example there have been experiments with JAVA using JNI but no current
frontend is implemented using it.
-## Implementation complexity
+# 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
@@ -55,7 +56,7 @@ 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.
-## Implementation
+# 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
@@ -70,7 +71,7 @@ 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
+## Build system
A frontend must provide three GNU Makefile fragments (these will be
included from the core Makefile):
@@ -83,7 +84,7 @@ Source code modules can be named as the devloper desires
within the
frontend directory and should be added to the SOURCES variable as
desired.
-### Program entry
+## 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`.
@@ -96,7 +97,7 @@ The usual shape for the `main()` function is a six step
process:
5. Run the toolkits main loop while ensuring the Netsurf scheduled operations
are also run at teh apropriate time.
6. Finalisation on completion.
-### NetSurf operations tables
+## 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
@@ -119,7 +120,7 @@ In this context mandantory means the tables must be non
NULL and do
not have a suitable default. Each of the mandantory sets contain
function pointers to implement operations.
-#### misc operation table
+### misc operation table
The only mandantory operation in this table is schedule.
@@ -130,7 +131,7 @@ miliseconds.
This callback is typicaly driven through the toolkits event loop and
it is important such callbacks are not attempted from an operation.
-#### window operation table
+### window operation table
The window operations (poorly named as already mentioned) are where
the frontend is called to actually manipulate widgets in the
@@ -152,7 +153,7 @@ The mandantory window operations are:
- event - deal with various window events from netsurf which have no
additional parameters
-#### fetch operation table
+### fetch operation table
The fetch operations allow the built in scheme fetchers (file, about,
resource) to obtain additional information necessary to complete their
operation.
@@ -160,7 +161,7 @@ The two mandantory 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
+### bitmap operation table
The bitmap table and all of its operations are mandantory only because
the empty defaults have not been included as it is assumed a browser
@@ -169,7 +170,7 @@ 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
+### 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
@@ -178,7 +179,7 @@ operations:
- `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
+# 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.
@@ -190,7 +191,7 @@ 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
+## Building
The
[frontends/Makefile.hts](https://git.netsurf-browser.org/netsurf.git/diff/frontends/Makefile.hts?h=vince/fltk&id=04900e82e65f8669675538a66a01b56a3e473cb2)
had the fltk target added to the VLDTARGET variable. This allows
@@ -205,20 +206,19 @@ 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)
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)
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
+## 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.
This implements the six stage process outlined previously.
-#### Operations table registration
+### Operations table registration
The `netsurf_table` structure is initialised and passed to
`netsurf_register()`. It should be noted that the approach taken here
@@ -227,7 +227,7 @@ table. The header for each module exposes just the pointer
to the
indivial 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
+### Frontend specific initialisation
Her it is implemented in `nsfltk_init()` this function performs all
the operations specific to the frontend which must be initialised
@@ -238,12 +238,12 @@ It is nessesary 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.
-#### Frontend specific startup
+### 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
@@ -254,7 +254,7 @@ 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
+### 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.
@@ -269,7 +269,7 @@ A futher 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
+### finalisation
This simply finalises the browser stopping all activity and cleaning
up any resource usage. After the call to `netsurf_exit()` no more
@@ -282,11 +282,11 @@ should be called.
The finalisation of logging will ensure that any output buffers are
flushed.
-### The window operation table
+## 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.
-#### `nsfltk_window_create`
+### `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
@@ -320,16 +320,16 @@ the second and third parameters to the draw call. When
scrolling is
required this is achived by altering these offsets.
-#### `nsfltk_window_invalidate()`
+### `nsfltk_window_invalidate()`
This simply calls the damage method on the `Fl_Widget` class with the
appropriate coordinate translation.
-#### `nsfltk_window_get_dimensions()`
+### `nsfltk_window_get_dimensions()`
This obtains the fltk widget width and height and returns them.
-### The plotting interface
+## 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
@@ -340,7 +340,7 @@ 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)
-## Conclusion
+# Conclusion
Hopefully this breif overview and worked example should give the
prospectinve frontend developer enough information to understand how
--
NetSurf Browser
_______________________________________________
netsurf-commits mailing list -- netsurf-commits@netsurf-browser.org
To unsubscribe send an email to netsurf-commits-le...@netsurf-browser.org
