apps/konqueror/DESIGN

   1 Konqueror Design Document
   2
   3 Author:
   4   David Faure, faure@kde.org
   5
   6 Last modified: 25 September 2007
   7
   8 Overall design of konqueror :
   9 =============================
  10
  11 The design of konqueror is based on the KParts part/mainwindow mechanism
  12 (basically, konqueror can embed several parts, putting each one inside a view :
  13 icon views, tree views, html views...)
  14
  15 The main(), including all the startup mechanism is in konq_main.*
  16
  17 The main window contains several "views", in order to show several URLs
  18 at once, possibly using several modes. Each view is a KonqView.
  19 The KonqView contains the child part, which can be any KParts::ReadOnlyPart.
  20 For instance:
  21 - a directory view provided by DolphinPart
  22 - an HTML view provided by KHTMLPart
  23 - any other KParts::ReadOnlyPart with or without BrowserExtension
  24
  25 Where to find those classes
  26 ===========================
  27
  28 src/*  : This is where konqueror is.
  29   konqrun.* : Re-implementation of KRun (see libkio) for konqueror.
  30               Responsible for finding appropriate view<->mimetype bindings.
  31   konqview.* : KonqView, class used by KonqMainView to handle child views
  32   konqframe.* : KonqFrame and KonqFrameHeader (handles view-statusbar).
  33   konqmain.* : The main()
  34   konqmainwindow.* : KonqMainWindow, the main window :)
  35   konqviewmanager.*: View manager. Handles view creation, activation, splitters etc.
  36 about/* : The about part, shows the about page on startup
  37 client/* : kfmclient, for talking to running konqueror processes
  38 sidebar/* : The konqueror sidebar (framework+plugins)
  39
  40 Libs used by konqueror
  41 ======================
  42
  43 From kdelibs:
  44 kdecore - mimetypes, services
  45 kdeui - widgets
  46 kparts - component model
  47 khtml - HTML rendering
  48 kio - I/O stuff, bookmarks, properties dialog
  49
  50 From kdebase:
  51 libkonq - templates ("new") menu, RMB popup menu, file operations
  52
  53 How konqueror opens URLs
  54 ========================
  55
  56 KonqMainWindow:
  57
  58   openFilteredURL or slotOpenURLRequest
  59                     |
  60                     |
  61             -----openUrl----
  62              |   |        |
  63              |   |        |
  64              |  KonqRun  KRun
  65              |   |
  66              |   |
  67            openView
  68                |   \----- splitView to create a new one
  69 KonqView:      |
  70          changeViewMode
  71                |
  72        [switchView if different mode required]
  73                |
  74           openUrl  [emits openURLEvent (after calling openURL)]
  75 Part:          |
  76                |
  77           openUrl [emits started, progress info, completed]
  78               ...
  79
  80
  81 How history is implemented
  82 ==========================
  83
  84 From the konqueror side:
  85
  86 * KonqView has a list of history items. Each item contains a URL,
  87 and a QByteArray for the view to store its stuff in the format that suits it best.
  88 It calls saveState() at various points of time (right after starting loading the URL,
  89 when the loading is completed, and right before loading another URL). Reason:
  90 among other things, many views store the x and y offset of their scrollview in there.
  91 It calls restoreState() when restoring a particular item out of the history list.
  92
  93 From the khtml side:
  94
  95 * Site with no frames: no problem, it just obeys to saveState/restoreState.
  96
  97 * Site with frames:
  98 KHTMLPart saves the whole structure (all frames, and their URL) in the
  99 history buffer (saveState/restoreState).
 100 Every time a frame changes its URL, we want a new item in the history.
 101 But when this happens, since it's internal to khtml, konqueror wouldn't know
 102 about it. That's why there is the openUrlNotify() signal in browser extension
 103 (see there for extensive docu about it).
 104 When khtml emits it, KonqView creates a new history entry and fills it
 105 (calling saveState).
 106