BROWSER SWITCHBOARD
version 3.3b1

Browser Switchboard is a program which allows you to choose which
browser to use as the default browser. It supports MicroB, Tear,
Fennec/Mobile Firefox, and Midori out of the box, and can also be used
to launch MicroB without having browserd running.


Download:
Binary packages and source are available for download from the project
page on garage.maemo.org: https://garage.maemo.org/frs/?group_id=1159


Quick Start:
1. Download the binary package: browser-switchboard_X.Y-Z_all.deb
(where X.Y-Z is the version number, of course).
2. If you're using a Maemo 5 device, make sure all your MicroB browser
windows are closed.
3. Install the package using the Application Manager (open the
Application Manager, then select Application->Install from file in the
menu).

You can now select the default browser by using the Browser Switchboard
applet in the Control Panel.  Links in most applications, locally-saved
web pages opened from the file manager, and (for Maemo 4.x) entries in
the Web sidebar panel will open in the browser that you select as the
default.  Opening the "Web" menu entry and running "browser" from the
shell will also cause your chosen default browser to open.  If you don't
configure a default browser, MicroB will continue to be used as the
default browser.

No matter which browser you select as the default, MicroB can always be
opened via the MicroB menu entry in the applications menu (for Maemo
4.x, installed in the Extras menu by default), or by running "microb"
from the shell.  While MicroB is open, it will receive all links from
other applications; closing MicroB will restore your chosen default
browser.

If you experience trouble after installing the package, try rebooting
your device.  If that fixes things, please report this as a bug.


Configuring the Default Browser by Hand:

If for some reason, you don't want to use the Control Panel applet to
configure Browser Switchboard, you can create the configuration file by
hand from a shell.  Run the following (where $ is your prompt, not
something you type):

$ cat > $HOME/.config/browser-switchboard <<EOF
default_browser = "your_browser"
EOF

where your_browser can be one of "tear", "microb", "fennec", "midori",
or "other" (see below for more on the "other" option).  You can of
course also edit the $HOME/.config/browser-switchboard file with your
favorite text editor.

To restore the default behavior, just delete the config file:

$ rm $HOME/.config/browser-switchboard


Advanced Configuration:

Here's a more complete sample configuration file:

# BEGIN SAMPLE CONFIG FILE
# This is a comment
# continuous_mode: 0 -- close after handling a request; 1 -- run
# continuously in the background
continuous_mode = 0
# default_browser: "tear", "microb", "fennec", "midori", or "other"
default_browser = "tear"
# other_browser_cmd: If default browser is "other", what program
# to run (%s will be replaced by URI)
#other_browser_cmd = "some_browser %s"
# logging: Where log output should go: "stdout", "syslog", "none"
#logging = "stdout"
# END SAMPLE CONFIG FILE

Lines beginning with # characters are comments and are ignored by the
script.  [Most options correspond directly to an option or option group
in the configuration UI.]

