File: compdoc.html

package info (click to toggle)
libbonoboui 2.24.5-4
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 6,808 kB
  • ctags: 3,596
  • sloc: ansic: 30,221; sh: 10,256; xml: 599; makefile: 475
file content (204 lines) | stat: -rw-r--r-- 11,477 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
    
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    
  <meta name="GENERATOR" content="Mozilla/4.77C-EMS-1.4 [en] (X11; U; SunOS 5.5.1 sun4u) [Netscape]">
</head>
 <body>
 <b>Overview:</b> 
<p>The Bonobo Compound Document Interfaces were originally modeled after the
associated COM interfaces.&nbsp; It has become clear that they do not provide
much utility in their current form.&nbsp; They have been largely unused to
this point, so the Gnome 2 platform shift gives us an opportunity to revamp
the interfaces and set them on a path that is more consistent with the rest
of Bonobo. </p>
<p>This document is an attempt to identify the requirements for a compound 
document architecture and propose a solution which is more in line with the
rest of the bonobo interfaces. </p>
<p><b>What are compound documents?</b> </p>
<p>A compound document is obviously an aggregation of multiple sub-documents.&nbsp; 
The sub-documents are implemented as standalone components.&nbsp; A set of
interfaces is necessary to allow the components to expose both their model
characteristics to container documents and their display characteristics to
container views.&nbsp; With these generalized interfaces, it is possible to
write simple container applications that can unleash the power&nbsp; of specialized
components while remaining ignorant of the components' purpose.&nbsp; The
container need only know how to perform the following operations on subcomponents. 
<br>
&nbsp; </p>
<blockquote><u>Activation:</u> <br>
A container must be able to query for subcomponents which provide the container's
preferred rendering model (canvas vs. widget).&nbsp; A Control implementation
should be provided for ease of identifying embeddable subcomponents.&nbsp;
The control should perform component activation and provide a reference to
the selected subcomponent via an event.&nbsp; Linking of subcomponents via
the Clipboard/Drag'nDrop is also necessary.&nbsp; Using a moniker based scheme
is the clear choice for this capability.&nbsp; The design and implementation
of this new capability is being performed in parallel to this compound document 
effort.</blockquote>
  
  <blockquote>&nbsp; <br>
    <u>WYSIWYG Display/Print rendering:</u> <br>
A subcomponent must be capable of rendering itself in a WYSIWYG fashion using
GNOME rendering technology.&nbsp; Components should expose factories to obtain
a canvas or widget based "view" reference which can be embedded into a document
view.&nbsp; Similarly, an interface to provide print rendering is necessary. 
    <p>Uniform zooming of subcomponents is accomplished through the size
request/size allocation cycle on the plug/socket interfaces.&nbsp; Components
request their size in points based on their full extent at 100% zoom. The
container can then factor in manual resizing of the component and scale the
allocation by the current zoom factor of the document. The component then
scales itself to utilize the allocated space.&nbsp; If the component's unscaled
dimensional requirements change due to editing, for example if a new line
of text is added to a text control, the component view should emit a new
size request (again in points and based on 100% zoom) so that the container
can reallocate space and perform any additional layout tasks it deems necessary.</p>
    <p>The above zooming mechanism is made more complicated because the current
size request mechanism is integer/pixel based, and we need point based granularity
using floating point values. &nbsp;We already have a mechanism to perform
this transformation, GnomeCanvasWidget. &nbsp;The canvas also incorporates
an easy to use zooming mechanism.</p>
    <p>Another consideration is whether user resizing of a subcomponent should
scale the component view, or crop it. &nbsp;Word, for example, uses a cropping
paradigm, where the zoom of the component is not impacted, and only the visible
extent of the document changes as the user resizes the component. &nbsp;While
it is somewhat counterintuitive to show only a portion of a subcomponent,
we must recognize that some users may be used to this sort of behavior and
consider providing an alternative mechanism to perform this operation.</p>
    <p>Perhaps subcomponents could expose a standard property to identify
if they support cropping. &nbsp;A zoom_factor property would also be necessary
so that when the container sets a new size allocation, the component could
render its visible extent at a given zoom factor for the specified size allocation.</p>
    <p> </p>
    <p>The subcomponent must support at least a subset of its editing capabilities 
via "in-place" activation of its view controls.&nbsp; The subcomponent should
merge UI&nbsp;elements into the container's UI to provide an embedded editing
capability.&nbsp; It is not necessary to provide all of the editing functionality
that the subcomponent's native application provides, however. </p>
    <p>Where possible, a subcomponent should support both canvas and widget 
based view controls.&nbsp; Until such time as the widget infrastructure becomes
more canvas-like, it is anticipated that canvas based subcomponents will
be more useful.&nbsp; It is hard to imagine an acceptable document layout
implementation using tables and boxes.&nbsp; The canvas is currently better
suited to the fine positioning and sizing requirements of a document application.<u></u>
 </p>
    <p><u>Persistence:</u> <br>
A subcomponent must be able to save and restore its state via a predictable
interface.&nbsp; A compound document container must be able to serialize
the state information for all of its subcomponents. The subcomponent must
also have a mechanism to notify the container when the component has changed
since its state was saved last.</p>
    </blockquote>
  
    <p><br>
    <b>The Original Compound Document interfaces:</b> </p>
    <p>The following interfaces represent the compound document architecture 
