From: Matthew Khouzam Date: Tue, 12 Jun 2012 18:02:24 +0000 (-0400) Subject: Improve Javadoc for TmfEventsViews X-Git-Url: http://drtracing.org/?a=commitdiff_plain;h=02023181c10b75a56cd3c034f763fe25c5db3da5;p=deliverable%2Ftracecompass.git Improve Javadoc for TmfEventsViews --- diff --git a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/views/events/TmfEventsView.java b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/views/events/TmfEventsView.java index 5e0c4abb4f..d61a450d85 100644 --- a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/views/events/TmfEventsView.java +++ b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/views/events/TmfEventsView.java @@ -1,11 +1,11 @@ /******************************************************************************* * Copyright (c) 2009, 2010 Ericsson - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Francois Chouinard - Initial API and implementation * Patrick Tasse - Factored out events table @@ -65,6 +65,9 @@ import org.osgi.framework.Bundle; */ public class TmfEventsView extends TmfView implements IResourceChangeListener { + /** + * ID for serializing purposes. + */ public static final String ID = "org.eclipse.linuxtools.tmf.ui.views.events"; //$NON-NLS-1$ private TmfExperiment fExperiment; @@ -72,15 +75,22 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { private static final int DEFAULT_CACHE_SIZE = 100; private String fTitlePrefix; private Composite fParent; - + // ------------------------------------------------------------------------ // Constructor // ------------------------------------------------------------------------ + /** + * Create an events view with a cache size + * @param cacheSize not used + */ public TmfEventsView(int cacheSize) { super("TmfEventsView"); //$NON-NLS-1$ } + /** + * Default contructor + */ public TmfEventsView() { this(DEFAULT_CACHE_SIZE); } @@ -95,7 +105,7 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { fParent = parent; fTitlePrefix = getTitle(); - + // If an experiment is already selected, update the table TmfExperiment experiment = (TmfExperiment) TmfExperiment.getCurrentExperiment(); if (experiment != null) { @@ -133,7 +143,7 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { return new TmfEventsTable(parent, cacheSize); } String traceType = resource.getPersistentProperty(TmfCommonConstants.TRACETYPE); - if (commonTraceType != null && !commonTraceType.equals(traceType)) { + if ((commonTraceType != null) && !commonTraceType.equals(traceType)) { return new TmfEventsTable(parent, cacheSize); } commonTraceType = traceType; @@ -154,7 +164,7 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { break; } String eventsTableType = eventsTableTypeCE[0].getAttribute(TmfTraceType.CLASS_ATTR); - if (eventsTableType == null || eventsTableType.length() == 0) { + if ((eventsTableType == null) || (eventsTableType.length() == 0)) { break; } Bundle bundle = Platform.getBundle(ce.getContributor().getName()); @@ -219,7 +229,11 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { // ------------------------------------------------------------------------ // Signal handlers // ------------------------------------------------------------------------ - + + /** + * ExperimentSelected, a callback called when the TmfSignal "TmfExperimentSelectedSignal" is sent. + * @param signal the signal that triggered the callback + */ @SuppressWarnings("unchecked") @TmfSignalHandler public void experimentSelected(TmfExperimentSelectedSignal signal) { @@ -241,6 +255,10 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { } } + /** + * Experiment disposed, a callback called when the TmfSignal "TmfExperimentDisposedSignal" is sent. + * @param signal the signal that triggered the callback + */ @SuppressWarnings("unchecked") @TmfSignalHandler public void experimentDisposed(TmfExperimentDisposedSignal signal) { @@ -265,12 +283,12 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { @Override public void resourceChanged(final IResourceChangeEvent event) { - if (fExperiment == null || fExperiment.getBookmarksFile() == null) { + if ((fExperiment == null) || (fExperiment.getBookmarksFile() == null)) { return; } - for (final IMarkerDelta delta : event.findMarkerDeltas(IMarker.BOOKMARK, false)) - if (delta.getResource().equals(fExperiment.getBookmarksFile())) + for (final IMarkerDelta delta : event.findMarkerDeltas(IMarker.BOOKMARK, false)) { + if (delta.getResource().equals(fExperiment.getBookmarksFile())) { if (delta.getKind() == IResourceDelta.REMOVED) { final IMarker bookmark = delta.getMarker(); Display.getDefault().asyncExec(new Runnable() { @@ -279,12 +297,15 @@ public class TmfEventsView extends TmfView implements IResourceChangeListener { fEventsTable.removeBookmark(bookmark); } }); - } else if (delta.getKind() == IResourceDelta.CHANGED) + } else if (delta.getKind() == IResourceDelta.CHANGED) { Display.getDefault().asyncExec(new Runnable() { @Override public void run() { fEventsTable.getTable().refresh(); } }); + } + } + } } } diff --git a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/ColumnData.java b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/ColumnData.java index b7272a6014..67278e658d 100644 --- a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/ColumnData.java +++ b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/ColumnData.java @@ -1,22 +1,42 @@ /******************************************************************************* * Copyright (c) 2010 Ericsson - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Matthew Khouzam - Extracted from TmfEventsView ******************************************************************************/ package org.eclipse.linuxtools.tmf.ui.widgets.virtualtable; - +/** + * ColumnData + * @author Matthew Khouzam + * @version 1.0 + * + */ public class ColumnData { + /** + * The title of the column + */ public final String header; + /** + * the width of the column in pixels + */ public final int width; + /** + * the alignment of the column + */ public final int alignment; + /** + * Constructor + * @param h header (title) + * @param w width + * @param a alignment + */ public ColumnData(String h, int w, int a) { header = h; width = w; diff --git a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/IDoubleClickListener.java b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/IDoubleClickListener.java index 7ed4717963..4df6479785 100644 --- a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/IDoubleClickListener.java +++ b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/IDoubleClickListener.java @@ -1,21 +1,30 @@ /******************************************************************************* * Copyright (c) 2011 Kalray. - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Xavier Raynaud - Initial API and implementation ******************************************************************************/ package org.eclipse.linuxtools.tmf.ui.widgets.virtualtable; import org.eclipse.swt.widgets.TableItem; - +/** + * Double click listener interface + * @author Xavier Raynaud + * @version 1.0 + */ public interface IDoubleClickListener { - + /** + * Handle a double click event + * @param table the table that was double clicked + * @param item the item that was double clicked in the table + * @param column the column that was double clicked in the item in the table. + */ public void handleDoubleClick(TmfVirtualTable table, TableItem item, int column); - + } diff --git a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TmfVirtualTable.java b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TmfVirtualTable.java index 514d82e523..f7365ef2ef 100644 --- a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TmfVirtualTable.java +++ b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TmfVirtualTable.java @@ -61,26 +61,64 @@ import org.eclipse.ui.PlatformUI; * * Styles: * H_SCROLL, V_SCROLL, SINGLE, CHECK, FULL_SELECTION, HIDE_SELECTION, NO_SCROLL + * @author Matthew Khouzam, Francois Chouinard, Patrick Tasse, Xavier Raynaud + * @version $Revision: 1.0 */ public class TmfVirtualTable extends Composite { // The table + /** + * Field fTable. + */ private Table fTable; + /** + * Field fTableRows. + */ private int fTableRows = 0; // Number of table rows + /** + * Field fFullyVisibleRows. + */ private int fFullyVisibleRows = 0; // Number of fully visible table rows + /** + * Field fFrozenRowCount. + */ private int fFrozenRowCount = 0; // Number of frozen table rows at top of table + /** + * Field fTableTopEventRank. + */ private int fTableTopEventRank = 0; // Global rank of the first entry displayed + /** + * Field fSelectedEventRank. + */ private int fSelectedEventRank = 0; // Global rank of the selected event + /** + * Field fPendingSelection. + */ private boolean fPendingSelection = false; // Pending selection update + /** + * Field fTableItemCount. + */ private int fTableItemCount = 0; // The slider + /** + * Field fSlider. + */ private Slider fSlider; + /** + * Field fLinuxItemHeight. + */ private int fLinuxItemHeight = 0; // Calculated item height for Linux workaround + /** + * Field tooltipProvider. + */ private TooltipProvider tooltipProvider = null; + /** + * Field doubleClickListener. + */ private IDoubleClickListener doubleClickListener = null; // ------------------------------------------------------------------------ @@ -265,6 +303,7 @@ public class TmfVirtualTable extends Composite { /** * Create the table and add listeners + * @param style int can be H_SCROLL, V_SCROLL, SINGLE, CHECK, FULL_SELECTION, HIDE_SELECTION, NO_SCROLL */ private void createTable(int style) { fTable = new Table(this, style | SWT.NO_SCROLL); @@ -484,6 +523,12 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method setDataItem. + * @param index int + * @param item TableItem + * @return boolean + */ private boolean setDataItem(int index, TableItem item) { if (index != -1) { Event event = new Event(); @@ -504,6 +549,10 @@ public class TmfVirtualTable extends Composite { // Slider handling // ------------------------------------------------------------------------ + /** + * Method createSlider. + * @param style int + */ private void createSlider(int style) { fSlider = new Slider(this, SWT.VERTICAL | SWT.NO_FOCUS); fSlider.setMinimum(0); @@ -536,47 +585,88 @@ public class TmfVirtualTable extends Composite { // Simulated Table API // ------------------------------------------------------------------------ + /** + * Method setHeaderVisible. + * @param b boolean + */ public void setHeaderVisible(boolean b) { fTable.setHeaderVisible(b); } + /** + * Method setLinesVisible. + * @param b boolean + */ public void setLinesVisible(boolean b) { fTable.setLinesVisible(b); } + /** + * Method getSelection. + * @return TableItem[] the items that are selected. + */ public TableItem[] getSelection() { return fTable.getSelection(); } + /** + * Method addListener. + * @param eventType int + * @param listener Listener + */ @Override public void addListener(int eventType, Listener listener) { fTable.addListener(eventType, listener); } + /** + * Method addKeyListener. + * @param listener KeyListener + */ @Override public void addKeyListener(KeyListener listener) { fTable.addKeyListener(listener); } + /** + * Method addMouseListener. + * @param listener MouseListener + */ @Override public void addMouseListener(MouseListener listener) { fTable.addMouseListener(listener); } + /** + * Method addSelectionListener. + * @param listener SelectionListener + */ public void addSelectionListener(SelectionListener listener) { fTable.addSelectionListener(listener); } + /** + * Method setMenu sets the menu + * @param menu Menu the menu + */ @Override public void setMenu(Menu menu) { fTable.setMenu(menu); } + /** + * Method clearAll empties a table. + */ public void clearAll() { setItemCount(0); } + /** + * Method setItemCount + * @param nbItems int the number of items in the table + * + */ public void setItemCount(int nbItems) { nbItems = Math.max(0, nbItems); @@ -593,10 +683,18 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method getItemCount. + * @return int the number of items in the table + */ public int getItemCount() { return fTableItemCount; } + /** + * Method getItemHeight. + * @return int the height of a table item in pixels. (may vary from one os to another) + */ public int getItemHeight() { /* * Bug in Linux. The method getItemHeight doesn't always return the correct value. @@ -618,14 +716,26 @@ public class TmfVirtualTable extends Composite { return fTable.getItemHeight(); } + /** + * Method getHeaderHeight. + * @return int get the height of the header in pixels. + */ public int getHeaderHeight() { return fTable.getHeaderHeight(); } + /** + * Method getTopIndex. + * @return int get the first data item index, if you have a header it is offset. + */ public int getTopIndex() { return fTableTopEventRank + fFrozenRowCount; } + /** + * Method setTopIndex. + * @param i int suggested top index for the table. + */ public void setTopIndex(int i) { if (fTableItemCount > 0) { i = Math.min(i, fTableItemCount - 1); @@ -640,6 +750,11 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method indexOf. Return the index of a table item + * @param ti TableItem the table item to search for in the table + * @return int the index of the first match. (there should only be one match) + */ public int indexOf(TableItem ti) { int index = fTable.indexOf(ti); if (index < fFrozenRowCount) { @@ -649,14 +764,26 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method getColumns. + * @return TableColumn[] the table columns + */ public TableColumn[] getColumns() { return fTable.getColumns(); } + /** + * Method getItem. + * @param point Point the coordinates in the table + * @return TableItem the corresponding table item + */ public TableItem getItem(Point point) { return fTable.getItem(point); } + /** + * Method resize. + */ private void resize() { // Compute the numbers of rows that fit the new area int tableHeight = Math.max(0, getSize().y - fTable.getHeaderHeight()); @@ -678,6 +805,10 @@ public class TmfVirtualTable extends Composite { // Controls interactions // ------------------------------------------------------------------------ + /** + * Method setFocus. + * @return boolean is this visible? + */ @Override public boolean setFocus() { boolean isVisible = isVisible(); @@ -687,6 +818,9 @@ public class TmfVirtualTable extends Composite { return isVisible; } + /** + * Method refresh. + */ public void refresh() { boolean done = refreshTable(); if (fPendingSelection && done) { @@ -699,6 +833,10 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method setColumnHeaders. + * @param columnData ColumnData[] the columndata array. + */ public void setColumnHeaders(ColumnData columnData[]) { for (int i = 0; i < columnData.length; i++) { TableColumn column = new TableColumn(fTable, columnData[i].alignment, i); @@ -711,6 +849,10 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method removeAll. + * @return int 0 the number of elements in the table + */ public int removeAll() { setItemCount(0); fSlider.setMaximum(0); @@ -719,6 +861,10 @@ public class TmfVirtualTable extends Composite { return 0; } + /** + * Method refreshTable. + * @return boolean did all the items regresh properly? + */ private boolean refreshTable() { boolean done = true; for (int i = 0; i < fTableRows; i++) { @@ -751,6 +897,10 @@ public class TmfVirtualTable extends Composite { return done; } + /** + * Method setSelection. + * @param i int the item number to select in the table. + */ public void setSelection(int i) { if (fTableItemCount > 0) { i = Math.min(i, fTableItemCount - 1); @@ -770,6 +920,10 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method getSelectionIndex. + * @return int the table index of the selected event. not necessarrily the index of the event due to filtering. + */ public int getSelectionIndex() { int index = fTable.getSelectionIndex(); if (index == -1) { @@ -782,15 +936,28 @@ public class TmfVirtualTable extends Composite { } } + /** + * Method setFrozenRowCount. + * @param count int the number of rows to freeze from the top row + */ public void setFrozenRowCount(int count) { fFrozenRowCount = count; refreshTable(); } + /** + * Method createTableEditor. + * @return a TableEditor of the table + */ public TableEditor createTableEditor() { return new TableEditor(fTable); } + /** + * Method createTableEditorControl. + * @param control Class + * @return Control + */ public Control createTableEditorControl(Class control) { try { return control.getConstructor(Composite.class, int.class).newInstance(new Object[] {fTable, SWT.NONE}); @@ -802,7 +969,7 @@ public class TmfVirtualTable extends Composite { /** * @return the tooltipProvider - */ + */ public TooltipProvider getTooltipProvider() { return tooltipProvider; } @@ -816,7 +983,7 @@ public class TmfVirtualTable extends Composite { /** * @return the doubleClickListener - */ + */ public IDoubleClickListener getDoubleClickListener() { return doubleClickListener; } diff --git a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TooltipProvider.java b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TooltipProvider.java index 39734c8f24..90ab760d12 100644 --- a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TooltipProvider.java +++ b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/widgets/virtualtable/TooltipProvider.java @@ -1,19 +1,29 @@ /******************************************************************************* * Copyright (c) 2011 Kalray. - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Xavier Raynaud - Initial API and implementation ******************************************************************************/ package org.eclipse.linuxtools.tmf.ui.widgets.virtualtable; +/** + * An interface to get tooltips. + * @author Xavier Raynaud + * @version 1.0 + */ public interface TooltipProvider { - + /** + * get a Tooltip for a given column in a table row. (a cell if you will) + * @param column the column + * @param data the object being selected. (quite often a "TableItem") + * @return the string of text to display in the tooltip. + */ public String getTooltip(int column, Object data); - + }