SourceForge Logo



Application Extension: The API

browsex.ini: The Init File

BrowseX  can now easily be extended, without changing BrowseX  source code. Just put your own Tcl in browsex.ini in the BrowseX  home directory (~/.brx/browsex.ini under unix). As of version 1.6, this file will get sourced automatically at browser startup. New users will be given a default version of this file which looks something like:
  # Tcl user extension script for BrowseX.
  # This is sourced at startup and lets you hook in your own Tcl.

  # Comment out the following "return" for an simple App that displays Urls.

  toplevel [set m .myapp]
  wm geom $m 200x200
  pack [text $m.t]
  $m.t insert end "Here is my Url Displayer extension\n"
  # Event handler for "urlget"
  proc My_urlget {v url arg} {
    $::m.t insert end $url\n
    return 1
  # Add an event handler to get control when a "urlget" event occurs.
  brx::ApiAddHandler 0 urlget My_urlget
  # See for details of Api calls.

Alternatively, you can specify a script file with the -i command line argument. The above simple example runs if you remove or comment out the return on line 5. It pops up a window which displays each URL you visit. Not spectacular, but it demonstrates how easy it is to extend BrowseX . Used in conjunction with SQLite also builtin to BrowseX , it gives a fair degree of power and flexibility.

API Details

Any procedure within BrowseX  can be called directly. Commonly used ones include:
 set v [brx::ViewNew -1 0 {-url}]
 brx::UrlView $v 

  • ViewNew opens a new browser window and returns the handle v.
  • UrlView displays the URL in the window identifed by the handle v
The problem is, BrowseX  can and does change. Thus the API tries to reduce this risk.

The main goal is to allow programs to get control at various stages of the browsing process. There are three areas to the API. The first and simplest lets you define Event Handlers that let you get control at various events in the browsing process. The more extreme lets you Morph the View to do pretty much whatever you like. Lastly, you can even take control at startup.

Event Handlers

The following 3 functions allow getting/setting your own event handlers. (We're talking about BrowseX events here, not Tcl events.)

ApiAddHandler {v event cmd} Set an event handler and returns token
ApiDelHandler {v event token} Delete an event handler
ApiUpdHandler {v event cmd var} Add/del handler and puts token in var
Valid events are: authget parse unktype cancel arghandler urlget formsubmit

In practice you probably need only the last function, ApiUpdHandler using a cmd of {} to remove handlers.

The token is just an integer denoting the place in the queue. Multiple event handlers can be added, and they will be executed in order of addition (but watch it, deleting creates empty slots that the next add will grab).

Lets say you've defined handlers for your Foo_ project. The cmd called must take exactly these parameters.

Foo_authget {v epass realm} Authorization request
Foo_parse {v url arg} A document parse
Foo_unktype {v ltyp data} Unknown mime type
Foo_cancel {v msg} A cancel was issued
Foo_arghandler {flag arg} Parse command line argument
Foo_urlget {v url arg} A urlget issue
Foo_formsubmit {v n a url qargs} Form is about to submit
In the case of urlget and formsubmit a return 1 is required for continuation. Finally, be aware that the function will be in the brx:: namespace. If you are outside that use ::foo::Foo_parse, etc.

View Morphing

If you actually need complete control to change or wrap BrowseX  to customize the browser, use this interface. Choose a unique suffix/prefix, say Foo_. Then you would call the view create function ViewNew thus:

::brx::ViewNew -1 Foo_

This creates a new view of type Foo_, plus the following are functions in the brx:: namespace that let you get control when:

AppInitFoo_ {v ov a args}view is to be created
AppMainFoo_ {v w} Html widget is about to be created
AppDisplayItFoo_ v End of view creation
MenuDoDefFoo_ {v m} popup menu is appearing.
HrefFoo_{v x y f} User has clicked in Html view.
Note the per-view v parameter to each. Here is a sample definition.
  proc ::brx::AppInitFoo_  {v ov a args} {
    variable pc
    upvar brx::pd$v pv
    return [AppInit0 $v $ov $a $args]

The BrowseX  default type is 0, so we just chained to it. The pc variable contains the global program state. The upvar statement that connects you the pv per-view variable.

If you would like to see a reference implementation, look in mailer.tcl which demonstrates how the Mailer takes complete control and encapsulates Browser views.

Startup Control and Command Line Arguments

You can get control at startup by adding the following file to the as the file name: /custapp.tcl
# custapp.tcl
namespace eval ::brx {
  set pc(deftype) Foo_
  set pc(hook:arghandler) brx::foo_arghandler
if [catch {source $argv0} src] {
  tobe_bgerror $src

The pc(deftype) assignment instructs BrowseX  to look for the file appmain.tcl in the directory Foo_ and source it at startup. Arghandler lets you get control of the command line arguments that are not already in use.
proc ::brx::foo_arghandler {flag arg} {
  switch -- $flag {
    -fooroot {
       set pc(foo_:root) $arg
       return 2
  return 0;

By specifing Foo_ above, you instructed BrowseX to look for the following

Table of Contents

Copyright © 1999-2001   Browsex Systems Inc