org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/viewers/xycharts/ITmfChartTimeProvider.java

   1 /**********************************************************************
   2  * Copyright (c) 2013 Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials are
   5  * made available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *   Bernd Hufmann - Initial API and implementation
  11  **********************************************************************/
  12 package org.eclipse.linuxtools.tmf.ui.viewers.xycharts;
  13
  14 import org.eclipse.linuxtools.tmf.ui.viewers.ITmfViewer;
  15
  16 /**
  17  * Interface for providing and updating time information. This is typically
  18  * implemented by a chart viewer that is displaying trace data over time where
  19  * the time is shown on the x-axis.
  20  *
  21  * @author Bernd Hufmann
  22  * @since 3.0
  23  */
  24 public interface ITmfChartTimeProvider extends ITmfViewer {
  25     /**
  26      * Gets the start time of trace
  27      *
  28      * @return start time of trace
  29      */
  30     long getStartTime();
  31
  32     /**
  33      * Gets the end time of trace
  34      *
  35      * @return End time of trace
  36      */
  37     long getEndTime();
  38
  39     /**
  40      * Gets the start time of current time range displayed
  41      *
  42      * @return start time of current time range
  43      */
  44     long getWindowStartTime();
  45
  46     /**
  47      * Gets the end time of current time range displayed
  48      *
  49      * @return End time of current time range
  50      */
  51     long getWindowEndTime();
  52
  53     /**
  54      * Gets the duration of the current time range displayed
  55      *
  56      * @return duration of current time range
  57      */
  58     long getWindowDuration();
  59
  60     /**
  61      * Gets the begin time of the selected range
  62      *
  63      * @return the begin time of the selected range
  64      */
  65     long getSelectionBeginTime();
  66
  67     /**
  68      * Gets the end time of the selected range
  69      *
  70      * @return end time of the selected range
  71      */
  72     long getSelectionEndTime();
  73
  74     /**
  75      * Returns a constant time offset that is used to normalize the time values
  76      * to a range of 0..53 bits to avoid loss of precision when converting
  77      * long <-> double.
  78      *
  79      * Time values are stored in TMF as long values. The SWT chart library
  80      * uses values of type double (on x and y axis). To avoid loss of
  81      * precision when converting long <-> double the values need to fit
  82      * within 53 bits.
  83      *
  84      * Subtract the offset when using time values provided externally for
  85      * internal usage in SWT chart. Add the offset when using time values
  86      * provided by SWT chart (e.g. for display purposes) and when broadcasting
  87      * them externally (e.g. time synchronization signals).
  88      *
  89      * For example the offset can be calculated as the time of the first
  90      * time value in the current time range to be displayed in the chart.
  91      * Add +1 to avoid 0 when using logarithmic scale.
  92      *
  93      * t0=10000, t2=20000, tn=N -> timeOffset=t0-1
  94      * -> t0'=1, t1'=10001, tn'=N-timeOffset
  95      *
  96      * where t0 ... tn are times used externally and t0' ... tn' are times
  97      * used internally by the SWT chart.
  98      *
  99      * @return the time offset
 100      */
 101     long getTimeOffset();
 102
 103     /**
 104      * Method to notify about a change of the current selected time.
 105      *
 106      * @param currentBeginTime
 107      *            The current selection begin time
 108      * @param currentEndTime
 109      *            The current selection end time
 110      */
 111     void updateSelectionRange(long currentBeginTime, long currentEndTime);
 112
 113     /**
 114      * Updates the current time range window.
 115      *
 116      * @param windowStartTime
 117      *            The window start time
 118      * @param windowEndTime
 119      *            The window end time.
 120      */
 121     void updateWindow(long windowStartTime, long windowEndTime);
 122
 123
 124 }