content/smil/nsSMILInstanceTime.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is the Mozilla SMIL module.
  16  *
  17  * The Initial Developer of the Original Code is Brian Birtles.
  18  * Portions created by the Initial Developer are Copyright (C) 2005
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Brian Birtles <birtles@gmail.com>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef NS_SMILINSTANCETIME_H_
  39 #define NS_SMILINSTANCETIME_H_
  40
  41 #include "nsSMILTimeValue.h"
  42 #include "nsAutoPtr.h"
  43
  44 class nsSMILInterval;
  45 class nsSMILTimeContainer;
  46 class nsSMILTimeValueSpec;
  47
  48 //----------------------------------------------------------------------
  49 // nsSMILInstanceTime
  50 //
  51 // An instant in document simple time that may be used in creating a new
  52 // interval.
  53 //
  54 // For an overview of how this class is related to other SMIL time classes see
  55 // the documentation in nsSMILTimeValue.h
  56 //
  57 // These objects are owned by an nsSMILTimedElement but MAY also be referenced
  58 // by:
  59 //
  60 // a) nsSMILIntervals that belong to the same nsSMILTimedElement and which refer
  61 //    to the nsSMILInstanceTimes which form the interval endpoints; and/or
  62 // b) nsSMILIntervals that belong to other nsSMILTimedElements but which need to
  63 //    update dependent instance times when they change or are deleted.
  64 //    E.g. for begin='a.begin', 'a' needs to inform dependent
  65 //    nsSMILInstanceTimes if its begin time changes. This notification is
  66 //    performed by the nsSMILInterval.
  67
  68 class nsSMILInstanceTime
  69 {
  70 public:
  71   // Instance time source. Times generated by events, syncbase relationships,
  72   // and DOM calls behave differently in some circumstances such as when a timed
  73   // element is reset.
  74   enum nsSMILInstanceTimeSource {
  75     // No particularly significant source, e.g. offset time, 'indefinite'
  76     SOURCE_NONE,
  77     // Generated by a DOM call such as beginElement
  78     SOURCE_DOM,
  79     // Generated by a syncbase relationship
  80     SOURCE_SYNCBASE,
  81     // Generated by an event
  82     SOURCE_EVENT
  83   };
  84
  85   nsSMILInstanceTime(const nsSMILTimeValue& aTime,
  86                      nsSMILInstanceTimeSource aSource = SOURCE_NONE,
  87                      nsSMILTimeValueSpec* aCreator = nsnull,
  88                      nsSMILInterval* aBaseInterval = nsnull);
  89   ~nsSMILInstanceTime();
  90   void Unlink();
  91   void HandleChangedInterval(const nsSMILTimeContainer* aSrcContainer,
  92                              PRBool aBeginObjectChanged,
  93                              PRBool aEndObjectChanged);
  94   void HandleDeletedInterval();
  95   void HandleFilteredInterval();
  96
  97   const nsSMILTimeValue& Time() const { return mTime; }
  98   const nsSMILTimeValueSpec* GetCreator() const { return mCreator; }
  99
 100   PRBool IsDynamic() const { return !!(mFlags & kDynamic); }
 101   PRBool IsFixedTime() const { return !(mFlags & kMayUpdate); }
 102   PRBool FromDOM() const { return !!(mFlags & kFromDOM); }
 103
 104   PRBool ShouldPreserve() const;
 105   void   UnmarkShouldPreserve();
 106
 107   void AddRefFixedEndpoint();
 108   void ReleaseFixedEndpoint();
 109
 110   void DependentUpdate(const nsSMILTimeValue& aNewTime)
 111   {
 112     NS_ABORT_IF_FALSE(!IsFixedTime(),
 113         "Updating an instance time that is not expected to be updated");
 114     mTime = aNewTime;
 115   }
 116
 117   PRBool IsDependent() const { return !!mBaseInterval; }
 118   PRBool IsDependentOn(const nsSMILInstanceTime& aOther) const;
 119   const nsSMILInterval* GetBaseInterval() const { return mBaseInterval; }
 120
 121   PRBool SameTimeAndBase(const nsSMILInstanceTime& aOther) const
 122   {
 123     return mTime == aOther.mTime && GetBaseTime() == aOther.GetBaseTime();
 124   }
 125
 126   // Get and set a serial number which may be used by a containing class to
 127   // control the sort order of otherwise similar instance times.
 128   PRUint32 Serial() const { return mSerial; }
 129   void SetSerial(PRUint32 aIndex) { mSerial = aIndex; }
 130
 131   NS_INLINE_DECL_REFCOUNTING(nsSMILInstanceTime)
 132
 133 protected:
 134   void SetBaseInterval(nsSMILInterval* aBaseInterval);
 135   const nsSMILInstanceTime* GetBaseTime() const;
 136
 137   nsSMILTimeValue mTime;
 138
 139   // Internal flags used to represent the behaviour of different instance times
 140   enum {
 141     // Indicates that this instance time was generated by an event or a DOM
 142     // call. Such instance times require special handling when (i) the owning
 143     // element is reset, and (ii) when a backwards seek is performed and the
 144     // timing model is reconstructed.
 145     kDynamic = 1,
 146
 147     // Indicates that this instance time is referred to by an
 148     // nsSMILTimeValueSpec and as such may be updated. Such instance time should
 149     // not be filtered out by the nsSMILTimedElement even if they appear to be
 150     // in the past as they may be updated to a future time.
 151     kMayUpdate = 2,
 152
 153     // Indicates that this instance time was generated from the DOM as opposed
 154     // to an nsSMILTimeValueSpec. When a 'begin' or 'end' attribute is set or
 155     // reset we should clear all the instance times that have been generated by
 156     // that attribute (and hence an nsSMILTimeValueSpec), but not those from the
 157     // DOM.
 158     kFromDOM = 4,
 159
 160     // Indicates that this instance time was used as the endpoint of an interval
 161     // that has been filtered or removed. However, since it is a dynamic time it
 162     // should be preserved and not filtered.
 163     kWasDynamicEndpoint = 8
 164   };
 165   PRUint8       mFlags;   // Combination of kDynamic, kMayUpdate, etc.
 166   PRPackedBool  mVisited; // (mutable) Cycle tracking
 167
 168   // Additional reference count to determine if this instance time is currently
 169   // used as a fixed endpoint in any intervals. Instance times that are used in
 170   // this way should not be removed when the owning nsSMILTimedElement removes
 171   // instance times in response to a restart or in an attempt to free up memory
 172   // by filtering out old instance times.
 173   //
 174   // Instance times are only shared in a few cases, namely:
 175   // a) early ends,
 176   // b) zero-duration intervals, and
 177   // c) momentarily whilst establishing new intervals and updating the current
 178   //    interval
 179   // Hence the limited range of a PRUint16 should be more than adequate.
 180   PRUint16      mFixedEndpointRefCnt;
 181
 182   PRUint32      mSerial; // A serial number used by the containing class to
 183                          // specify the sort order for instance times with the
 184                          // same mTime.
 185
 186   nsSMILTimeValueSpec* mCreator; // The nsSMILTimeValueSpec object that created
 187                                  // us. (currently only needed for syncbase
 188                                  // instance times.)
 189   nsSMILInterval* mBaseInterval; // Interval from which this time is derived
 190                                  // (only used for syncbase instance times)
 191 };
 192
 193 #endif // NS_SMILINSTANCETIME_H_