Jun 2003, Frank de lange <frank@unternet.org>

==============================
DilloDoc: Document abstraction
==============================

The DilloDoc document abstraction was implemented to make it possible
to have more than one document bound to a single browser
window. While the need for this abstraction arose during the
development of document tabs, it can also be useful for implementing
full frame support.

The current implementation of DilloDoc is still somewhat
interface-specific, in that it focuses on the display of several
'Root' documents in a single browser window (in essence, the use of a
tabbed browser window). For frames support, it is probably best to
separate the remaining interface-related items from DilloDoc into a
separate DilloTab abstraction (partly done).


Notes on Naming
===============

In the context of DilloDoc the word 'document' refers to the contents
of a single browser tab, a single frame, or any other single display
widget containing a 'Root' URL. Documents each have their own browsing
history. To get an overview of the contents of a document, just have a
look at the definition of DilloDoc in src/browser.h


From BrowserWindow to DilloDoc
==============================

Before DilloDoc came around, both window-related and document-related
data were kept in a single structure named 'BrowserWindow'. After
DilloDoc, the document-related stuff moved to DilloDoc while the
window-related data remains in BrowserWindow. Where BrowserWindow
used to have a 'docwin' member (containing a GTK_DW_SCROLLED_WINDOW),
it now has a 'tabbrowser' member (containing a GTK_NOTEBOOK).

DilloDoc has a member 'bw', which points to the BrowserWindow it is
attached to. Likewise, BrowserWindow has a member 'dd' which points to
the active DilloDoc in the BrowserWindow. Interface code which used to
refer to bw->docwin to get to the document was changed to refer to
dd->bw->docwin instead. In many cases, references to bw->docwin were
actually not related to interface activity. In those cases the API was
changed to work with DilloDoc instead of BrowserWindow objects, and
the reference to bw->docwin was simply replaced by one to dd->docwin.

In the documentation there might still be references to the old
structure (everything in BrowserWindow). These need to be changed to
fit the current model.


Anatomy of DilloDoc
===================

See src/browser.h for a definition of DilloDoc. Some specifics of the
current implementation follow.


The Pagemark menu
-----------------

While DilloDoc generally does not contain interface-related data
(apart from the GTK_DW_SCROLLED_WINDOW of course), there is currently
one exception: the pagemarks menu. This menu is created 'on the fly'
while parsing the document, and it is document specific. Currently,
the menu is directly attached to the DilloDoc. It is kept alive by a
gtk_object_reference, so it can be attached to and detached from the
main browser window popup menu without problems. The reference is
created in a_Pagemark_new and destroyed in a_Pagemark_destroy.


The Progress members
--------------------

A DilloDoc has several members related to the progress of the
document. These are used by code in src/doc.c to update the
BrowserWindow's progress bars if and only if the DilloDoc is the
'current' document in that window. The members are:

 gint NumImages    - the number of images in this document
 gint NumImagesGot - the number of images already downloaded
 gfloat progress   - the size of the current 'Root' document
 gboolean ready    - TRUE when all data has been downloaded


TODO
====

DilloDoc probably needs to be split up in two parts, one 'pure'
document abstraction and a DilloTab. The 'pure' version of DilloDoc
can then be contained in either a DilloTab or a DilloFrame.

DilloDoc currently contains a direct reference to a BrowserWindow, and
BrowserWindow in turn has a reference to a DilloDoc. For frames, this
might not be a workable solution, since there will be more than one
current DilloDoc per BrowserWindow (wrapped in another DilloDoc, which
contains the FRAMESET).

