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.
  return

  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 http://browsex.com/API.html 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 http://my.url.com/}]
 brx::UrlView $v http://my.url.com/

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 brx.zip 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

browsex.ini: The Init File
API Details
Event Handlers
View Morphing
Startup Control and Command Line Arguments
Table of Contents

Application Extension: The API

browsex.ini: The Init File

API Details

Event Handlers

View Morphing

Startup Control and Command Line Arguments

Table of Contents