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