
Galeon Bookmarks
-----------------

This small document describes the overall design of Galeon's Bookmark
System. It is by no means complete, you can ask questions at
<galeon-devel@lists.sourceforge.net>.

The bookmark system is mostly independent of the rest of galeon. It
is built as a static library that only uses code in the bookmarks/ and
utils/ directories. Outside of bookmarks/, there is very little code
related with bookmarks, and most of it is trivial.

The bookmark library is written in C using GObjects. It uses lots of
signals and GLib features, so understanding GObjects is a good idea
before looking at this code. I'm not following all of the GObjects
conventions (only 90% of them), partly because I'm lazy and partly
because some of them don't make sense always.

Every exposed field of a class should be considered "public
readonly". You can read it, but never change it directly. Use the
public functions to manipulate bookmarks.

To understand this document, you should read the header files at the
same time. 

Basic Classes
-------------

- GbBookmark

    This abstract class represent a bookmark. It can be a site, a
    folder, a smartsite...

    A bookmark has a parent (which is always a GbFolder or
    NULL). Bookmarks have a name, brothers, an id, a nick...

    A GbBookmark emits the "modified" signal when any of its properties
    changes. It emits a "name-modified" signal when its name changes.

    Most of the time, every bookmark belongs to a GbBookmarkSet.

    Bookmarks can have aliases and / or can be aliases. Using the
    public api, you can manipulate a bookmark without caring if it is
    an alias (see GbFolder section for a exception). There are
    functions to get the real bookmark of a bookmark that may be an
    alias (gb_bookmark_real_bookmark) and to test if a bookmark is an
    alias (gb_bookmark_is_alias). Aliases share some fields with their
    real bookmark.

- GbSite:GbBookmark

    A GbSite is the most common type of bookmark. It extends a
    GbBookmark with a URL and some other fields.

    A GbBookmark emits the "url-modified" signal when the URL
    changes. Of course, it also emits the "modified" signal.

- GbFolder:GbBookmark

    A GbFolder is a GbBookmark than can have children. 

    A GbFolder emits signals when it is modified, and also when a
    children or deeper descendant is modified, added or removed. The
    signal names are: "child-modified", "descendant-modified",
    "child-added", "descendant-added", "child-removed" and
    "descendant-removed".

    Every children of a GbFolder must belong to the same
    GbBookmarkSet than the GbFolder.
    
    GbFolder can be alias, and it is possible to create recursive
    structures. This has to be remembered when iterating to avoid
    infinite loops. You can use the GbIterator class, or you can check
    if a GbFolder is an alias before iterating through its children.

    GbFolder can be marked as toolbars, in which case they will be
    included in the toolbar list of their GbBookmarkSet.

- GbBookmarkSet

    A GbBookmarkSet is a tree (actually, a graph) of related
    bookmarks. Usually, it is a collection of bookmarks loaded from
    the same file. There is a special bookmark, the root which has no
    parent and all the rest of the bookmarks should be descendants of
    it (there may be exceptions for this, but those bookmarks will not
    be saved). Every descendant of the root must belong to the same
    bookmark set.

    Bookmarks that belong to the bookmark set are indexed by their id
    (when it is not 0) and the URL that they point (when they are a
    GbSite or a subclass).

    Alias resolution (see GbAliasPlaceholder) is done always inside a
    GbBookmarkSet.

    GbBookmarkSet have an autosave feature that updates the file
    automatically when there are changes.

    A GbBookmarkSet has a special folder marked as "default
    folder". New bookmarks should be added to this folder as default.

    It emits a signal "toolbar" when one of the GbFolder objects that
    belong to this set changes its create_toolbar property.

- GbSmartSite:GbSite

    A GbSmartSite is a GbSite that has also a special smart URL. See
    the Galeon Manual if you don't know what does this mean.

    The api is designed to allow several parameters (unlike galeon 1),
    but only support for one is really
    implemented. gb_smart_site_get_num_fields returns the number of
    parameters that can be used for a bookmark (always 1).

    It also has some extra properties: whether the entries should be
    visible or folded (in the toolbar), the size of the entries and
    the history of used parameters.

    It emits signals when those properties change:
    "visibility-changed", "width-changed" and "history-changed".

