e3bb3bf56d
2007/02/06 17:18:02 thb 1.1.2.2: #i37778# Moved clear() method from View to ViewLayer (also sprites need to be cleared); fixed a few more cases of local code style violations; removed redundant inline keywords; finished Layer/LayerManager rework (Layer now represents ViewLayers, shapes and rendering are fully under LayerManager control); made shape comparator reusable 2007/01/29 14:01:51 thb 1.1.2.1: Issue number: #i37778# Larger slideshow refactoring. Wrote design and coding style manifest, and adapted the code to actually conform to this. In detail: - cleaned up ownership/disposable/weak_ptr story. removed hacks and explicit Disposable implementations, where workaround were available - removed object mutices, where superfluous - reworked EventMultiplexer (using templatized listener class now), added more events. EventMultiplexer now serves as a true blackboard - reworked directory structure: disjunct parts are now physically separated into directories, instantiation happens via factories & abstract interfaces - added CursorManager, to make setting mouse cursor less hackish - reworked DrawShape, to implement SeparateListener pattern - reworked IntrinsicAnimationActivity, to avoid cyclic references - modified hyperlink & shape cursor handling to communicate via EventMultiplexer - renamed & cleaned up files (presentation.cxx now named slideshowimpl.cxx, etc.) - added first version of the z-order fix to layer/layermanager - cleaned up include guards and include syntax
95 lines
3.8 KiB
Text
95 lines
3.8 KiB
Text
Slideshow module design & coding manifest
|
|
=========================================
|
|
|
|
Coding style:
|
|
-------------
|
|
|
|
- modified BSD style:
|
|
if( !test )
|
|
{
|
|
function( arg1,
|
|
arg2,
|
|
arg3 );
|
|
}
|
|
|
|
- members are always named maSomething
|
|
|
|
- no tabs, indent four spaces
|
|
|
|
- Class names (and type names in general) are UpperCamelCase, method
|
|
names lowerCamelCase
|
|
|
|
- all file names are lowercase, header files end in hxx, source files
|
|
in cxx; one header per class, only one linkable class per cxx.
|
|
|
|
- header guards follow this scheme: INCLUDED_SLIDESHOW_<CLASSNAME>_HXX
|
|
|
|
- module-external headers, and system headers are included like this:
|
|
#include <module/header.hxx> or #include <boost/shared_ptr.hpp>.
|
|
module-internal headers are included like this:
|
|
#include "header.hxx"
|
|
No external header guards are used in cxx files
|
|
|
|
|
|
Design
|
|
------
|
|
|
|
- currently, the slideshow module is basically
|
|
single-threaded. Therefore, the XSlideShow interface must be called
|
|
from the _main thread_ (this precondition is asserted). Other
|
|
listener interfaces, which we could not impose this limitation upon
|
|
(XSlideShowView's XMouseMotionListener, XMouseListener,
|
|
XPaintListener and XModifyListener) will queue the events, and
|
|
process them in the main thread. Therefore, XSlideShow::update()
|
|
needs to be called frequently from the slideshow client.
|
|
|
|
This design is necessitated by the fact that at least one XCanvas
|
|
implementation (vclcanvas) must be called from the main thread
|
|
only. Once the UNO threading framework is integrated, this can be
|
|
changed.
|
|
|
|
As of now, SlideView, SlideShowImpl, EventMultiplexerListener and
|
|
DummyRenderer are exposed to calls from the outside world; of
|
|
those, SlideView and EventMultiplexerListener serialize the calls
|
|
by enqueuing events, SlideShowImpl imposes the hard constraint of
|
|
being called from the main thread, and DummyRenderer is content
|
|
with a simple object mutex. As a side effect, the global EventQueue
|
|
must be thread-safe (as one of the few internal objects having an
|
|
object mutex)
|
|
|
|
- wherever possible, abstract interfaces and shared_ptr are used.
|
|
* exception: global objects like EventQueue,
|
|
and tightly collaborating classes, like Slide/LayerManager/Layer
|
|
|
|
- since shared_ptr can lead to circular references (resulting in
|
|
memory leaks), some care needs to be taken to avoid those. Where
|
|
circular references are inevitable, or can happen by accident,
|
|
classes implement the Disposable interface. The owner of the object
|
|
then calls dispose() on its owned objects.
|
|
Another way of avoiding circular references are weak_ptr, which are
|
|
used in a few places.
|
|
One of those places are the ViewEventHandlers, which are held weak
|
|
on the EventMultiplexer. Otherwise, every class in need of view
|
|
events would have to delegate listening to a dedicated child
|
|
object, or burden their clients with the Disposable interface.
|
|
|
|
- Pattern: Separate Listener
|
|
To avoid circular shared_ptr references, classes in need to
|
|
register a listener at EventMultiplexer often implement the
|
|
corresponding listener interface in a separate object. This object
|
|
is held via shared_ptr by the original class, and normally
|
|
registered at the EventMultiplexer (and thus held by shared_ptr
|
|
there, too). The separate listener object in turn holds the
|
|
original object by plain reference. This is safe, if the original
|
|
object removes the listener from the EventMultiplexer, before or
|
|
within the destructor.
|
|
|
|
|
|
Testing
|
|
=======
|
|
|
|
Before merging changes to HEAD, besides making sure the usual QA has
|
|
been done, also run the unit and integration tests in the
|
|
slideshow/test directory. Issuing a "dmake test" should run the unit
|
|
tests, and generate a "demoshow" binary, that should also be run and
|
|
checked to work properly.
|