docs/architecture.txt

   1
   2
   3 * Nautilus Architecture Block Diagram
   4
   5
   6 +-----------------------------------------------------------------------+
   7 |                                                                       |
   8 |                            nautilus application                       |
   9 |                                                                       |
  10 |     +----------------------------------------------------------+      |
  11 |     |                                                          |      |
  12 |     |                                                          |      |
  13 |     |                      NautilusWindow                      |      |
  14 |     |                                                          |      |
  15 |     |                                                          |      |
  16 |     +----------------------------------------------------------+      |
  17 |                |                   |                     |            |
  18 |                |                   |                     |            |
  19 |               \|/                 \|/                   \|/           |
  20 | +---------------------+   +------------------+   +------------------+ |
  21 | |                     |   |                  |   |                  | |
  22 | | NautilusContentView |   | NautilusMetaView |   | NautilusMetaView | |
  23 | |                     |   |                  |   |                  | |
  24 | +---------------------+   +------------------+   +------------------+ |
  25 |         /||\                         /||\                      /||\   |
  26 |          ||                           ||                        ||    |
  27 +----------||---------------------------||------------------------||----+
  28            ||                           ||                        ||
  29          CORBA                         CORBA                     CORBA
  30            ||                           ||                        ||
  31 +----------||------------------+ +------||-------------------+ +--||-----------------------+
  32 |         \||/                 | |     \||/                  | | \||/                      |
  33 | +--------------------------+ | | +-----------------------+ | | +-----------------------+ |
  34 | |                          | | | |                       | | | |                       | |
  35 | | NautilusContentViewFrame | | | | NautilusMetaViewFrame | | | | NautilusMetaViewFrame | |
  36 | |                          | | | |                       | | | |                       | |
  37 | +--------------------------+ | | +-----------------------+ | | +-----------------------+ |
  38 |                              | |                           | |                           |
  39 |   nautilus view component    | |  nautilus view component  | |  nautilus view component  |
  40 |                              | |                           | |                           |
  41 +------------------------------+ +---------------------------+ +---------------------------+
  42
  43
  44
  45 * Nautilus Architecture Summary
  46
  47 Nautilus is a general-purpose shell application for browsing arbitrary
  48 content. It is implemented as `nautilus', a container application
  49 which excercises overall control and provides chrome, and a number of
  50 nautilus view components. These view components may use the
  51 `libnautilus' library to ease implementation.
  52
  53 There are two types of views, content views and meta-views. A nautilus
  54 window typically has one content view, which is displayed in the main
  55 area of the window, and several meta-views, which are displayed on the
  56 left, typically one at a time. The meta-views should be panels that
  57 display information about the content being displayed, or that provide
  58 navigation aids.
  59
  60 However, ultimately multiple content views will be available and may
  61 be switched by using an option menu.
  62
  63 The nautilus application has a NautilusWindow object for each window
  64 it displays. The NautilusWindow object provides various chrome and
  65 uses a number of NautilusView objects to communicate with view
  66 components. The relationship between NautilusWindow and the
  67 NautilusViews is mostly, but not completely one-way; primarily, the
  68 window calls the view's methods and connects to its signals.
  69
  70 The NautilusView object serves as a proxy for a view component. It
  71 provides a number of methods which correspond to the methods of the
  72 Nautilus:View IDL interface, and translates calls to these methods to
  73 CORBA calls to the view component. It also translates incoming calls
  74 from the view component into signal emissions for a set of signals
  75 that reflects that Nautilus:ViewFrame IDL interface.
  76
  77 The NautilusViewFrame object serves the corresponding role in the view
  78 component. It provides methods that correspond to the
  79 Nautilus:ViewFrame IDL interface which it translates to CORBA calls to
  80 the app, and translates incoming CORBA calls from the app into signal
  81 emissions which reflect the Nautilus:View IDL interface.
  82
  83 Thus, whenever the application calls a NautilusView method to
  84 communicate with the view, a CORBA message is sent, and a signal is
  85 emitted in the view component by NautilusViewFrame. And conversely,
  86 when the view component calls a NautilusViewFrame method to
  87 communicate with the app, a CORBA message is sent, and a signal is
  88 emitted by NautilusView.
  89
  90
  91
  92 * Control Flow for a Location Change
  93
  94 There are two possible cases. One case is when one of the views
  95 requests a location change. The other is when the framework itself
  96 initiates a location change. This may happen for various reasons, such
  97 as the user typing a URI into the location bar, the user pressing the
  98 Back or Forward buttons, or the user selecting a bookmark.
  99
 100 ** A view requests a location change
 101
 102 For a view to initiate a location change, view-specific code in the
 103 component calls nautilus_view_frame_request_location_change with the
 104 appropriate arguments. This results in the "request_location_change"
 105 signal being emitted by the corresponding NautilusView object in the
 106 app, as described above. The NautilusWindow has connected to this
 107 signal, so it is made aware of the request. The app may decide to
 108 create a new window to display the new location, or to display it in
 109 the same window. Either way, control proceeds largely as below.
 110
 111
 112 ** The framework carries out a location change
 113
 114 When a NautilusWindow has determined that it should carry out a
 115 location change or load an initial location, it calls
 116 `nautilus_window_change_location'. This routine begins by stopping any
 117 previous in-progress loads. Then it determines the applicable content
 118 views and meta-views. It then enters a state machine which results in
 119 updating each view.
 120
 121 When an individual view is being updated, one of two things may
 122 happen. First, if the same view component is still applicable but the
 123 location is different, `nautilus_view_notify_location_change' is
 124 called which causes the "notify_location_change" signal to be emitted
 125 in the view. If the same view component is no longer applicable, then
 126 a new NautilusView object is created, and the component for the proper
 127 iid is loaded. Then `nautilus_view_notify_location_change' is called
 128 to set it's initial location.
 129
 130
 131 ** Other component types
 132
 133 Nautilus also has built-in support for viewing locations via Bonobo
 134 subdocuments and Bonobo controls. This is implemented in the view and
 135 transparent to the nautilus application. However, the underlying
 136 architecture is different.
 137
 138
 139
 140 * Other Communication
 141
 142 The Nautilus:View and Nautilus:ViewFrame interfaces allow for other
 143 communication as well.
 144
 145 The view may request that the frame update the status message,
 146 indicate a certain level of progress during loading, or display a
 147 particular selection.
 148
 149 The view frame may notify the view of a change in selection, tell it
 150 to stop a load in progress, ask it to load or save its state, or ask
 151 it to show its properties.
 152
 153 Some conventions apply to the stop and progress operations. First,
 154 `stop_location_change' should be an idempotent operation - that is,
 155 performing it several times in a row should have the same effect as
 156 performing it once, and it should not cause a crash. Second, the view
 157 should send a `request_progress_change' message with a type of either
 158 PROGRESS_DONE_OK or PROGRESS_DONE_ERROR when it is done loading, as
 159 appropriate. This is necessary so that the stop button can be
 160 desensitized when loading is complete.