In continuous mode, Browser Switchboard keeps running in the background
instead of closing after handling each request.  This saves a bit of
startup time for each link (on my N800 running Diablo), but costs you
about 100 KB extra memory.  Continuous mode is disabled by default; set
continuous_mode to 1 to enable.  [This option corresponds to the
"Optimize Browser Switchboard for" option group in the UI; "Lower memory
usage" corresponds to continuous_mode off, while "Faster browser startup
time" corresponds to continuous_mode on.]

The "tear", "microb", "fennec", and "midori" options for default_browser
should be self-explanatory.  [These correspond to the options in the
"Default browser" combo box in the UI.]

If the default browser is "other", Browser Switchboard will run the
program specified in other_browser_cmd as the default browser, with a
URI replacing the %s on the command line; for example, if
other_browser_cmd is set to "some_browser %s", and Browser Switchboard
is asked to load http://www.google.com/, it will perform the equivalent
of typing in 

$ some_browser 'http://www.google.com/'

at a shell.  [In the UI, setting "Default brower" to "Other" activates
the "Command (%s for URI)" setting, which corresponds to the value of
other_browser_cmd.]

The logging option controls where Browser Switchboard sends its debug
logging output to.  You should not need to change this unless you're
debugging Browser Switchboard, and there is no UI for this option.  The
default option is "stdout", which means you won't see output unless you
run Browser Switchboard from the shell.  "syslog" will send the output
to the system log (assuming you have a syslogd set up on your device),
and "none" disables debug logging entirely.


Browser Switchboard and MicroB's browserd:

MicroB uses a background process called browserd to decrease its load
time.  Browser Switchboard knows how to launch MicroB without having
browserd running all the time, so if you don't plan on using MicroB
often, you can disable browserd (for example, by using the
maemo-control-services control panel applet available in Maemo Extras to
disable tablet-browser-daemon).  This will save you about 1 MB of
memory, but add a few seconds to MicroB's load time.


Uninstalling Browser Switchboard:

Remove the Browser Switchboard package using the Application Manager,
and everything should be back to normal.  If you experience problems
after uninstalling, try restarting your device first; if that fixes
things, please report this as a bug.


Compiling Browser Switchboard:

If for some reason you don't want to use the prebuilt binary package to
install Browser Switchboard, you can compile and install by hand:
1. You will need a copy of the SDK for your device.  Make sure the
following packages are installed: libdbus-glib-1-dev for
browser-switchboard; libdbus-1-dev, libgtk2.0-dev, libhildon1-dev,
hildon-control-panel-dev for the config UI.
2. Download the source tarball: browser-switchboard_X.Y.orig.tar.gz
3. Unpack the source tarball in your SDK install:

SDK$ tar -xvzf browser-switchboard_X.Y.orig.tar.gz
SDK$ cd browser-switchboard-X.Y

4. Compile:

SDK$ make diablo
SDK$ make -C config-ui diablo-plugin

(Replace "diablo" with "fremantle" and "diablo-plugin" with
"fremantle-plugin" if compiling for Fremantle.

If you want the standalone config application instead of the Control
Panel plugin, do 
SDK$ make -C config-ui diablo-hildon-app
instead.

If you're using the Scratchbox2-based SDK+, you want
SDK+$ sb2 make
etc. as usual.)

5. Install to a temporary directory, and tar up the result:

SDK$ make DESTDIR=temp install
SDK$ make -C config-ui install
SDK$ cd temp
SDK$ tar cf stuff.tar .

6. As root on your device, move files that will be replaced in the
install process out of the way:

DEVICE# mv /usr/share/dbus-1/services/com.nokia.osso_browser.service
  /usr/share/dbus-1/services/com.nokia.osso_browser.bak
DEVICE# mv /usr/bin/browser /usr/bin/browser.bak

7. Copy the tar file from step 5 to your device, and as root, unpack it
in the root directory of your device:

DEVICE# cd /
DEVICE# tar xf /path/to/stuff.tar

To uninstall, remove the files you installed, restore the backup copies,
and reboot your device.


Bug Reports and Patches:

Bug reports, patches, and suggested improvements can either be sent to
the maintainer via email (see below) or posted in the Tear thread on the
talk.maemo.org forums (http://talk.maemo.org/showthread.php?t=28539).


Source Code Repository:

Source code is hosted in a Git (http://git-scm.com/) repository on
git.maemo.org.  You can get a copy of the current development version by
cloning the repository:

$ git clone http://git.maemo.org/projects/browser-switch

or you can browse the source using gitweb
(http://git.maemo.org/projects/browser-switch/?p=browser-switch;a=summary).


Maintainer:

Steven Luo <steven+maemo@steven676.net> is the primary maintainer, with
Jason Simpson (the original developer) assisting in development.


License:

Browser Switchboard is available under the terms of the GNU General
Public License (GPL), version 2 or later (see the file LICENSE in the
source).
