org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/views/histogram/Histogram.java

   1 /*******************************************************************************
   2  * Copyright (c) 2011, 2012 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  *   Francois Chouinard - Initial API and implementation
  11  *   Bernd Hufmann - Changed to updated histogram data model
  12  *   Francois Chouinard - Initial API and implementation
  13  *******************************************************************************/
  14
  15 package org.eclipse.linuxtools.tmf.ui.views.histogram;
  16
  17 import org.eclipse.linuxtools.tmf.ui.views.TmfView;
  18 import org.eclipse.swt.SWT;
  19 import org.eclipse.swt.events.ControlEvent;
  20 import org.eclipse.swt.events.ControlListener;
  21 import org.eclipse.swt.events.KeyEvent;
  22 import org.eclipse.swt.events.KeyListener;
  23 import org.eclipse.swt.events.MouseEvent;
  24 import org.eclipse.swt.events.MouseListener;
  25 import org.eclipse.swt.events.MouseTrackListener;
  26 import org.eclipse.swt.events.PaintEvent;
  27 import org.eclipse.swt.events.PaintListener;
  28 import org.eclipse.swt.graphics.Color;
  29 import org.eclipse.swt.graphics.Font;
  30 import org.eclipse.swt.graphics.FontData;
  31 import org.eclipse.swt.graphics.GC;
  32 import org.eclipse.swt.graphics.Image;
  33 import org.eclipse.swt.layout.GridData;
  34 import org.eclipse.swt.layout.GridLayout;
  35 import org.eclipse.swt.widgets.Canvas;
  36 import org.eclipse.swt.widgets.Composite;
  37 import org.eclipse.swt.widgets.Display;
  38 import org.eclipse.swt.widgets.Text;
  39
  40 /**
  41  * <b><u>Histogram</u></b>
  42  * <p>
  43  * Re-usable histogram widget with the following features:
  44  * <ul>
  45  * <li>Y-axis labels displaying min/max count values
  46  * <li>X-axis labels displaying time range
  47  * <li>a histogram displaying the distribution of values over time (note that
  48  * the histogram might not necessarily fill the whole canvas)
  49  * </ul>
  50  * The widget also has 2 'markers' to identify:
  51  * <ul>
  52  * <li>a red dashed line over the bar that contains the currently selected event
  53  * <li>a dark red dashed line that delimits the right end of the histogram (if
  54  * it doesn't fill the canvas)
  55  * </ul>
  56  * Clicking on the histogram will select the current event at the mouse
  57  * location.
  58  * <p>
  59  * Once the histogram is selected, there is some limited keyboard support:
  60  * <ul>
  61  * <li>Home: go to the first histogram bar
  62  * <li>End: go to the last histogram bar
  63  * <li>Left: go to the previous histogram
  64  * <li>Right: go to the next histogram bar
  65  * </ul>
  66  * Finally, when the mouse hovers over the histogram, a tool tip showing the
  67  * following information about the corresponding histogram bar time range:
  68  * <ul>
  69  * <li>start of the time range
  70  * <li>end of the time range
  71  * <li>number of events in that time range
  72  * </ul>
  73  */
  74 public abstract class Histogram implements ControlListener, PaintListener, KeyListener, MouseListener, MouseTrackListener, IHistogramModelListener {
  75
  76     // ------------------------------------------------------------------------
  77     // Constants
  78     // ------------------------------------------------------------------------
  79
  80     // Histogram colors
  81     private final Color fBackgroundColor = Display.getCurrent().getSystemColor(SWT.COLOR_WHITE);
  82     private final Color fCurrentEventColor = Display.getCurrent().getSystemColor(SWT.COLOR_RED);
  83     private final Color fLastEventColor = Display.getCurrent().getSystemColor(SWT.COLOR_DARK_RED);
  84     private final Color fHistoBarColor = new Color(Display.getDefault(), 74, 112, 139);
  85
  86     // Timestamp scale (nanosecond)
  87     public static final byte TIME_SCALE = -9;
  88
  89     public static final int HISTOGRAM_BAR_WIDTH = 1;
  90
  91     // ------------------------------------------------------------------------
  92     // Attributes
  93     // ------------------------------------------------------------------------
  94
  95     // Owner view
  96     protected TmfView fParentView;
  97
  98     // Histogram text fields
  99     private Text fMaxNbEventsText;
 100     private Text fMinNbEventsText;
 101     private Text fTimeRangeStartText;
 102     private Text fTimeRangeEndText;
 103
 104     // Histogram drawing area
 105     protected Canvas fCanvas;
 106
 107     // Data model
 108     protected final HistogramDataModel fDataModel;
 109     protected HistogramScaledData fScaledData;
 110
 111     protected long fCurrentEventTime = 0;
 112
 113     // ------------------------------------------------------------------------
 114     // Construction
 115     // ------------------------------------------------------------------------
 116
 117     public Histogram(final TmfView view, final Composite parent) {
 118         fParentView = view;
 119
 120         createWidget(parent);
 121         fDataModel = new HistogramDataModel();
 122         fDataModel.addHistogramListener(this);
 123         clear();
 124
 125         fCanvas.addControlListener(this);
 126         fCanvas.addPaintListener(this);
 127         fCanvas.addKeyListener(this);
 128         fCanvas.addMouseListener(this);
 129         fCanvas.addMouseTrackListener(this);
 130     }
 131
 132     public void dispose() {
 133         fHistoBarColor.dispose();
 134         fDataModel.removeHistogramListener(this);
 135     }
 136
 137     private void createWidget(final Composite parent) {
 138
 139         final Color labelColor = parent.getBackground();
 140         final Font fFont = adjustFont(parent);
 141
 142         final int initalWidth = 10;
 143
 144         // --------------------------------------------------------------------
 145         // Define the histogram
 146         // --------------------------------------------------------------------
 147
 148         final GridLayout gridLayout = new GridLayout();
 149         gridLayout.numColumns = 3;
 150         gridLayout.marginHeight = 0;
 151         gridLayout.marginWidth = 0;
 152         gridLayout.marginTop = 0;
 153         gridLayout.horizontalSpacing = 0;
 154         gridLayout.verticalSpacing = 0;
 155         gridLayout.marginLeft = 0;
 156         gridLayout.marginRight = 0;
 157         final Composite composite = new Composite(parent, SWT.FILL);
 158         composite.setLayout(gridLayout);
 159
 160         // Use all the horizontal space
 161         GridData gridData = new GridData();
 162         gridData.horizontalAlignment = SWT.FILL;
 163         gridData.verticalAlignment = SWT.FILL;
 164         gridData.grabExcessHorizontalSpace = true;
 165         composite.setLayoutData(gridData);
 166
 167         // Y-axis max event
 168         gridData = new GridData();
 169         gridData.horizontalAlignment = SWT.RIGHT;
 170         gridData.verticalAlignment = SWT.TOP;
 171         fMaxNbEventsText = new Text(composite, SWT.READ_ONLY | SWT.RIGHT);
 172         fMaxNbEventsText.setFont(fFont);
 173         fMaxNbEventsText.setBackground(labelColor);
 174         fMaxNbEventsText.setEditable(false);
 175         fMaxNbEventsText.setText("0"); //$NON-NLS-1$
 176         fMaxNbEventsText.setLayoutData(gridData);
 177
 178         // Histogram itself
 179         gridData = new GridData();
 180         gridData.horizontalSpan = 2;
 181         gridData.verticalSpan = 2;
 182         gridData.horizontalAlignment = SWT.FILL;
 183         gridData.verticalAlignment = SWT.FILL;
 184         gridData.grabExcessHorizontalSpace = true;
 185         fCanvas = new Canvas(composite, SWT.BORDER | SWT.DOUBLE_BUFFERED);
 186         fCanvas.setLayoutData(gridData);
 187
 188         // Y-axis min event (always 0...)
 189         gridData = new GridData();
 190         gridData.horizontalAlignment = SWT.RIGHT;
 191         gridData.verticalAlignment = SWT.BOTTOM;
 192         fMinNbEventsText = new Text(composite, SWT.READ_ONLY | SWT.RIGHT);
 193         fMinNbEventsText.setFont(fFont);
 194         fMinNbEventsText.setBackground(labelColor);
 195         fMinNbEventsText.setEditable(false);
 196         fMinNbEventsText.setText("0"); //$NON-NLS-1$
 197         fMinNbEventsText.setLayoutData(gridData);
 198
 199         // Dummy cell
 200         gridData = new GridData(initalWidth, SWT.DEFAULT);
 201         gridData.horizontalAlignment = SWT.RIGHT;
 202         gridData.verticalAlignment = SWT.BOTTOM;
 203         final Text dummyText = new Text(composite, SWT.READ_ONLY);
 204         dummyText.setFont(fFont);
 205         dummyText.setBackground(labelColor);
 206         dummyText.setEditable(false);
 207         dummyText.setText(""); //$NON-NLS-1$
 208         dummyText.setLayoutData(gridData);
 209
 210         // Window range start time
 211         gridData = new GridData();
 212         gridData.horizontalAlignment = SWT.LEFT;
 213         gridData.verticalAlignment = SWT.BOTTOM;
 214         fTimeRangeStartText = new Text(composite, SWT.READ_ONLY);
 215         fTimeRangeStartText.setFont(fFont);
 216         fTimeRangeStartText.setBackground(labelColor);
 217         fTimeRangeStartText.setText(HistogramUtils.nanosecondsToString(0));
 218         fTimeRangeStartText.setLayoutData(gridData);
 219
 220         // Window range end time
 221         gridData = new GridData();
 222         gridData.horizontalAlignment = SWT.RIGHT;
 223         gridData.verticalAlignment = SWT.BOTTOM;
 224         fTimeRangeEndText = new Text(composite, SWT.READ_ONLY);
 225         fTimeRangeEndText.setFont(fFont);
 226         fTimeRangeEndText.setBackground(labelColor);
 227         fTimeRangeEndText.setText(HistogramUtils.nanosecondsToString(0));
 228         fTimeRangeEndText.setLayoutData(gridData);
 229     }
 230
 231     private Font adjustFont(final Composite composite) {
 232         // Reduce font size for a more pleasing rendering
 233         final int fontSizeAdjustment = -2;
 234         final Font font = composite.getFont();
 235         final FontData fontData = font.getFontData()[0];
 236         return new Font(font.getDevice(), fontData.getName(), fontData.getHeight() + fontSizeAdjustment, fontData.getStyle());
 237     }
 238
 239     // ------------------------------------------------------------------------
 240     // Accessors
 241     // ------------------------------------------------------------------------
 242
 243     public long getStartTime() {
 244         return fDataModel.getFirstBucketTime();
 245     }
 246
 247     public long getEndTime() {
 248         return fDataModel.getEndTime();
 249     }
 250
 251     public long getTimeLimit() {
 252         return fDataModel.getTimeLimit();
 253     }
 254
 255     public HistogramDataModel getDataModel() {
 256         return fDataModel;
 257     }
 258
 259     // ------------------------------------------------------------------------
 260     // Operations
 261     // ------------------------------------------------------------------------
 262     public abstract void updateTimeRange(long startTime, long endTime);
 263
 264     /**
 265      * Clear the histogram and reset the data
 266      */
 267     public void clear() {
 268         fDataModel.clear();
 269         fScaledData = null;
 270     }
 271
 272     /**
 273      * Increase the histogram bucket corresponding to [timestamp]
 274      *
 275      * @param timestamp
 276      */
 277     public void countEvent(final long eventCount, final long timestamp) {
 278         fDataModel.countEvent(eventCount, timestamp);
 279     }
 280
 281     /**
 282      * Sets the current event time and refresh the display
 283      *
 284      * @param timestamp
 285      */
 286     public void setCurrentEvent(final long timestamp) {
 287         fCurrentEventTime = (timestamp > 0) ? timestamp : 0;
 288         fDataModel.setCurrentEventNotifyListeners(timestamp);
 289     }
 290
 291     /**
 292      * Computes the timestamp of the bucket at [offset]
 293      *
 294      * @param offset offset from the left on the histogram
 295      * @return the start timestamp of the corresponding bucket
 296      */
 297     public synchronized long getTimestamp(final int offset) {
 298         assert offset > 0 && offset < fScaledData.fWidth;
 299         try {
 300             return fDataModel.getFirstBucketTime() + fScaledData.fBucketDuration * offset;
 301         } catch (final Exception e) {
 302             return 0; // TODO: Fix that racing condition (NPE)
 303         }
 304     }
 305
 306     /**
 307      * Computes the offset of the timestamp in the histogram
 308      *
 309      * @param timestamp the timestamp
 310      * @return the offset of the corresponding bucket (-1 if invalid)
 311      */
 312     public synchronized int getOffset(final long timestamp) {
 313         if (timestamp < fDataModel.getFirstBucketTime() || timestamp > fDataModel.getEndTime())
 314             return -1;
 315         return (int) ((timestamp - fDataModel.getFirstBucketTime()) / fScaledData.fBucketDuration);
 316     }
 317
 318     /**
 319      * Move the currently selected bar cursor to a non-empty bucket.
 320      *
 321      * @param keyCode the SWT key code
 322      */
 323     protected void moveCursor(final int keyCode) {
 324
 325         if (fScaledData.fCurrentBucket == HistogramScaledData.OUT_OF_RANGE_BUCKET)
 326             return;
 327
 328         int index;
 329         switch (keyCode) {
 330
 331             case SWT.HOME:
 332                 index = 0;
 333                 while (index < fScaledData.fLastBucket && fScaledData.fData[index] == 0)
 334                     index++;
 335                 if (index < fScaledData.fLastBucket)
 336                     fScaledData.fCurrentBucket = index;
 337                 break;
 338
 339             case SWT.ARROW_RIGHT:
 340                 index = fScaledData.fCurrentBucket + 1;
 341                 while (index < fScaledData.fWidth && fScaledData.fData[index] == 0)
 342                     index++;
 343                 if (index < fScaledData.fLastBucket)
 344                     fScaledData.fCurrentBucket = index;
 345                 break;
 346
 347             case SWT.END:
 348                 index = fScaledData.fLastBucket;
 349                 while (index >= 0 && fScaledData.fData[index] == 0)
 350                     index--;
 351                 if (index >= 0)
 352                     fScaledData.fCurrentBucket = index;
 353                 break;
 354
 355             case SWT.ARROW_LEFT:
 356                 index = fScaledData.fCurrentBucket - 1;
 357                 while (index >= 0 && fScaledData.fData[index] == 0)
 358                     index--;
 359                 if (index >= 0)
 360                     fScaledData.fCurrentBucket = index;
 361                 break;
 362
 363             default:
 364                 return;
 365         }
 366
 367         updateCurrentEventTime();
 368     }
 369
 370     /**
 371      * Refresh the histogram display
 372      */
 373     @Override
 374     public void modelUpdated() {
 375         if (!fCanvas.isDisposed() && fCanvas.getDisplay() != null)
 376             fCanvas.getDisplay().asyncExec(new Runnable() {
 377                 @Override
 378                 public void run() {
 379                     if (!fCanvas.isDisposed()) {
 380                         // Retrieve and normalize the data
 381                         final int canvasWidth = fCanvas.getBounds().width;
 382                         final int canvasHeight = fCanvas.getBounds().height;
 383                         if (canvasWidth <= 0 || canvasHeight <= 0)
 384                             return;
 385                         fDataModel.setCurrentEvent(fCurrentEventTime);
 386                         fScaledData = fDataModel.scaleTo(canvasWidth, canvasHeight, HISTOGRAM_BAR_WIDTH);
 387                         synchronized(fScaledData) {
 388                             if (fScaledData != null) {
 389                                 fCanvas.redraw();
 390                                 // Display histogram and update X-,Y-axis labels
 391                                 fTimeRangeStartText.setText(HistogramUtils.nanosecondsToString(fDataModel.getFirstBucketTime()));
 392                                 fTimeRangeEndText.setText(HistogramUtils.nanosecondsToString(fDataModel.getEndTime()));
 393                                 fMaxNbEventsText.setText(Long.toString(fScaledData.fMaxValue));
 394                                 // The Y-axis area might need to be re-sized
 395                                 fMaxNbEventsText.getParent().layout();
 396                             }
 397                         }
 398                     }
 399                 }
 400             });
 401     }
 402
 403     // ------------------------------------------------------------------------
 404     // Helper functions
 405     // ------------------------------------------------------------------------
 406
 407     private void updateCurrentEventTime() {
 408         final long bucketStartTime = getTimestamp(fScaledData.fCurrentBucket);
 409         ((HistogramView) fParentView).updateCurrentEventTime(bucketStartTime);
 410     }
 411
 412     // ------------------------------------------------------------------------
 413     // PaintListener
 414     // ------------------------------------------------------------------------
 415
 416     protected final String IMAGE_KEY = "double-buffer-image"; //$NON-NLS-1$
 417
 418     @Override
 419     public void paintControl(final PaintEvent event) {
 420
 421         // Get the geometry
 422         final int canvasWidth = fCanvas.getBounds().width;
 423         final int canvasHeight = fCanvas.getBounds().height;
 424
 425         // Make sure we have something to draw upon
 426         if (canvasWidth <= 0 || canvasHeight <= 0)
 427             return;
 428
 429         // Retrieve image; re-create only if necessary
 430         Image image = (Image) fCanvas.getData(IMAGE_KEY);
 431         if (image == null || image.getBounds().width != canvasWidth || image.getBounds().height != canvasHeight) {
 432             image = new Image(event.display, canvasWidth, canvasHeight);
 433             fCanvas.setData(IMAGE_KEY, image);
 434         }
 435
 436         // Draw the histogram on its canvas
 437         final GC imageGC = new GC(image);
 438         formatImage(imageGC, image);
 439         event.gc.drawImage(image, 0, 0);
 440         imageGC.dispose();
 441     }
 442
 443     private void formatImage(final GC imageGC, final Image image) {
 444
 445         if (fScaledData == null)
 446             return;
 447
 448         final HistogramScaledData scaledData = new HistogramScaledData(fScaledData);
 449
 450         try {
 451             // Get drawing boundaries
 452             final int width = image.getBounds().width;
 453             final int height = image.getBounds().height;
 454
 455             // Clear the drawing area
 456             imageGC.setBackground(fBackgroundColor);
 457             imageGC.fillRectangle(0, 0, image.getBounds().width + 1, image.getBounds().height + 1);
 458
 459             // Draw the histogram bars
 460             imageGC.setBackground(fHistoBarColor);
 461             final int limit = width < scaledData.fWidth ? width : scaledData.fWidth;
 462             for (int i = 1; i < limit; i++) {
 463                 final int value = (int) (scaledData.fData[i] * scaledData.fScalingFactor);
 464                 imageGC.fillRectangle(i, height - value, 1, value);
 465             }
 466
 467             // Draw the current event bar
 468             final int currentBucket = scaledData.fCurrentBucket;
 469             if (currentBucket >= 0 && currentBucket < limit)
 470                 drawDelimiter(imageGC, fCurrentEventColor, height, currentBucket);
 471
 472             // Add a dashed line as a delimiter (at the right of the last bar)
 473             int lastEventIndex = limit - 1;
 474             while (lastEventIndex >= 0 && scaledData.fData[lastEventIndex] == 0)
 475                 lastEventIndex--;
 476             lastEventIndex += (lastEventIndex < limit - 1) ? 1 : 0;
 477             drawDelimiter(imageGC, fLastEventColor, height, lastEventIndex);
 478         } catch (final Exception e) {
 479             // Do nothing
 480         }
 481     }
 482
 483     private void drawDelimiter(final GC imageGC, final Color color, final int height, final int index) {
 484         imageGC.setBackground(color);
 485         final int dash = height / 4;
 486         imageGC.fillRectangle(index, 0 * dash, 1, dash - 1);
 487         imageGC.fillRectangle(index, 1 * dash, 1, dash - 1);
 488         imageGC.fillRectangle(index, 2 * dash, 1, dash - 1);
 489         imageGC.fillRectangle(index, 3 * dash, 1, height - 3 * dash);
 490     }
 491
 492     // ------------------------------------------------------------------------
 493     // KeyListener
 494     // ------------------------------------------------------------------------
 495
 496     @Override
 497     public void keyPressed(final KeyEvent event) {
 498         moveCursor(event.keyCode);
 499     }
 500
 501     @Override
 502     public void keyReleased(final KeyEvent event) {
 503     }
 504
 505     // ------------------------------------------------------------------------
 506     // MouseListener
 507     // ------------------------------------------------------------------------
 508
 509     @Override
 510     public void mouseDoubleClick(final MouseEvent event) {
 511     }
 512
 513     @Override
 514     public void mouseDown(final MouseEvent event) {
 515         if (fDataModel.getNbEvents() > 0 && fScaledData.fLastBucket >= event.x) {
 516             fScaledData.fCurrentBucket = event.x;
 517             updateCurrentEventTime();
 518         }
 519     }
 520
 521     @Override
 522     public void mouseUp(final MouseEvent event) {
 523     }
 524
 525     // ------------------------------------------------------------------------
 526     // MouseTrackListener
 527     // ------------------------------------------------------------------------
 528
 529     @Override
 530     public void mouseEnter(final MouseEvent event) {
 531     }
 532
 533     @Override
 534     public void mouseExit(final MouseEvent event) {
 535     }
 536
 537     @Override
 538     public void mouseHover(final MouseEvent event) {
 539         if (fDataModel.getNbEvents() > 0 && fScaledData != null && fScaledData.fLastBucket >= event.x) {
 540             final String tooltip = formatToolTipLabel(event.x);
 541             fCanvas.setToolTipText(tooltip);
 542         }
 543     }
 544
 545     private String formatToolTipLabel(final int index) {
 546         long startTime = fScaledData.getBucketStartTime(fScaledData.fCurrentBucket);
 547         // negative values are possible if time values came into the model in decreasing order
 548         if (startTime < 0)
 549             startTime = 0;
 550         final long endTime = fScaledData.getBucketEndTime(fScaledData.fCurrentBucket);
 551         final int nbEvents = (index >= 0) ? fScaledData.fData[index] : 0;
 552
 553         final StringBuffer buffer = new StringBuffer();
 554         buffer.append("Range = ["); //$NON-NLS-1$
 555         buffer.append(HistogramUtils.nanosecondsToString(startTime));
 556         buffer.append(","); //$NON-NLS-1$
 557         buffer.append(HistogramUtils.nanosecondsToString(endTime));
 558         buffer.append(")\n"); //$NON-NLS-1$
 559         buffer.append("Event count = "); //$NON-NLS-1$
 560         buffer.append(nbEvents);
 561         return buffer.toString();
 562     }
 563
 564     // ------------------------------------------------------------------------
 565     // ControlListener
 566     // ------------------------------------------------------------------------
 567
 568     @Override
 569     public void controlMoved(final ControlEvent event) {
 570         fDataModel.complete();
 571     }
 572
 573     @Override
 574     public void controlResized(final ControlEvent event) {
 575         fDataModel.complete();
 576     }
 577 }