tmf/org.eclipse.tracecompass.tmf.ui/src/org/eclipse/tracecompass/tmf/ui/widgets/timegraph/widgets/ITimeDataProvider.java

   1 /*****************************************************************************
   2  * Copyright (c) 2007, 2016 Intel Corporation, Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *   Intel Corporation - Initial API and implementation
  11  *   Ruslan A. Scherbakov, Intel - Initial API and implementation
  12  *   Alvaro Sanchez-Leon - Updated for TMF
  13  *   Geneviève Bastien - Added methods to save a time range selection
  14  *   Patrick Tasse - Refactoring, support for range selection
  15  *****************************************************************************/
  16
  17 package org.eclipse.tracecompass.tmf.ui.widgets.timegraph.widgets;
  18
  19 import org.eclipse.tracecompass.tmf.ui.widgets.timegraph.widgets.Utils.TimeFormat;
  20
  21 /**
  22  * Time data provider interface, for use in the timegraph widget.
  23  *
  24  * @author Alvaro Sanchez-Leon
  25  * @author Patrick Tasse
  26  * @author Xavier Raynaud
  27  */
  28 public interface ITimeDataProvider {
  29
  30     /**
  31      * Updates the selection begin and end time and notifies the selection
  32      * listeners about the new selection range (if it has changed).
  33      * <p>
  34      * If ensureVisible is true, the window range will be centered either on the
  35      * selection begin time (if it has changed) or otherwise on the selection
  36      * end time, if and only if that time is outside of the current window. If
  37      * the window range is modified, the range listeners will be notified.
  38      *
  39      * @param beginTime
  40      *            the selection begin time
  41      * @param endTime
  42      *            the selection end time
  43      * @param ensureVisible
  44      *            if true, ensure visibility of the new selection range boundary
  45      * @since 2.0
  46      */
  47     void setSelectionRangeNotify(long beginTime, long endTime, boolean ensureVisible);
  48
  49     /**
  50      * Updates the selection begin and end time.
  51      * <p>
  52      * If ensureVisible is true, the window range will be centered either on the
  53      * selection begin time (if it has changed) or otherwise on the selection
  54      * end time, if and only if that time is outside of the current window. If
  55      * the window range is modified, the range listeners will be notified.
  56      *
  57      * @param beginTime
  58      *            the selection begin time
  59      * @param endTime
  60      *            the selection end time
  61      * @param ensureVisible
  62      *            if true, ensure visibility of the new selection range boundary
  63      * @since 2.0
  64      */
  65     void setSelectionRange(long beginTime, long endTime, boolean ensureVisible);
  66
  67     /**
  68      * @return The begin time of the current selection
  69      */
  70     long getSelectionBegin();
  71
  72     /**
  73      * @return The end time of the current selection
  74      */
  75     long getSelectionEnd();
  76
  77     /**
  78      * Get the user-specified bounds begin time. May be set to SWT.DEFAULT. For
  79      * the actual bound use {@link #getMinTime()}.
  80      *
  81      * @return The user-specified begin time, or SWT.DEFAULT if input bound used
  82      */
  83     long getBeginTime();
  84
  85     /**
  86      * Get the user-specified bounds end time. May be set to SWT.DEFAULT. For
  87      * the actual bound use {@link #getMaxTime()}.
  88      *
  89      * @return The user-specified end time, or SWT.DEFAULT if input bound used
  90      */
  91     long getEndTime();
  92
  93     /**
  94      * @return The bounds minimum time
  95      */
  96     long getMinTime();
  97
  98     /**
  99      * @return The bounds maximum time
 100      */
 101     long getMaxTime();
 102
 103     /**
 104      * @return The current window start time
 105      */
 106     long getTime0();
 107
 108     /**
 109      * @return The current window end time
 110      */
 111     long getTime1();
 112
 113     /**
 114      * @return The minimal time interval
 115      */
 116     long getMinTimeInterval();
 117
 118     /**
 119      * Updates the window range and notify the range listeners.
 120      *
 121      * @param time0
 122      *            the window start time
 123      * @param time1
 124      *            the window end time
 125      */
 126     void setStartFinishTimeNotify(long time0, long time1);
 127
 128     /**
 129      * Update the window range but do not notify the range listeners.
 130      *
 131      * @param time0
 132      *            the window start time
 133      * @param time1
 134      *            the window end time
 135      */
 136     void setStartFinishTime(long time0, long time1);
 137
 138     /**
 139      * Notify the range listeners without updating the time range.
 140      */
 141     void notifyStartFinishTime();
 142
 143     /**
 144      * Updates the selection time and notifies the selection listeners about the
 145      * new selection time (if it has changed).
 146      * <p>
 147      * If ensureVisible is true, the window range will be centered on the
 148      * selection time, if and only if that time is outside of the current
 149      * window. If the window range is modified, the range listeners will be
 150      * notified.
 151      *
 152      * @param time
 153      *            the selection time
 154      * @param ensureVisible
 155      *            if true, ensure visibility of the new selection time
 156      */
 157     void setSelectedTimeNotify(long time, boolean ensureVisible);
 158
 159     /**
 160      * Updates the selection time.
 161      * <p>
 162      * If ensureVisible is true, the window range will be centered on the
 163      * selection time, if and only if that time is outside of the current
 164      * window. If the window range is modified, the range listeners will be
 165      * notified.
 166      *
 167      * @param time
 168      *            the selection time
 169      * @param ensureVisible
 170      *            if true, ensure visibility of the new selection time
 171      */
 172     void setSelectedTime(long time, boolean ensureVisible);
 173
 174     /**
 175      * Reset the start and end times and notify the registered listeners
 176      */
 177     void resetStartFinishTime();
 178
 179     /**
 180      * Reset the start and end times.
 181      *
 182      * @param notify
 183      *            if true, notify the registered listeners
 184      * @since 2.0
 185      */
 186     default void resetStartFinishTime(boolean notify) {
 187         if (notify) {
 188             setStartFinishTimeNotify(getMinTime(), getMaxTime());
 189         } else {
 190             setStartFinishTime(getMinTime(), getMaxTime());
 191         }
 192     }
 193
 194     /**
 195      * @return The names' width
 196      */
 197     int getNameSpace();
 198
 199     /**
 200      * Set the names' width
 201      *
 202      * @param width
 203      */
 204     void setNameSpace(int width);
 205
 206     /**
 207      * @return The width for timestamps
 208      */
 209     int getTimeSpace();
 210
 211     /**
 212      * @return the time format, one of:
 213      * <ul>
 214      *   <li>{@link TimeFormat#CALENDAR} absolute time, displayed as year/month/day/hours/minutes/seconds/ms/us/ns
 215      *   <li>{@link TimeFormat#RELATIVE} relative time, displayed as seconds/ms/us/ns
 216      *   <li>{@link TimeFormat#NUMBER}   number, displayed as long values.
 217      *   <li>{@link TimeFormat#CYCLES}   cycles, displayed as long values.
 218      * </ul>
 219      */
 220     TimeFormat getTimeFormat();
 221 }