- GbSeparator:GbBookmark

    A GbSeparator helps grouping bookmarks inside a folder. It has
    some properties but are not really used or saved.

- GbAutoFolder:GbFolder

    This is a GbFolder whose contents are auto generated (from the
    history or whatever). It is currently unimplemented.

- GbAliasPlaceholder:GbBookmark

    GbAliasPlaceholder are used while loading bookmarks files, Because
    we can't create the actual alias to a bookmark until the whole
    file has been parsed.

    Once the file has been read, the GbIO object calls
    gb_bookmark_set_resolve_aliases which unparents all placeholders
    and creates an alias in its place. The resolution is done using
    the bookmark id.

    GbAliasPlaceholder also carry the information about properties of
    the alias that are different from the real bookmark (like whether
    to create a toolbar for a folder or not).

Serialization Classes
---------------------

- GbIO

    GbIO objects can save a GbBookmarkSet to a file (or a string) and
    read a GbBookmarkSet from a file (or a string). This class is
    abstract. 

    You can ask a GbIO the format name and the extensions that it
    support. There is also a function to create a GbIO suitable for
    parsing a file based in its mime type.

- GbXBEL:GbIO

    This is a GbIO that saves and reads files in the XBEL format. It
    is the default format used and the best supported one.

- GbIOMozilla:GbIO

    This is a GbIO that saves and reads files in the format used by
    Mozilla. It only supports saving and loading of disk files, no
    strings.

- GbIONetscape:GbIO

    This is a GbIO that saves and reads files in the format used by
    Netscape. It only supports saving and loading of disk files, no
    strings.

Editor Classes
--------------

- GbSingleEditor

    This class implements a dialog to modify single bookmarks. The
    actual fields shown in the dialog depend on the type of the
    bookmark. To use it, you should do something like: 

	GbSingleEditor *se = gb_single_editor_new ();
	gb_single_editor_set_bookmark (se, bookmark);
	gb_single_editor_show (se);

    The object will be unrefed when the user closes the dialog, so you
    should ref it if you need to keep it around.

- GbTreeModel:GtkTreeModel

    This class implements the GtkTreeModel interface to allow
    displaying bookmarks in any GtkTreeView. 

    This tree model has three columns: the icon of the bookmark, its
    name and its URL (if it is a site).

    It allows having several roots (although this is not very well
    tested because it is not used in galeon yet). All roots must
    belong to the same GbBookmarkSet. There is a convenience
    constructor to create a GtkTreeModel for a whole GbBookmarkSet.

    This model supports DND but does not support sorting.
  
- GbTreeView:GtkTreeView

    This class extends GtkTreeView and makes easier to use a
    GbTreeModel. It only accepts GbTreeModel objects as models, not
    any GtkTreeModel. It automatically adds three columns, handles
    mouse events (double click to activate or edit a bookmark and
    right click to open context menus), enables drag and drop and
    provides an easy api to get selected bookmarks.

    It emits the "bookmark-activated" signal when a bookmark is
    activated and it can have a GbLocationSource to add new bookmarks.

- GbEditor

    This class implements a bookmarks editor using a GbTreeModel and a
    GbTreeView and adds menus, toolbars, options for creating new
    folders, separators, aliases and bookmarks, sorting, copy, cut,
    paste...

    Its use is similar to the GbSingleEditor, but instead of editing a
    single bookmark is edit a GbBookmarkSet (or a subset of bookmarks
    from the same GbBookmarkSet).

    It uses a BonoboWindow as the main widget.

    It emits the "bookmark-activated" signal when a bookmark is
    activated and it can have a GbLocationSource to add new bookmarks.

- GbEditorDockable:GbEditor

    This class extends GbEditor and instead of using a BonoboWindow it
    uses a GtkBox. It makes it suitable to be docked in Galeon's side
    pane (or added to another container). It does not add a toolbar or
    a menu.

User Interface Classes
----------------------

- GbBonoboUIMenu

- GbBonoboUIToolbar

- GbGtkMenu

- GbContextMenu

- GbContextMenuSeveral

- GbTbWidget

- GbFolderTbWidget:GbTbWidget

 GbSeparatorTbWidget:GbTbWidget

