1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 #ifndef INCLUDED_CANVAS_ELAPSEDTIME_HXX 29 #define INCLUDED_CANVAS_ELAPSEDTIME_HXX 30 31 #include <sal/types.h> 32 33 #include "boost/shared_ptr.hpp" 34 35 namespace canvas 36 { 37 namespace tools 38 { 39 /** Calculate elapsed time. 40 41 This class provides several time-measurement and 42 -management functions. In its simplest use-case, it 43 measures the time from its creation. 44 */ 45 class ElapsedTime 46 { 47 public: 48 /** Create a new ElapsedTime object 49 50 The moment of construction starts the time 51 measurement. That means, a subsequent getElapsedTime() 52 call will return the time difference between object 53 creation and getElapsedTime() call. 54 */ 55 ElapsedTime(); 56 57 /** Creates a new ElapsedTime object based on another 58 timer. 59 60 The moment of construction starts the time 61 measurement. That means, a subsequent getElapsedTime() 62 call will return the time difference between object 63 creation and getElapsedTime() call. All time values 64 are not taken from the system's time base, but from 65 the provided timer. 66 */ 67 ElapsedTime( ::boost::shared_ptr<ElapsedTime> const & pTimeBase ); 68 69 /** Gets this timer's base timer. 70 */ 71 ::boost::shared_ptr<ElapsedTime> const & getTimeBase() const; 72 73 /** Reset the time 74 75 The instance of the reset() call starts the time 76 measurement from scratch. That means, a subsequent 77 getElapsedTime() call will return the time difference 78 between reset() and getElapsedTime() call. 79 */ 80 void reset(); 81 82 /** Query the elapsed time 83 84 This method returns the elapsed time in seconds 85 between either the construction of this object, or the 86 last reset() call, if any (but see the time modulation 87 methods below, for means to modify the otherwise 88 continuous flow of time). 89 90 @return the elapsed time in seconds. 91 */ 92 double getElapsedTime() const; 93 94 /** Pauses the running timer. 95 96 This method stops the time, as returned by this 97 object, until continueTimer() is called. During this 98 period, getElapsedTime() will always return the same 99 time value (i.e. the instant when pauseTimer() was 100 called). 101 */ 102 void pauseTimer(); 103 104 /** Continues the paused timer. 105 106 This method re-enables the time flow, that is, time 107 starts running again for clients calling 108 getElapsedTime(). The (subtle) difference to the 109 holdTimer/releaseTimer() methods below is, that there 110 is no perceived time 'jump' between the pauseTimer() 111 call and the continueTimer() call, i.e. the time 112 starts over with the same value it has stopped on 113 pauseTimer(). 114 */ 115 void continueTimer(); 116 117 /** Adjusts the timer, hold and pause times. 118 119 This method modifies the time as returned by this 120 object by the specified amount. This affects the time 121 as returned by getElapsedTime(), regardless of the 122 mode (e.g. paused, or on hold). 123 124 @param fOffset 125 This value will be added to the current time, i.e. the 126 next call to getElapsedTime() (when performed 127 immediately) will be adjusted by fOffset. 128 129 @param bLimitToLastQueriedTime 130 Limits the given offset to the time that has been 131 taken via getElapsedTime() 132 */ 133 void adjustTimer( double fOffset, 134 bool bLimitToLastQueriedTime = true ); 135 136 /** Holds the current time. 137 138 This call makes the timer hold the current time 139 (e.g. getElapsedTime() will return the time when 140 holdTimer() was called), while the underlying time is 141 running on. When releaseTimer() is called, the time 142 will 'jump' to the then-current, underlying time. This 143 is equivalent to pressing the "interim time" button on 144 a stop watch, which shows this stopped time, while the 145 clock keeps running internally. 146 */ 147 void holdTimer(); 148 149 /** Releases a held timer. 150 151 After this call, the timer again returns the running 152 time on getElapsedTime(). 153 */ 154 void releaseTimer(); 155 156 private: 157 static double getSystemTime(); 158 double getCurrentTime() const; 159 double getElapsedTimeImpl() const; // does not set m_fLastQueriedTime 160 161 const ::boost::shared_ptr<ElapsedTime> m_pTimeBase; 162 163 /// To validate adjustTimer() calls with bLimitToLastQueriedTime=true 164 mutable double m_fLastQueriedTime; 165 166 /// Start time, from which the difference to the time base is returned 167 double m_fStartTime; 168 169 /// Instant, when last pause or hold started, relative to m_fStartTime 170 double m_fFrozenTime; 171 172 /// True, when in pause mode 173 bool m_bInPauseMode; 174 175 /// True, when in hold mode 176 bool m_bInHoldMode; 177 }; 178 179 } 180 } 181 182 #endif /* INCLUDED_CANVAS_ELAPSEDTIME_HXX */ 183