as of bonobo-1.0.&nbsp; They are primarily unused as of GNOME 1.4 and have 
very little utility.&nbsp; Clearly, wholesale restructuring is required. </p>
    <ul>
 
      <li> ClientSite:&nbsp; A client helper object which "binds" to the
remote Embeddable object.&nbsp; The interface exposes 3 methods, none of
which provide any utility to a remote component.:</li>
  
      <ul>
 
        <li> getContainer():&nbsp; There is nothing useful that a remote
component can do with the ClientSite's parent container.</li>
  
        <li> showWindow(): Is to notify the client if a containee wants to
show its own separate editing window.</li>
  
        <li> saveObject(): This should be accomplished by QI for the component's
persist interfaces.</li>
 
      </ul>
  
      <li> View: A Control subclass that exposes one addition zooming method.&nbsp; 
Zooming is a complex issue as described above, but View::setZoomFactor is
not a desirable way to manage this. A zoom_factor property would be better.</li>
  
      <li> ViewFrame: A ControlFrame subclass with the dubious method, getClientSite.&nbsp; 
As displayed above, there's not much point to obtaining a ClientSite ref.</li>
  
      <li> Embeddable: The sub-document model object interface.&nbsp; It
exposes the following methods:</li>
  
      <ul>
 
        <li> setClientSite: If the ClientSite is worthless to the Embeddable,
why would it care?</li>
  
        <li> getClientSite: Ditto.</li>
  
        <li> setHostName: Documented as being useful for labeling separate
editing window.&nbsp; Since an Embeddable need never open such a beast, there's
no need to label it.</li>
  
        <li> setURI:&nbsp; the URI this component represents.&nbsp; If this
is really necessary, a property would be more appropriate.</li>
  
        <li> close:&nbsp; The normal ref counting mechanism should cause
clean shutdown of Embeddables.&nbsp; Besides, there is no way a container
could know if&nbsp; it is the sole user of a component and is allowed to
shut it down.</li>
  
        <li> advise: This is COM/OLE cruft that if it were needed would be
better provided in Bonobo by an EventSource.</li>
  
        <li> unadvise: Ditto.</li>
  
        <li> getMiscStatus:&nbsp; Undocumented, and it's hard to imagine
what need this could possible fill.</li>
  
        <li> createView: Useful, but misplaced here.&nbsp; This should be
in its own queryable interface so that containers can determine the view
capabilities of potential embeddables prior to activation.</li>
  
        <li> createCanvasItem: Also useful, and similarly misplaced.</li>
 
      </ul>
 
    </ul>
 The above interfaces are inconsistent with the current bonobo direction of
minimizing client-side helper objects.&nbsp; In the View/ViewFrame case, they
are so thin a wrapper around the Control interfaces as to be virtually indistinguishable
from them, save by name.&nbsp; The ClientSite, View, and ViewFrame interfaces
can be eliminated outright.&nbsp; The useful bits of Embeddable need to be
split out into queryable interfaces, so it too can be eliminated. 
    <p><b>Proposed Compound Document Interfaces:</b> </p>
    <p>The two useful methods from Embeddable will be split out into their 
own interfaces.&nbsp; Since the View Interface was so thin, the comparable 
interface will instead return a control and the ControlFrame implementation 
can be easily used to provide a proper Socket subclass. </p>
    <p>i<tt>nterface ControlFactory {</tt> <br>
    <tt>&nbsp;&nbsp;&nbsp;&nbsp; Control&nbsp;&nbsp;&nbsp; createControl (in
ControlFrame frame,</tt> <br>
    <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
in UIContainer uic);</tt> <br>
    <tt>};</tt><tt></tt> </p>
    <p><tt>interface CanvasComponentFactory {</tt> <br>
    <tt>&nbsp;&nbsp;&nbsp; Canvas::Component&nbsp;&nbsp;&nbsp; createCanvasComponent 
(in boolean aa,</tt> <br>
    <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
in Canvas::ComponentProxy proxy);</tt> <br>
    <tt>};</tt><tt></tt> </p>
    <p>Dirty status is obtainable via the persist interfaces, but is currently
duplicated in all the Persist subclasses. &nbsp;This method will be moved
to Bonobo::Persist to eliminate duplication. Parallel discussions are occuring
regarding Cut/Paste Drag/Drop related enhancements to the persist interfaces.&nbsp;
These enhancements will provide even more utility to the container for managing
subcomponents, and will form the basis for linking in the compound document
environment.&nbsp; Persist and its subclasses are the workhorses for the
model side of compound documents. </p>
    <p>Any component wishing to be considered compound document ready would 
need to expose at a minimum, one of the above "view" interface factories, 
and either PersistStream or PersistStorage for save/load.&nbsp; Additionally, 
The existing Print interface should be exposed to provide a print rendering 
capability.&nbsp; The above interfaces should be sufficient for containers 
to layout and render subcomponents and manage their persistence. <br>
&nbsp; </p>
    </body>
    </html>