- GbSiteTbWidget:GbTbWidget

- GbSmartSiteTbWidget:GbTbWidget

- GbExportDruid

- GbExportDruidKonqueror:GbExportDruid

- GbExportDruidMozilla:GbExportDruid

- GbExportDruidNetscape:GbExportDruid

- GbImportDruid

- GbImportDruidKonqueror:GbImportDruid

- GbImportDruidMozilla:GbImportDruid

- GbImportDruidNetscape:GbImportDruid

Other Classes
-------------

- GbIconProvider

    This interface allows an object to provide icons fr a
    bookmark. The provided icon can be different depending of the
    type, url or any other property of the icon. It can be NULL.

    This interface is necessary because the bookmarks lib can fetch
    icons from the net. Galeon implements an icon provider that
    returns icons using favicons.

    You can set and query the icon provider used by the bookmark
    system using gb_system_set_icon_provider and
    gb_system_get_icon_provider.

- GbDefaultIconProvider:GbIconProvider

    This is the default GbIconProvider. It creates different icons
    depending of the type (site or folder) of the bookmark. It also
    marks aliases icons with an arrow.

- GbClipboard

    This class interfaces with the system clipboard (using
    GtkClipboard) and allows copying and pasting of bookmark objects.

    You can add independent bookmarks to the clipboard (copying them)
    and you can paste all of them (obtaining a GbBookmarkSet). The
    bookmarks are stored in the clipboard using XBEL.

- GbLocationSource

    Location sources are object that have a location that can be used
    to create new bookmarks. For example, Galeon windows. 

    Several objects in the bookmark library can have a location
    source. Usually, those object will pass that location source to
    new objects created by them (for example, GbContextMenu objects
    created by a GbTreeView will get the tree view location source).

    Usually, setting the location source of an object does not
    increment the source's ref count. Weak pointers are used
    instead. This avoids cyclic references.

- GbIterator

    This class helps iterating through a set ob bookmarks. It avoids
    infinite recursion because if does not iterate trough alias
    folders. 

Other considerations
--------------------

- "bookmark-activated" signal

    Several objects can emit this signal. The listener should then
    load the address pointed to the bookmark (or the addresses if it
    is a folder).

    The callback looks like this:

	typedef void (*GbBookmarkActivatedCallback)
		(GObject *emitter, GbBookmark *bookmark, 
		 const gchar *url, GbBookmarkActivatedFlags flags);

    The url may be NULL is the bookmark is not a site, and it may not
    be the same than the bookmark's url if it is a smart site. The
    flags tell the listener how to open the bookmark (or bookmarks if
    it is a folder): in different windows, different tabs... 













 LocalWords:  GbFolder GbBookmark GbBookmarkSet smartsite Galeon's utils devel
 LocalWords:  GObjects GLib readonly api GbSite Serialization GbIONetscape GbIO
 LocalWords:  GbXBEL GbSeparator GbSmartSite GbAutoFolder GbAliasPlaceholder
 LocalWords:  GbIOMozilla LocalWords GbTreeModel GtkTreeModel GbTreeView XBEL
 LocalWords:  GtkTreeView GbSingleEditor GbEditor GbEditorDockable GbTbWidget
 LocalWords:  GbBonoboUIMenu GbBonoboUIToolbar GbGtkMenu GbContextMenu toolbars
 LocalWords:  GbContextMenuSeveral GbFolderTbWidget GbSeparatorTbWidget toolbar
 LocalWords:  GbSmartSiteTbWidget GbSiteTbWidget GbExportDruid GbImportDruid
 LocalWords:  GbExportDruidKonqueror GbExportDruidMozilla GbExportDruidNetscape
 LocalWords:  GbImportDruidKonqueror GbImportDruidMozilla GbImportDruidNetscape
 LocalWords:  GbIterator GbLocationSourceIface GbLocationSource GbClipboard DND
 LocalWords:  GbDefaultIconProvider GbIconProvider autosave unparents Mozilla
 LocalWords:  dialog unrefed GbBookmarkActivatedCallback GObject const gchar
 LocalWords:  GbBookmarkActivatedFlags url BonoboWindow GtkBox favicons
 LocalWords:  GtkClipboard
