tdebase/konqueror/DESIGN

Konqueror Design Document

Author:
  David Faure, faure@kde.org

Last modified: 16 June 2000

Overall design of konqueror :
=============================

The design of konqueror is based on the KParts part/mainwindow mechanism
(basically, konqueror can embed several parts, putting each one inside a view :
icon views, tree views, html views...)

The main(), including all the startup mechanism is in konq_main.*

The main window contains several "views", in order to show several URLs
at once, possibly using several modes. Each view is a KonqView.
The KonqView contains the child part, which can be :
- an icon view (KonqIconView)
- a list view / tree view (KonqListView/KonqTreeView)
- an HTML view (KHTMLPart)
- any other ReadOnlyPart with or without Browserextension

Where to find those classes
===========================

konq_run.* : Re-implementation of KRun (see libkio) for konqueror.
	   Responsible for finding appropriate view<->mimetype bindings.
konq_view.* : KonqView, class used by KonqMainView to handle child views
konq_frame.* : KonqFrame and KonqFrameHeader (handles view-statusbar).
konq_main.* : The main()
konq_mainwindow.* : KonqMainWindow, the main window :)
konq_viewmgr.*: View manager. Handles view creation, activation, splitters etc.
iconview/* : KonqIconView, for icon views
listview/* : KonqTreeView, KonqListView...
dirtree/*  : KonqDirTree, the directory tree

Libs used by konqueror
======================

kdecore, kdeui, kfile, khtml, kparts - usual stuff :)
libkio - I/O stuff, mimetypes, services
libkonq - bookmarks, properties dialog, templates ("new") menu, icon view widget

How konqueror opens URLs
========================

KonqMainWindow:

  openFilteredURL or slotOpenURLRequest
                    |
                    |
            -----openURL----
             |   |        |
             |   |        |
             |  KonqRun  KRun
             |   |
             |   |
           openView
               |   \----- splitView to create a new one
KonqView:      |
         changeViewMode
               |
       [switchView if different mode required]
               |
          openURL  [emits openURLEvent (after calling openURL)]
Part:          |
               |
          openURL [emits started, progress info, completed]
              ...


How history is implemented
==========================

From the konqueror side:

* KonqView has a list of history items. Each item contains a URL,
and a QByteArray for the view to store its stuff in the format that suits it best.
It calls saveState() at various points of time (right after starting loading the URL,
when the loading is completed, and right before loading another URL). Reason:
among other things, many views store the x and y offset of their scrollview in there.
It calls restoreState() when restoring a particular item out of the history list.

From the khtml side:

* Site with no frames: no problem, it just obeys to saveState/restoreState.

* Site with frames:
KHTMLPart saves the whole structure (all frames, and their URL) in the
history buffer (saveState/restoreState).
Every time a frame changes its URL, we want a new item in the history.
But when this happens, since it's internal to khtml, konqueror wouldn't know
about it. That's why there is the openURLNotify() signal in browser extension
(see there for extensive docu about it).
When khtml emits it, KonqView creates a new history entry and fills it
(calling saveState).