xref: /aoo41x/main/slideshow/manifest.txt (revision c966c276)
1# *************************************************************
2#
3#  Licensed to the Apache Software Foundation (ASF) under one
4#  or more contributor license agreements.  See the NOTICE file
5#  distributed with this work for additional information
6#  regarding copyright ownership.  The ASF licenses this file
7#  to you under the Apache License, Version 2.0 (the
8#  "License"); you may not use this file except in compliance
9#  with the License.  You may obtain a copy of the License at
10#
11#    http://www.apache.org/licenses/LICENSE-2.0
12#
13#  Unless required by applicable law or agreed to in writing,
14#  software distributed under the License is distributed on an
15#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16#  KIND, either express or implied.  See the License for the
17#  specific language governing permissions and limitations
18#  under the License.
19#
20# *************************************************************
21
22Slideshow module design & coding manifest
23=========================================
24
25Coding style:
26-------------
27
28 - modified BSD style:
29   if( !test )
30   {
31       function( arg1,
32                 arg2,
33                 arg3 );
34   }
35
36 - members are always named maSomething
37
38 - no tabs, indent four spaces
39
40 - Class names (and type names in general) are UpperCamelCase, method
41   names lowerCamelCase
42
43 - all file names are lowercase, header files end in hxx, source files
44   in cxx; one header per class, only one linkable class per cxx.
45
46 - header guards follow this scheme: INCLUDED_SLIDESHOW_<CLASSNAME>_HXX
47
48 - module-external headers, and system headers are included like this:
49   #include <module/header.hxx> or #include <boost/shared_ptr.hpp>.
50   module-internal headers are included like this:
51   #include "header.hxx"
52   No external header guards are used in cxx files
53
54
55Design
56------
57
58 - currently, the slideshow module is basically
59   single-threaded. Therefore, the XSlideShow interface must be called
60   from the _main thread_ (this precondition is asserted). Other
61   listener interfaces, which we could not impose this limitation upon
62   (XSlideShowView's XMouseMotionListener, XMouseListener,
63   XPaintListener and XModifyListener) will queue the events, and
64   process them in the main thread. Therefore, XSlideShow::update()
65   needs to be called frequently from the slideshow client.
66
67   This design is necessitated by the fact that at least one XCanvas
68   implementation (vclcanvas) must be called from the main thread
69   only. Once the UNO threading framework is integrated, this can be
70   changed.
71
72   As of now, SlideView, SlideShowImpl, EventMultiplexerListener and
73   DummyRenderer are exposed to calls from the outside world; of
74   those, SlideView and EventMultiplexerListener serialize the calls
75   by enqueuing events, SlideShowImpl imposes the hard constraint of
76   being called from the main thread, and DummyRenderer is content
77   with a simple object mutex. As a side effect, the global EventQueue
78   must be thread-safe (as one of the few internal objects having an
79   object mutex)
80
81 - wherever possible, abstract interfaces and shared_ptr are used.
82   * exception: global objects like EventQueue,
83     and tightly collaborating classes, like Slide/LayerManager/Layer
84
85 - since shared_ptr can lead to circular references (resulting in
86   memory leaks), some care needs to be taken to avoid those. Where
87   circular references are inevitable, or can happen by accident,
88   classes implement the Disposable interface. The owner of the object
89   then calls dispose() on its owned objects.
90   Another way of avoiding circular references are weak_ptr, which are
91   used in a few places.
92   One of those places are the ViewEventHandlers, which are held weak
93   on the EventMultiplexer. Otherwise, every class in need of view
94   events would have to delegate listening to a dedicated child
95   object, or burden their clients with the Disposable interface.
96
97 - Pattern: Separate Listener
98   To avoid circular shared_ptr references, classes in need to
99   register a listener at EventMultiplexer often implement the
100   corresponding listener interface in a separate object. This object
101   is held via shared_ptr by the original class, and normally
102   registered at the EventMultiplexer (and thus held by shared_ptr
103   there, too). The separate listener object in turn holds the
104   original object by plain reference. This is safe, if the original
105   object removes the listener from the EventMultiplexer, before or
106   within the destructor.
107
108
109Testing
110=======
111
112Before merging changes to HEAD, besides making sure the usual QA has
113been done, also run the unit and integration tests in the
114slideshow/test directory. Issuing a "dmake test" should run the unit
115tests, and generate a "demoshow" binary, that should also be run and
116checked to work properly.
117