

* Peony Architecture Block Diagram


+-----------------------------------------------------------------------+
|                                                                       |
|                            peony application                           |
|                                                                       |
|     +----------------------------------------------------------+      |
|     |                                                          |      |
|     |                                                          |      |
|     |                        PeonyWindow                        |      |
|     |                                                          |      |
|     |                                                          |      |
|     +----------------------------------------------------------+      |
|                |                   |                     |            |
|                |                   |                     |            |
|               \|/                 \|/                   \|/           |
| +---------------------+   +------------------+   +------------------+ |
| |                     |   |                  |   |                  | |
| |   PeonyContentView   |   |   PeonyMetaView   |   |   PeonyMetaView   | |
| |                     |   |                  |   |                  | |
| +---------------------+   +------------------+   +------------------+ |
|         /||\                         /||\                      /||\   |
|          ||                           ||                        ||    |
+----------||---------------------------||------------------------||----+
           ||                           ||                        ||
         CORBA                         CORBA                     CORBA
           ||                           ||                        ||
+----------||------------------+ +------||-------------------+ +--||-----------------------+
|         \||/                 | |     \||/                  | | \||/                      |
| +--------------------------+ | | +-----------------------+ | | +-----------------------+ |
| |                          | | | |                       | | | |                       | |
| |   PeonyContentViewFrame   | | | |   PeonyMetaViewFrame   | | | |   PeonyMetaViewFrame   | |
| |                          | | | |                       | | | |                       | |
| +--------------------------+ | | +-----------------------+ | | +-----------------------+ |
|                              | |                           | |                           |
|     peony view component      | |    peony view component    | |    peony view component    |
|                              | |                           | |                           |
+------------------------------+ +---------------------------+ +---------------------------+



* Peony Architecture Summary

Peony is a general-purpose shell application for browsing arbitrary
content. It is implemented as `peony', a container application
which excercises overall control and provides chrome, and a number of
peony view components. These view components may use the
`libpeony' library to ease implementation.

There are two types of views, content views and meta-views. A peony
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, ultiukuily multiple content views will be available and may
be switched by using an option menu.

The peony application has a PeonyWindow object for each window
it displays. The PeonyWindow object provides various chrome and
uses a number of PeonyView objects to communicate with view
components. The relationship between PeonyWindow and the
PeonyViews is mostly, but not completely one-way; primarily, the
window calls the view's methods and connects to its signals. 

The PeonyView object serves as a proxy for a view component. It
provides a number of methods which correspond to the methods of the
Peony: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 Peony:ViewFrame IDL interface.

The PeonyViewFrame object serves the corresponding role in the view
component. It provides methods that correspond to the
Peony: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 Peony:View IDL interface.

Thus, whenever the application calls a PeonyView method to
communicate with the view, a CORBA message is sent, and a signal is
emitted in the view component by PeonyViewFrame. And conversely,
when the view component calls a PeonyViewFrame method to
communicate with the app, a CORBA message is sent, and a signal is
emitted by PeonyView.



* 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 peony_view_frame_request_location_change with the
appropriate arguments. This results in the "request_location_change"
signal being emitted by the corresponding PeonyView object in the
app, as described above. The PeonyWindow 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 PeonyWindow has determined that it should carry out a
location change or load an initial location, it calls
`peony_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, `peony_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 PeonyView object is created, and the component for the proper
iid is loaded. Then `peony_view_notify_location_change' is called
to set it's initial location.


** Other component types

Peony also has built-in support for viewing locations via UkuiComponent
subdocuments and UkuiComponent controls. This is implemented in the view and
transparent to the peony application. However, the underlying
architecture is different.



* Other Communication

The Peony:View and Peony: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.
