|
NetSurf
|
This document provides usage instructions for the Framebuffer version of NetSurf.
Framebuffer NetSurf has been tested on Ubuntu and Debian.
The NetSurf framebuffer front end is primarily intended for kiosk and embedded applications where there is insufficient Operating System support for a full graphical windowing environment.
The framebuffer frontend features:
The framebuffer frontend is not a replacement for full native ports. It lacks functionality and flexibility compared to such implementations.
Limitations include:
In addition it should be noted support for some libnsfb surfaces has been implemented purely for debugging functionality (SDL especially) and is not intended to replace native surface handlers.
If a high level windowing system is available then a native NetSurf frontend is almost certainly a better choice than attempting to use the framebuffer frontend.
If there is a graphical environment which supports GTK then using the GTK frontend is a vastly superior choice. The framebuffer frontend will appear exceptionally limited on such capable systems.
The framebuffer frontend is executed with the nsfb command. This command takes parameters to control the operation of the browser. The 'Configuring' section describes the available options in detail.
The selection of the display surface is controlled with the -f switch, the available display surfaces can be shown by passing '?' as the parameter.
$ ./nsfb -f ? ./nsfb: Valid surface names are: ./nsfb: ram ./nsfb: sdl ./nsfb: x ./nsfb: vnc ./nsfb: wld
The avilable surfaces are dependant on what was compiled into the nsfb library.
The browser appears to "hang" with no output
This is often cause by the unintentianal selection of the debug "ram" surface. In this case the browser is in fact operating but the output is being rendered to a memory buffer. the solution is to explictly select the intended surface using the -f switch
The displayed browser interface has no visible icons
This is generally because the necessary resources are not availale on the resource search path.
There is no displayed text.
The font configuration is incorrect either it has been compiled wrongly or the configured freetype font is not available
The browser messages are "bad"
If the browser messages are being emited as unrecognisable short text symbols or in the wrong language it is likely the Messages file could not be located. This can be confirmed by looking for the text "Message translations failed to load" in the verbose log output (run the browser with the -v switch)
Several resources are set at compile time and are not changeable at run time such as the icon bitmaps, the font system to use and what default surface to use. Refer to the BUILDING-Framebuffer document for details.
As with any NetSurf frontend run-time configuration is read from a "Choices" file. This file is a simple key:value list and by default is located in "${HOME}/.netsurf/Choices".
The standard core user options are available. In addition to the core options there are a number of values to control specific aspects of the framebuffer version.
The trivial toolkit has some configuration parameters allowing the user to alter specific aspects of the UI. All the sizes are in surface pixels however that is mapped.
fb_furniture_size This is the size allowed for the scroll bar elements.
fb_toolbar_size The height of the toolbar.
fb_toolbar_layout The layout of the toolbar, layout uses a string to define buttons type and position each character adds an element to the toolbar:
b - Move back in history l - Display the local history f - Move forward in history s - stop fetching content r - refresh content u - url bar expands to fit remaining space t - throbber/activity indicator c - close the current window q - Disable The toolbar altogether
If the option contains only the q specifier the toolbar is disabled altogether (this was previously the empty string but that was difficult to configure correctly).
The default layout is "blfsrutc" there should be no more than a single url bar entry.
fb_osk Whether the on screen keyboard should be enabled for input.
There are four command line switches which override compiled in defaults these are:
-f <handler> Selects a surface handler to pass to libnsfb instead of the default. (e.g. x, sdl, mem, linux)
-b <depth> Selects the pixel depth to pass to libnsfb instead of the compiled in default. (one of 8, 16, 24, 32)
-w <width> Selects the surface width to pass to libnsfb instead of the compiled in default.
-h <height> Selects the surface height to pass to libnsfb instead of the compiled in default.
The libnsfb surface parameters are controlled with:
fb_refresh - The refresh rate (for physical displays) fb_depth - The depth (in bits per pixel) of the surface fb_device - The path to the device (for physical displays) fb_input_devpath - The path to the input devices (for linux input layer) fb_input_glob - The input device selection glob (for linux input layer) window_width - The width of the framebuffer window_height - The height of the framebuffer
The defaults are for 800 by 600 pixels at 16bpp and 70Hz refresh rate.
The documentation of libnsfb should be consulted for further information about supported surfaces and their configuration.
If the compile time option is set to use the freetype font system then several configuration options are available. If the simple bitmap glyphs are used none of these options apply.
Font faces are provided for the css default styles of sans serif, serif, monospace, cursive and fantasy. Only the sans serif non-italic normal weight font is required to exist, If any of the other faces are missing the sans serif font will be used instead.
The compiled in default font file paths are specified within the build time Makefile.config. The default faces is the truetype DejaVu font set in the directory /usr/share/fonts/truetype/ttf-dejavu/
The font glyphs are, by default, rendered as 256 level transparency which gives excellent visual results even on small font sizes.
The font selection may be changed by placing truetype font files in the resources path. The resource files will be the generic names sans_serif.ttf, sans_serif_bold.ttf etc.
The font system is configured at run-time by several options:
fb_font_monochrome This option causes the renderer to use monochrome glyph rendering. This method of rendering is much less visually appealing and while faster to plot it is slower to render.
fb_font_cachesize This option sets the number of kilobytes of memory set aside for caching the rendered glyphs. This caching significantly improves the performance of using the freetype rendering system. It is set to 2048 by default (2 Megabytes of memory) which impiracle testing shows to be a suitable value for the seven default faces.
The remaining options control the files to be used for font faces. The font file name options will override both the compiled in paths and files found in the resource path.
fb_face_sans_serif - The sans serif face fb_face_sans_serif_bold - The bold sans serif face fb_face_sans_serif_italic - The italic sans serif face fb_face_sans_serif_italic_bold - The bold italic sans serif face. fb_face_serif - The serif font fb_face_serif_bold - The bold serif font fb_face_monospace - The monospaced font fb_face_monospace_bold - The bold monospaced font fb_face_cursive - The cursive font fb_face_fantasy - The fantasy font
1.8.13