slideshow/manifest.txt

   1 #
   2 # This file is part of the LibreOffice project.
   3 #
   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/.
   7 #
   8 # This file incorporates work covered by the following license notice:
   9 #
  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 .
  17 #
  18
  19 Slideshow module design & coding manifest
  20 =========================================
  21
  22 Coding style:
  23 -------------
  24
  25  - modified BSD style:
  26    if( !test )
  27    {
  28        function( arg1,
  29                  arg2,
  30                  arg3 );
  31    }
  32
  33  - members are always named maSomething
  34
  35  - no tabs, indent four spaces
  36
  37  - Class names (and type names in general) are UpperCamelCase, method
  38    names lowerCamelCase
  39
  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.
  42
  43  - header guards follow this scheme: INCLUDED_SLIDESHOW_<CLASSNAME>_HXX
  44
  45  - module-external headers, and system headers are included like this:
  46    #include <module/header.hxx>.
  47    module-internal headers are included like this:
  48    #include "header.hxx"
  49    No external header guards are used in cxx files
  50
  51
  52 Design
  53 ------
  54
  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.
  63
  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.
  68
  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)
  77
  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
  81
  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.
  93
  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.
 104
 105
 106 Testing
 107 =======
 108
 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.