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