summaryrefslogtreecommitdiff
path: root/docs/architecture.txt
diff options
context:
space:
mode:
authorPerberos <[email protected]>2011-12-01 22:24:23 -0300
committerPerberos <[email protected]>2011-12-01 22:24:23 -0300
commit0e004c696b0e68b2cff37a4c3315b022a35eaf43 (patch)
tree43261e815529cb9518ed7be37af13b846af8b26b /docs/architecture.txt
downloadcaja-0e004c696b0e68b2cff37a4c3315b022a35eaf43.tar.bz2
caja-0e004c696b0e68b2cff37a4c3315b022a35eaf43.tar.xz
moving from https://github.com/perberos/mate-desktop-environment
Diffstat (limited to 'docs/architecture.txt')
-rw-r--r--docs/architecture.txt160
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.