diff options
Diffstat (limited to 'docs/architecture.txt')
| -rw-r--r-- | docs/architecture.txt | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/docs/architecture.txt b/docs/architecture.txt new file mode 100644 index 00000000..83ce44fd --- /dev/null +++ b/docs/architecture.txt @@ -0,0 +1,160 @@ + + +* Caja Architecture Block Diagram + + ++-----------------------------------------------------------------------+ +| | +| caja application | +| | +| +----------------------------------------------------------+ | +| | | | +| | | | +| | CajaWindow | | +| | | | +| | | | +| +----------------------------------------------------------+ | +| | | | | +| | | | | +| \|/ \|/ \|/ | +| +---------------------+ +------------------+ +------------------+ | +| | | | | | | | +| | CajaContentView | | CajaMetaView | | CajaMetaView | | +| | | | | | | | +| +---------------------+ +------------------+ +------------------+ | +| /||\ /||\ /||\ | +| || || || | ++----------||---------------------------||------------------------||----+ + || || || + CORBA CORBA CORBA + || || || ++----------||------------------+ +------||-------------------+ +--||-----------------------+ +| \||/ | | \||/ | | \||/ | +| +--------------------------+ | | +-----------------------+ | | +-----------------------+ | +| | | | | | | | | | | | +| | CajaContentViewFrame | | | | CajaMetaViewFrame | | | | CajaMetaViewFrame | | +| | | | | | | | | | | | +| +--------------------------+ | | +-----------------------+ | | +-----------------------+ | +| | | | | | +| caja view component | | caja view component | | caja view component | +| | | | | | ++------------------------------+ +---------------------------+ +---------------------------+ + + + +* Caja Architecture Summary + +Caja is a general-purpose shell application for browsing arbitrary +content. It is implemented as `caja', a container application +which excercises overall control and provides chrome, and a number of +caja view components. These view components may use the +`libcaja' library to ease implementation. + +There are two types of views, content views and meta-views. A caja +window typically has one content view, which is displayed in the main +area of the window, and several meta-views, which are displayed on the +left, typically one at a time. The meta-views should be panels that +display information about the content being displayed, or that provide +navigation aids. + +However, ultimately multiple content views will be available and may +be switched by using an option menu. + +The caja application has a CajaWindow object for each window +it displays. The CajaWindow object provides various chrome and +uses a number of CajaView objects to communicate with view +components. The relationship between CajaWindow and the +CajaViews is mostly, but not completely one-way; primarily, the +window calls the view's methods and connects to its signals. + +The CajaView object serves as a proxy for a view component. It +provides a number of methods which correspond to the methods of the +Caja:View IDL interface, and translates calls to these methods to +CORBA calls to the view component. It also translates incoming calls +from the view component into signal emissions for a set of signals +that reflects that Caja:ViewFrame IDL interface. + +The CajaViewFrame object serves the corresponding role in the view +component. It provides methods that correspond to the +Caja:ViewFrame IDL interface which it translates to CORBA calls to +the app, and translates incoming CORBA calls from the app into signal +emissions which reflect the Caja:View IDL interface. + +Thus, whenever the application calls a CajaView method to +communicate with the view, a CORBA message is sent, and a signal is +emitted in the view component by CajaViewFrame. And conversely, +when the view component calls a CajaViewFrame method to +communicate with the app, a CORBA message is sent, and a signal is +emitted by CajaView. + + + +* Control Flow for a Location Change + +There are two possible cases. One case is when one of the views +requests a location change. The other is when the framework itself +initiates a location change. This may happen for various reasons, such +as the user typing a URI into the location bar, the user pressing the +Back or Forward buttons, or the user selecting a bookmark. + +** A view requests a location change + +For a view to initiate a location change, view-specific code in the +component calls caja_view_frame_request_location_change with the +appropriate arguments. This results in the "request_location_change" +signal being emitted by the corresponding CajaView object in the +app, as described above. The CajaWindow has connected to this +signal, so it is made aware of the request. The app may decide to +create a new window to display the new location, or to display it in +the same window. Either way, control proceeds largely as below. + + +** The framework carries out a location change + +When a CajaWindow has determined that it should carry out a +location change or load an initial location, it calls +`caja_window_change_location'. This routine begins by stopping any +previous in-progress loads. Then it determines the applicable content +views and meta-views. It then enters a state machine which results in +updating each view. + +When an individual view is being updated, one of two things may +happen. First, if the same view component is still applicable but the +location is different, `caja_view_notify_location_change' is +called which causes the "notify_location_change" signal to be emitted +in the view. If the same view component is no longer applicable, then +a new CajaView object is created, and the component for the proper +iid is loaded. Then `caja_view_notify_location_change' is called +to set it's initial location. + + +** Other component types + +Caja also has built-in support for viewing locations via MateComponent +subdocuments and MateComponent controls. This is implemented in the view and +transparent to the caja application. However, the underlying +architecture is different. + + + +* Other Communication + +The Caja:View and Caja:ViewFrame interfaces allow for other +communication as well. + +The view may request that the frame update the status message, +indicate a certain level of progress during loading, or display a +particular selection. + +The view frame may notify the view of a change in selection, tell it +to stop a load in progress, ask it to load or save its state, or ask +it to show its properties. + +Some conventions apply to the stop and progress operations. First, +`stop_location_change' should be an idempotent operation - that is, +performing it several times in a row should have the same effect as +performing it once, and it should not cause a crash. Second, the view +should send a `request_progress_change' message with a type of either +PROGRESS_DONE_OK or PROGRESS_DONE_ERROR when it is done loading, as +appropriate. This is necessary so that the stop button can be +desensitized when loading is complete. |