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