258 lines
9.2 KiB
Markdown
258 lines
9.2 KiB
Markdown
--------------------------------------------------------------------------------
|
|
Usage Instructions for Framebuffer NetSurf 2nd October 2010
|
|
--------------------------------------------------------------------------------
|
|
|
|
This document provides usage instructions for the Framebuffer version of
|
|
NetSurf.
|
|
|
|
Framebuffer NetSurf has been tested on Ubuntu and Debian.
|
|
|
|
Overview
|
|
========
|
|
|
|
What it is
|
|
----------
|
|
|
|
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:
|
|
|
|
* A trivial occluded rectangle window management toolkit
|
|
|
|
* Font handling system using either:
|
|
- A trivial internal monochrome bitmap glyph set.
|
|
- An interface to fully anti-aliased glyphs using libfreetype 2
|
|
|
|
* Uses libnsfb to provide transparent support for:
|
|
- Numerous surface providers allowing usage on Linux, X, SDL, VNC
|
|
and any mapped linear memory region.
|
|
- Surface depths of 8, 16, 24 and 32bpp
|
|
- Optimised software plotters for lines, rectangles, polygons,
|
|
arbitrary ellipses (including circles), cubic and quadratic
|
|
splines, font glyphs and 32bpp RGBA bitmaps.
|
|
- Abstracted input handling.
|
|
|
|
What it is not
|
|
--------------
|
|
|
|
The framebuffer frontend is not a replacement for full native
|
|
ports. It lacks functionality and flexibility compared to such
|
|
implementations.
|
|
|
|
Limitations include:
|
|
- Single window interface.
|
|
- No tabbed interface.
|
|
- Expects to control the entire plotting surface.
|
|
- No ability to re-size a surface after initialisation.
|
|
- Inflexible input character mapping.
|
|
- Limited history view.
|
|
|
|
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.
|
|
|
|
Running
|
|
=======
|
|
|
|
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.
|
|
|
|
Common issues
|
|
-------------
|
|
|
|
- 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)
|
|
|
|
Configuring
|
|
===========
|
|
|
|
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](docs/netsurf-options.md) are
|
|
available. In addition to the core options there are a number of
|
|
values to control specific aspects of the framebuffer version.
|
|
|
|
Toolkit Options
|
|
---------------
|
|
|
|
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.
|
|
|
|
|
|
Framebuffer Surface
|
|
-------------------
|
|
|
|
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.
|
|
|
|
Fonts
|
|
-----
|
|
|
|
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
|