diff options
22 files changed, 1303 insertions, 90 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java index b1853fbce5..e93dc103ba 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java @@ -561,6 +561,23 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize return result; } +/** + * Sets the receiver's selection to the given item. + * The current selected is first cleared, then the new item is + * selected. + * + * @param item the item to select + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setSelection (TabItem item) { checkWidget (); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java index 3a12f4c821..13cd806465 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java @@ -90,11 +90,11 @@ public TabItem (TabFolder parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> - * <li>ERROR_INVALID_RANGE - if the index is either negative or greater than the parent's current tab count</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -257,14 +257,14 @@ public void setImage (Image image) { * the mnemonic character. * </p> * <p> - * Mnemonics are indicated by an '&' that causes the next + * Mnemonics are indicated by an '&' that causes the next * character to be the mnemonic. When the user presses a * key sequence that matches the mnemonic, a selection * event occurs. On most platforms, the mnemonic appears * underlined but may be emphasised in a platform specific - * manner. The mnemonic indicator character '&' can be + * manner. The mnemonic indicator character '&' can be * escaped by doubling it in the string, causing a single - *'&' to be displayed. + * '&' to be displayed. * </p> * * @param string the new text diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java index 5eb1599d36..0aca3a7a5d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java @@ -26,12 +26,32 @@ import org.eclipse.swt.graphics.*; /** * Instances of this class implement a selectable user interface - * object that displays a list of images and strings and issue + * object that displays a list of images and strings and issues * notification when selected. * <p> * The item children that may be added to instances of this class * must be of type <code>TableItem</code>. * </p><p> + * Style <code>VIRTUAL</code> is used to create a <code>Table</code> whose + * <code>TableItem</code>s are to be populated by the client on an on-demand basis + * instead of up-front. This can provide significant performance improvements for + * tables that are very large or for which <code>TableItem</code> population is + * expensive (for example, retrieving values from an external source). + * </p><p> + * Here is an example of using a <code>Table</code> with style <code>VIRTUAL</code>: + * <code><pre> + * final Table table = new Table (parent, SWT.VIRTUAL | SWT.BORDER); + * table.setItemCount (1000000); + * table.addListener (SWT.SetData, new Listener () { + * public void handleEvent (Event event) { + * TableItem item = (TableItem) event.item; + * int index = table.indexOf (item); + * item.setText ("Item " + index); + * System.out.println (item.getText ()); + * } + * }); + * </pre></code> + * </p><p> * Note that although this class is a subclass of <code>Composite</code>, * it does not make sense to add <code>Control</code> children to it, * or set a layout on it. @@ -40,9 +60,9 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION, HIDE_SELECTION, VIRTUAL</dd> * <dt><b>Events:</b></dt> - * <dd>Selection, DefaultSelection</dd> + * <dd>Selection, DefaultSelection, SetData, MeasureItem, EraseItem, PaintItem</dd> * </dl> - * <p> + * </p><p> * Note: Only one of the styles SINGLE, and MULTI may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -259,8 +279,8 @@ protected void checkSubclass () { /** * Clears the item at the given zero-relative index in the receiver. * The text, icon and other attributes of the item are set to the default - * value. If the table was created with the SWT.VIRTUAL style, these - * attributes are requested again as needed. + * value. If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param index the index of the item to clear * @@ -297,9 +317,9 @@ public void clear (int index) { /** * Removes the items from the receiver which are between the given * zero-relative start and end indices (inclusive). The text, icon - * and other attribues of the items are set to their default values. - * If the table was created with the SWT.VIRTUAL style, these attributes - * are requested again as needed. + * and other attributes of the items are set to their default values. + * If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param start the start index of the item to clear * @param end the end index of the item to clear @@ -334,9 +354,9 @@ public void clear (int start, int end) { /** * Clears the items at the given zero-relative indices in the receiver. - * The text, icon and other attribues of the items are set to their default - * values. If the table was created with the SWT.VIRTUAL style, these - * attributes are requested again as needed. + * The text, icon and other attributes of the items are set to their default + * values. If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param indices the array of indices of the items * @@ -370,9 +390,9 @@ public void clear (int [] indices) { /** * Clears all the items in the receiver. The text, icon and other - * attribues of the items are set to their default values. If the - * table was created with the SWT.VIRTUAL style, these attributes - * are requested again as needed. + * attributes of the items are set to their default values. If the + * table was created with the <code>SWT.VIRTUAL</code> style, these + * attributes are requested again as needed. * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1180,6 +1200,7 @@ public Rectangle getClientArea () { /** * Returns the column at the given, zero-relative index in the * receiver. Throws an exception if the index is out of range. + * Columns are returned in the order that they were created. * If no <code>TableColumn</code>s were created by the programmer, * this method will throw <code>ERROR_INVALID_RANGE</code> despite * the fact that a single column of data may be visible in the table. @@ -1196,6 +1217,12 @@ public Rectangle getClientArea () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see Table#getColumnOrder() + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move */ public TableColumn getColumn (int index) { checkWidget (); @@ -1265,7 +1292,8 @@ public int [] getColumnOrder () { /** * Returns an array of <code>TableColumn</code>s which are the - * columns in the receiver. If no <code>TableColumn</code>s were + * columns in the receiver. Columns are returned in the order + * that they were created. If no <code>TableColumn</code>s were * created by the programmer, the array is empty, despite the fact * that visually, one column of items may be visible. This occurs * when the programmer uses the table like a list, adding items but @@ -1282,6 +1310,12 @@ public int [] getColumnOrder () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see Table#getColumnOrder() + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move */ public TableColumn [] getColumns () { checkWidget (); @@ -1391,9 +1425,16 @@ public TableItem getItem (int index) { * Returns the item at the given point in the receiver * or null if no such item exists. The point is in the * coordinate system of the receiver. + * <p> + * The item that is returned represents an item that could be selected by the user. + * For example, if selection only occurs in items in the first column, then null is + * returned if the point is outside of the item. + * Note that the SWT.FULL_SELECTION style hint, which specifies the selection policy, + * determines the extent of the selection. + * </p> * * @param point the point used to locate the item - * @return the item at the given point + * @return the item at the given point, or null if the point is not in a selectable item * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the point is null</li> @@ -2325,7 +2366,7 @@ public void remove (int [] indices) { /** * Removes all of the items from the receiver. - * <p> + * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> @@ -2420,6 +2461,7 @@ public void select (int index) { * if start is greater than end. * If the receiver is single-select and there is more than one item in the * given range, then all indices are ignored. + * </p> * * @param start the start of the range * @param end the end of the range @@ -2457,6 +2499,7 @@ public void select (int start, int end) { * Indices that are out of range and duplicate indices are ignored. * If the receiver is single-select and multiple indices are specified, * then all indices are ignored. + * </p> * * @param indices the array of indices for the items to select * @@ -2517,6 +2560,7 @@ void select (int [] ids, int count, boolean clear) { * Selects all of the items in the receiver. * <p> * If the receiver is single-select, do nothing. + * </p> * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2875,6 +2919,7 @@ void setSelection (int index, boolean notify) { * if start is greater than end. * If the receiver is single-select and there is more than one item in the * given range, then all indices are ignored. + * </p> * * @param start the start index of the items to select * @param end the end index of the items to select @@ -2909,6 +2954,7 @@ public void setSelection (int start, int end) { * Indices that are out of range and duplicate indices are ignored. * If the receiver is single-select and multiple indices are specified, * then all indices are ignored. + * </p> * * @param indices the indices of the items to select * @@ -2944,6 +2990,26 @@ public void setSelection (int [] indices) { } } +/** + * Sets the receiver's selection to the given item. + * The current selection is cleared before the new item is selected. + * <p> + * If the item is not in the receiver, then it is ignored. + * </p> + * + * @param item the item to select + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setSelection (TableItem item) { checkWidget (); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -2957,6 +3023,7 @@ public void setSelection (TableItem item) { * Items that are not in the receiver are ignored. * If the receiver is single-select and multiple items are specified, * then all items are ignored. + * </p> * * @param items the array of items * @@ -2999,7 +3066,7 @@ public void setSelection (TableItem [] items) { * value will clear the sort indicator. The current sort column is cleared * before the new column is set. * - * @param column the column used by the sort indicator + * @param column the column used by the sort indicator or <code>null</code> * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the column is disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java index 5e75a1e1b6..f76a978386 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java @@ -20,13 +20,13 @@ import org.eclipse.swt.events.*; /** * Instances of this class represent a column in a table widget. - * <dl> + * <p><dl> * <dt><b>Styles:</b></dt> * <dd>LEFT, RIGHT, CENTER</dd> * <dt><b>Events:</b></dt> * <dd> Move, Resize, Selection</dd> * </dl> - * <p> + * </p><p> * Note: Only one of the styles LEFT, RIGHT and CENTER may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -94,10 +94,11 @@ public TableColumn (Table parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -272,6 +273,19 @@ public boolean getResizable () { return resizable; } +/** + * Returns the receiver's tool tip text, or null if it has + * not been set. + * + * @return the receiver's tool tip text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public String getToolTipText () { checkWidget (); return toolTipText; @@ -508,6 +522,19 @@ public void setText (String string) { updateHeader (); } +/** + * Sets the receiver's tool tip text to the argument, which + * may be null indicating that no tool tip text should be shown. + * + * @param string the new tool tip text (or null) + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setToolTipText (String string) { checkWidget(); toolTipText = string; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java index e13216e771..1e7280e26a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java @@ -92,10 +92,11 @@ public TableItem (Table parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -211,6 +212,19 @@ public Color getBackground (int index) { return cellBackground [index]; } +/** + * Returns a rectangle describing the receiver's size and location + * relative to its parent. + * + * @return the receiver's bounding rectangle + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public Rectangle getBounds () { checkWidget (); if (!parent.checkData (this, true)) error (SWT.ERROR_WIDGET_DISPOSED); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java index 8d915564ea..4a1bcb0480 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java @@ -17,6 +17,23 @@ import org.eclipse.swt.internal.carbon.HMHelpContentRec; import org.eclipse.swt.internal.carbon.OS; import org.eclipse.swt.events.*; +/** + * Instances of this class represent popup windows that are used + * to inform or warn the user. + * <p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>BALLOON, ICON_ERROR, ICON_INFORMATION, ICON_WARNING</dd> + * <dt><b>Events:</b></dt> + * <dd>Selection</dd> + * </dl> + * </p><p> + * IMPORTANT: This class is intended to be subclassed <em>only</em> + * within the SWT implementation. + * </p> + * + * @since 3.2 + */ public class ToolTip extends Widget { Shell parent, tip; int x, y; @@ -35,6 +52,36 @@ public class ToolTip extends Widget { static final int IMAGE_SIZE = 16; static final int DELAY = 10000; +/** + * Constructs a new instance of this class given its parent + * and a style value describing its behavior and appearance. + * <p> + * The style value is either one of the style constants defined in + * class <code>SWT</code> which is applicable to instances of this + * class, or must be built by <em>bitwise OR</em>'ing together + * (that is, using the <code>int</code> "|" operator) two or more + * of those <code>SWT</code> style constants. The class description + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control to construct + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> + * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> + * </ul> + * + * @see SWT#ICON_ERROR + * @see SWT#ICON_INFORMATION + * @see SWT#ICON_WARNING + * @see Widget#checkSubclass + * @see Widget#getStyle + */ public ToolTip (Shell parent, int style) { super (parent, checkStyle (style)); this.parent = parent; @@ -47,6 +94,26 @@ static int checkStyle (int style) { return checkBits (style, SWT.ICON_INFORMATION, SWT.ICON_WARNING, SWT.ICON_ERROR, 0, 0, 0); } +/** + * Adds the listener to the collection of listeners who will + * be notified when the receiver's value changes, by sending + * it one of the messages defined in the <code>SelectionListener</code> + * interface. + * + * @param listener the listener which should be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see SelectionListener + * @see #removeSelectionListener + * @see SelectionEvent + */ public void addSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -145,16 +212,49 @@ void disposeTip () { boldFont = null; } +/** + * Returns <code>true</code> if the receiver is automatically + * hidden by the platform, and <code>false</code> otherwise. + * + * @return the receiver's auto hide state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + */ public boolean getAutoHide () { checkWidget (); return autohide; } +/** + * Returns the receiver's message, which will be an empty + * string if it has never been set. + * + * @return the receiver's message + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public String getMessage () { checkWidget (); return message; } +/** + * Returns the receiver's parent, which must be a <code>Shell</code>. + * + * @return the receiver's parent + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public Shell getParent () { checkWidget (); return parent; @@ -188,11 +288,39 @@ Point getSize (int maxWidth) { return new Point (width, height); } +/** + * Returns the receiver's text, which will be an empty + * string if it has never been set. + * + * @return the receiver's text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public String getText () { checkWidget (); return text; } +/** + * Returns <code>true</code> if the receiver is visible, and + * <code>false</code> otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, this method + * may still indicate that it is considered visible even though + * it may not actually be showing. + * </p> + * + * @return the receiver's visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public boolean getVisible () { checkWidget (); if (tip != null) return tip.getVisible (); @@ -205,6 +333,20 @@ public boolean getVisible () { return false; } +/** + * Returns <code>true</code> if the receiver is visible and all + * of the receiver's ancestors are visible and <code>false</code> + * otherwise. + * + * @return the receiver's visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #getVisible + */ public boolean isVisible () { checkWidget (); return getVisible (); @@ -251,6 +393,23 @@ void releaseWidget () { helpString = 0; } +/** + * Removes the listener from the collection of listeners who will + * be notified when the receiver's value changes. + * + * @param listener the listener which should no longer be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see SelectionListener + * @see #addSelectionListener + */ public void removeSelectionListener (SelectionListener listener) { checkWidget(); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -259,12 +418,43 @@ public void removeSelectionListener (SelectionListener listener) { eventTable.unhook (SWT.DefaultSelection,listener); } +/** + * Makes the receiver hide automatically when <code>true</code>, + * and remain visible when <code>false</code>. + * + * @param autoHide the auto hide state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #getVisible + * @see #setVisible + */ public void setAutoHide (boolean autohide) { checkWidget (); this.autohide = autohide; //TODO - update when visible } +/** + * Sets the location of the receiver, which must be a tooltip, + * to the point specified by the arguments which are relative + * to the display. + * <p> + * Note that this is different from most widgets where the + * location of the widget is relative to the parent. + * </p> + * + * @param x the new x coordinate for the receiver + * @param y the new y coordinate for the receiver + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setLocation (int x, int y) { checkWidget (); if (this.x == x && this.y == y) return; @@ -273,12 +463,47 @@ public void setLocation (int x, int y) { if (tip != null && tip.getVisible ()) configure (); } +/** + * Sets the location of the receiver, which must be a tooltip, + * to the point specified by the argument which is relative + * to the display. + * <p> + * Note that this is different from most widgets where the + * location of the widget is relative to the parent. + * </p><p> + * Note that the platform window manager ultimately has control + * over the location of tooltips. + * </p> + * + * @param location the new location for the receiver + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setLocation (Point location) { checkWidget (); if (location == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); setLocation (location.x, location.y); } +/** + * Sets the receiver's message. + * + * @param string the new message + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setMessage (String string) { checkWidget (); if (string == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -289,6 +514,19 @@ public void setMessage (String string) { } } +/** + * Sets the receiver's text. + * + * @param string the new text + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setText (String string) { checkWidget (); if (string == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -301,6 +539,22 @@ public void setText (String string) { } } +/** + * Marks the receiver as visible if the argument is <code>true</code>, + * and marks it invisible otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, marking + * it visible may not actually cause it to be displayed. + * </p> + * + * @param visible the new visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setVisible (boolean visible) { if (helpString != 0) OS.CFRelease (helpString); helpString = 0; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java index a0cb342a99..a1be39e824 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java @@ -1075,6 +1075,23 @@ public void setSelection(int index) { if (!(0 <= index && index < items.length)) return; setSelection(index, false); } +/** + * Sets the receiver's selection to the given item. + * The current selected is first cleared, then the new item is + * selected. + * + * @param item the item to select + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setSelection(TabItem item) { checkWidget(); if (item == null) error(SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java index a9c9ed37e8..f71fde2a40 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java @@ -92,11 +92,11 @@ public TabItem (TabFolder parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> - * <li>ERROR_INVALID_RANGE - if the index is either negative or greater than the parent's current tab count</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -344,14 +344,14 @@ public void setImage (Image image) { * the mnemonic character. * </p> * <p> - * Mnemonics are indicated by an '&' that causes the next + * Mnemonics are indicated by an '&' that causes the next * character to be the mnemonic. When the user presses a * key sequence that matches the mnemonic, a selection * event occurs. On most platforms, the mnemonic appears * underlined but may be emphasised in a platform specific - * manner. The mnemonic indicator character '&' can be + * manner. The mnemonic indicator character '&' can be * escaped by doubling it in the string, causing a single - *'&' to be displayed. + * '&' to be displayed. * </p> * * @param string the new text diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tooltip/org/eclipse/swt/widgets/ToolTip.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tooltip/org/eclipse/swt/widgets/ToolTip.java index 4d53c719e5..90702f093a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tooltip/org/eclipse/swt/widgets/ToolTip.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tooltip/org/eclipse/swt/widgets/ToolTip.java @@ -15,6 +15,23 @@ import org.eclipse.swt.*; import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*; +/** + * Instances of this class represent popup windows that are used + * to inform or warn the user. + * <p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>BALLOON, ICON_ERROR, ICON_INFORMATION, ICON_WARNING</dd> + * <dt><b>Events:</b></dt> + * <dd>Selection</dd> + * </dl> + * </p><p> + * IMPORTANT: This class is intended to be subclassed <em>only</em> + * within the SWT implementation. + * </p> + * + * @since 3.2 + */ public class ToolTip extends Widget { Shell parent, tip; int x, y; @@ -33,6 +50,36 @@ public class ToolTip extends Widget { static final int IMAGE_SIZE = 16; static final int DELAY = 10000; +/** + * Constructs a new instance of this class given its parent + * and a style value describing its behavior and appearance. + * <p> + * The style value is either one of the style constants defined in + * class <code>SWT</code> which is applicable to instances of this + * class, or must be built by <em>bitwise OR</em>'ing together + * (that is, using the <code>int</code> "|" operator) two or more + * of those <code>SWT</code> style constants. The class description + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control to construct + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> + * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> + * </ul> + * + * @see SWT#ICON_ERROR + * @see SWT#ICON_INFORMATION + * @see SWT#ICON_WARNING + * @see Widget#checkSubclass + * @see Widget#getStyle + */ public ToolTip (Shell parent, int style) { super (parent, checkStyle (style)); this.parent = parent; @@ -62,6 +109,26 @@ static int checkStyle (int style) { return checkBits (style, SWT.ICON_INFORMATION, SWT.ICON_WARNING, SWT.ICON_ERROR, 0, 0, 0); } +/** + * Adds the listener to the collection of listeners who will + * be notified when the receiver's value changes, by sending + * it one of the messages defined in the <code>SelectionListener</code> + * interface. + * + * @param listener the listener which should be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see SelectionListener + * @see #removeSelectionListener + * @see SelectionEvent + */ public void addSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -164,6 +231,18 @@ void configure () { } } +/** + * Returns <code>true</code> if the receiver is automatically + * hidden by the platform, and <code>false</code> otherwise. + * + * @return the receiver's auto hide state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + */ public boolean getAutoHide () { checkWidget (); return autohide; @@ -197,26 +276,89 @@ Point getSize (int maxWidth) { return new Point (width, height); } +/** + * Returns the receiver's message, which will be an empty + * string if it has never been set. + * + * @return the receiver's message + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public String getMessage () { checkWidget (); return layoutMessage != null ? layoutMessage.getText() : ""; } +/** + * Returns the receiver's parent, which must be a <code>Shell</code>. + * + * @return the receiver's parent + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public Shell getParent () { checkWidget (); return parent; } +/** + * Returns the receiver's text, which will be an empty + * string if it has never been set. + * + * @return the receiver's text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public String getText () { checkWidget (); return layoutText != null ? layoutText.getText() : ""; } +/** + * Returns <code>true</code> if the receiver is visible, and + * <code>false</code> otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, this method + * may still indicate that it is considered visible even though + * it may not actually be showing. + * </p> + * + * @return the receiver's visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public boolean getVisible () { checkWidget (); return tip.getVisible (); } +/** + * Returns <code>true</code> if the receiver is visible and all + * of the receiver's ancestors are visible and <code>false</code> + * otherwise. + * + * @return the receiver's visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #getVisible + */ public boolean isVisible () { checkWidget (); return getVisible (); @@ -280,6 +422,23 @@ void onPaint (Event event) { } } +/** + * Removes the listener from the collection of listeners who will + * be notified when the receiver's value changes. + * + * @param listener the listener which should no longer be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see SelectionListener + * @see #addSelectionListener + */ public void removeSelectionListener (SelectionListener listener) { checkWidget(); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -288,12 +447,43 @@ public void removeSelectionListener (SelectionListener listener) { eventTable.unhook (SWT.DefaultSelection,listener); } +/** + * Makes the receiver hide automatically when <code>true</code>, + * and remain visible when <code>false</code>. + * + * @param autoHide the auto hide state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #getVisible + * @see #setVisible + */ public void setAutoHide (boolean autohide) { checkWidget (); this.autohide = autohide; //TODO - update when visible } +/** + * Sets the location of the receiver, which must be a tooltip, + * to the point specified by the arguments which are relative + * to the display. + * <p> + * Note that this is different from most widgets where the + * location of the widget is relative to the parent. + * </p> + * + * @param x the new x coordinate for the receiver + * @param y the new y coordinate for the receiver + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setLocation (int x, int y) { checkWidget (); if (this.x == x && this.y == y) return; @@ -302,12 +492,47 @@ public void setLocation (int x, int y) { if (tip.getVisible ()) configure (); } +/** + * Sets the location of the receiver, which must be a tooltip, + * to the point specified by the argument which is relative + * to the display. + * <p> + * Note that this is different from most widgets where the + * location of the widget is relative to the parent. + * </p><p> + * Note that the platform window manager ultimately has control + * over the location of tooltips. + * </p> + * + * @param location the new location for the receiver + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setLocation (Point location) { checkWidget (); if (location == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); setLocation (location.x, location.y); } +/** + * Sets the receiver's message. + * + * @param string the new message + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setMessage (String string) { checkWidget (); if (string == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -321,6 +546,19 @@ public void setMessage (String string) { if (tip.getVisible ()) configure (); } +/** + * Sets the receiver's text. + * + * @param string the new text + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setText (String string) { checkWidget (); if (string == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -341,6 +579,22 @@ public void setText (String string) { if (tip.getVisible ()) configure (); } +/** + * Marks the receiver as visible if the argument is <code>true</code>, + * and marks it invisible otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, marking + * it visible may not actually cause it to be displayed. + * </p> + * + * @param visible the new visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setVisible (boolean visible) { if (visible) configure (); tip.setVisible (visible); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java index 48302deb77..bac2f61bea 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java @@ -18,14 +18,14 @@ import org.eclipse.swt.graphics.*; /** * Instances of this class represent icons that can be placed on the * system tray or task bar status area. - * + * <p> * <dl> * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> * <dd>DefaultSelection, MenuDetect, Selection</dd> * </dl> - * <p> + * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> * @@ -128,6 +128,19 @@ public Tray getParent () { return parent; } +/** + * Returns the receiver's tool tip, or null if it has + * not been set. + * + * @return the receiver's tool tip text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public ToolTip getToolTip () { checkWidget (); return toolTip; @@ -211,6 +224,19 @@ public void setImage (Image image) { super.setImage (image); } +/** + * Sets the receiver's tool tip to the argument, which + * may be null indicating that no tool tip should be shown. + * + * @param toolTip the new tool tip (or null) + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setToolTip (ToolTip toolTip) { checkWidget (); this.toolTip = toolTip; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java index 769aad69cc..514fdd745c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java @@ -17,12 +17,32 @@ import org.eclipse.swt.internal.*; /** * Instances of this class implement a selectable user interface - * object that displays a list of images and strings and issue + * object that displays a list of images and strings and issues * notification when selected. * <p> * The item children that may be added to instances of this class * must be of type <code>TableItem</code>. * </p><p> + * Style <code>VIRTUAL</code> is used to create a <code>Table</code> whose + * <code>TableItem</code>s are to be populated by the client on an on-demand basis + * instead of up-front. This can provide significant performance improvements for + * tables that are very large or for which <code>TableItem</code> population is + * expensive (for example, retrieving values from an external source). + * </p><p> + * Here is an example of using a <code>Table</code> with style <code>VIRTUAL</code>: + * <code><pre> + * final Table table = new Table (parent, SWT.VIRTUAL | SWT.BORDER); + * table.setItemCount (1000000); + * table.addListener (SWT.SetData, new Listener () { + * public void handleEvent (Event event) { + * TableItem item = (TableItem) event.item; + * int index = table.indexOf (item); + * item.setText ("Item " + index); + * System.out.println (item.getText ()); + * } + * }); + * </pre></code> + * </p><p> * Note that although this class is a subclass of <code>Composite</code>, * it does not make sense to add <code>Control</code> children to it, * or set a layout on it. @@ -31,9 +51,9 @@ import org.eclipse.swt.internal.*; * <dt><b>Styles:</b></dt> * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION, HIDE_SELECTION, VIRTUAL</dd> * <dt><b>Events:</b></dt> - * <dd>Selection, DefaultSelection</dd> + * <dd>Selection, DefaultSelection, SetData, MeasureItem, EraseItem, PaintItem</dd> * </dl> - * <p> + * </p><p> * Note: Only one of the styles SINGLE, and MULTI may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -239,8 +259,8 @@ protected void checkSubclass () { /** * Clears the item at the given zero-relative index in the receiver. * The text, icon and other attributes of the item are set to the default - * value. If the table was created with the SWT.VIRTUAL style, these - * attributes are requested again as needed. + * value. If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param index the index of the item to clear * @@ -269,9 +289,9 @@ public void clear (int index) { /** * Removes the items from the receiver which are between the given * zero-relative start and end indices (inclusive). The text, icon - * and other attribues of the items are set to their default values. - * If the table was created with the SWT.VIRTUAL style, these attributes - * are requested again as needed. + * and other attributes of the items are set to their default values. + * If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param start the start index of the item to clear * @param end the end index of the item to clear @@ -303,9 +323,9 @@ public void clear (int start, int end) { } /** * Clears the items at the given zero-relative indices in the receiver. - * The text, icon and other attribues of the items are set to their default - * values. If the table was created with the SWT.VIRTUAL style, these - * attributes are requested again as needed. + * The text, icon and other attributes of the items are set to their default + * values. If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param indices the array of indices of the items * @@ -343,9 +363,9 @@ public void clear (int [] indices) { } /** * Clears all the items in the receiver. The text, icon and other - * attribues of the items are set to their default values. If the - * table was created with the SWT.VIRTUAL style, these attributes - * are requested again as needed. + * attributes of the items are set to their default values. If the + * table was created with the <code>SWT.VIRTUAL</code> style, these + * attributes are requested again as needed. * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -763,6 +783,7 @@ public Control[] getChildren () { /** * Returns the column at the given, zero-relative index in the * receiver. Throws an exception if the index is out of range. + * Columns are returned in the order that they were created. * If no <code>TableColumn</code>s were created by the programmer, * this method will throw <code>ERROR_INVALID_RANGE</code> despite * the fact that a single column of data may be visible in the table. @@ -779,6 +800,12 @@ public Control[] getChildren () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see Table#getColumnOrder() + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move */ public TableColumn getColumn (int index) { checkWidget (); @@ -847,7 +874,8 @@ public int[] getColumnOrder () { } /** * Returns an array of <code>TableColumn</code>s which are the - * columns in the receiver. If no <code>TableColumn</code>s were + * columns in the receiver. Columns are returned in the order + * that they were created. If no <code>TableColumn</code>s were * created by the programmer, the array is empty, despite the fact * that visually, one column of items may be visible. This occurs * when the programmer uses the table like a list, adding items but @@ -864,6 +892,12 @@ public int[] getColumnOrder () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see Table#getColumnOrder() + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move */ public TableColumn[] getColumns () { checkWidget (); @@ -953,9 +987,16 @@ public TableItem getItem (int index) { * Returns the item at the given point in the receiver * or null if no such item exists. The point is in the * coordinate system of the receiver. + * <p> + * The item that is returned represents an item that could be selected by the user. + * For example, if selection only occurs in items in the first column, then null is + * returned if the point is outside of the item. + * Note that the SWT.FULL_SELECTION style hint, which specifies the selection policy, + * determines the extent of the selection. + * </p> * * @param point the point used to locate the item - * @return the item at the given point + * @return the item at the given point, or null if the point is not in a selectable item * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the point is null</li> @@ -2961,7 +3002,7 @@ public void remove (int [] indices) { } /** * Removes all of the items from the receiver. - * <p> + * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> @@ -3053,6 +3094,7 @@ public void select (int index) { * if start is greater than end. * If the receiver is single-select and there is more than one item in the * given range, then all indices are ignored. + * </p> * * @param start the start of the range * @param end the end of the range @@ -3086,6 +3128,7 @@ public void select (int start, int end) { * Indices that are out of range and duplicate indices are ignored. * If the receiver is single-select and multiple indices are specified, * then all indices are ignored. + * </p> * * @param indices the array of indices for the items to select * @@ -3121,6 +3164,7 @@ public void select (int [] indices) { * Selects all of the items in the receiver. * <p> * If the receiver is single-select, do nothing. + * </p> * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -3426,6 +3470,26 @@ public void setRedraw (boolean value) { super.setRedraw (value); header.setRedraw (value); } +/** + * Sets the receiver's selection to the given item. + * The current selection is cleared before the new item is selected. + * <p> + * If the item is not in the receiver, then it is ignored. + * </p> + * + * @param item the item to select + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setSelection (TableItem item) { checkWidget (); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -3438,6 +3502,7 @@ public void setSelection (TableItem item) { * Items that are not in the receiver are ignored. * If the receiver is single-select and multiple items are specified, * then all items are ignored. + * </p> * * @param items the array of items * @@ -3501,7 +3566,7 @@ public void setSelection (TableItem[] items) { * value will clear the sort indicator. The current sort column is cleared * before the new column is set. * - * @param column the column used by the sort indicator + * @param column the column used by the sort indicator or <code>null</code> * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the column is disposed</li> @@ -3577,6 +3642,7 @@ public void setSelection (int index) { * if start is greater than end. * If the receiver is single-select and there is more than one item in the * given range, then all indices are ignored. + * </p> * * @param start the start index of the items to select * @param end the end index of the items to select @@ -3607,6 +3673,7 @@ public void setSelection (int start, int end) { * Indices that are out of range and duplicate indices are ignored. * If the receiver is single-select and multiple indices are specified, * then all indices are ignored. + * </p> * * @param indices the indices of the items to select * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java index cb037d6d3b..7506dbab8a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java @@ -16,13 +16,13 @@ import org.eclipse.swt.graphics.*; /** * Instances of this class represent a column in a table widget. - * <dl> + * <p><dl> * <dt><b>Styles:</b></dt> * <dd>LEFT, RIGHT, CENTER</dd> * <dt><b>Events:</b></dt> * <dd> Move, Resize, Selection</dd> * </dl> - * <p> + * </p><p> * Note: Only one of the styles LEFT, RIGHT and CENTER may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -88,10 +88,11 @@ public TableColumn (Table parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -391,6 +392,19 @@ public boolean getResizable () { checkWidget (); return resizable; } +/** + * Returns the receiver's tool tip text, or null if it has + * not been set. + * + * @return the receiver's tool tip text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public String getToolTipText () { checkWidget (); return toolTipText; @@ -667,6 +681,19 @@ public void setText (String value) { parent.header.redraw (getX (), 0, width, parent.getHeaderHeight (), false); } } +/** + * Sets the receiver's tool tip text to the argument, which + * may be null indicating that no tool tip text should be shown. + * + * @param string the new tool tip text (or null) + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setToolTipText (String string) { checkWidget (); if (toolTipText == string) return; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java index 62ff924970..237bb3d78b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java @@ -96,10 +96,11 @@ public TableItem (Table parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -422,6 +423,19 @@ public Color getBackground (int columnIndex) { if (cellBackgrounds == null || cellBackgrounds [columnIndex] == null) return getBackground (); return cellBackgrounds [columnIndex]; } +/** + * Returns a rectangle describing the receiver's size and location + * relative to its parent. + * + * @return the receiver's bounding rectangle + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public Rectangle getBounds () { checkWidget (); return getBounds (true); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java index a0ba45a6d3..a1c1342795 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java @@ -628,6 +628,23 @@ void setSelection (int index, boolean notify) { } } +/** + * Sets the receiver's selection to the given item. + * The current selected is first cleared, then the new item is + * selected. + * + * @param item the item to select + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setSelection (TabItem item) { if (item == null) error (SWT.ERROR_NULL_ARGUMENT); setSelection (new TabItem [] {item}); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java index 95c9a73694..7d63ef46d5 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java @@ -88,11 +88,11 @@ public TabItem (TabFolder parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> - * <li>ERROR_INVALID_RANGE - if the index is either negative or greater than the parent's current tab count</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -287,14 +287,14 @@ void setOrientation () { * the mnemonic character. * </p> * <p> - * Mnemonics are indicated by an '&' that causes the next + * Mnemonics are indicated by an '&' that causes the next * character to be the mnemonic. When the user presses a * key sequence that matches the mnemonic, a selection * event occurs. On most platforms, the mnemonic appears * underlined but may be emphasised in a platform specific - * manner. The mnemonic indicator character '&' can be + * manner. The mnemonic indicator character '&' can be * escaped by doubling it in the string, causing a single - *'&' to be displayed. + * '&' to be displayed. * </p> * * @param string the new text diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java index a878b13288..25f535d00e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java @@ -19,12 +19,32 @@ import org.eclipse.swt.events.*; /** * Instances of this class implement a selectable user interface - * object that displays a list of images and strings and issue + * object that displays a list of images and strings and issues * notification when selected. * <p> * The item children that may be added to instances of this class * must be of type <code>TableItem</code>. * </p><p> + * Style <code>VIRTUAL</code> is used to create a <code>Table</code> whose + * <code>TableItem</code>s are to be populated by the client on an on-demand basis + * instead of up-front. This can provide significant performance improvements for + * tables that are very large or for which <code>TableItem</code> population is + * expensive (for example, retrieving values from an external source). + * </p><p> + * Here is an example of using a <code>Table</code> with style <code>VIRTUAL</code>: + * <code><pre> + * final Table table = new Table (parent, SWT.VIRTUAL | SWT.BORDER); + * table.setItemCount (1000000); + * table.addListener (SWT.SetData, new Listener () { + * public void handleEvent (Event event) { + * TableItem item = (TableItem) event.item; + * int index = table.indexOf (item); + * item.setText ("Item " + index); + * System.out.println (item.getText ()); + * } + * }); + * </pre></code> + * </p><p> * Note that although this class is a subclass of <code>Composite</code>, * it does not make sense to add <code>Control</code> children to it, * or set a layout on it. @@ -33,9 +53,9 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION, HIDE_SELECTION, VIRTUAL</dd> * <dt><b>Events:</b></dt> - * <dd>Selection, DefaultSelection</dd> + * <dd>Selection, DefaultSelection, SetData, MeasureItem, EraseItem, PaintItem</dd> * </dl> - * <p> + * </p><p> * Note: Only one of the styles SINGLE, and MULTI may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -332,8 +352,8 @@ int calculateWidth (int /*long*/ column, int /*long*/ iter) { /** * Clears the item at the given zero-relative index in the receiver. * The text, icon and other attributes of the item are set to the default - * value. If the table was created with the SWT.VIRTUAL style, these - * attributes are requested again as needed. + * value. If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param index the index of the item to clear * @@ -362,9 +382,9 @@ public void clear (int index) { /** * Removes the items from the receiver which are between the given * zero-relative start and end indices (inclusive). The text, icon - * and other attribues of the items are set to their default values. - * If the table was created with the SWT.VIRTUAL style, these attributes - * are requested again as needed. + * and other attributes of the items are set to their default values. + * If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param start the start index of the item to clear * @param end the end index of the item to clear @@ -400,9 +420,9 @@ public void clear (int start, int end) { /** * Clears the items at the given zero-relative indices in the receiver. - * The text, icon and other attribues of the items are set to their default - * values. If the table was created with the SWT.VIRTUAL style, these - * attributes are requested again as needed. + * The text, icon and other attributes of the items are set to their default + * values. If the table was created with the <code>SWT.VIRTUAL</code> style, + * these attributes are requested again as needed. * * @param indices the array of indices of the items * @@ -437,9 +457,9 @@ public void clear (int [] indices) { /** * Clears all the items in the receiver. The text, icon and other - * attribues of the items are set to their default values. If the - * table was created with the SWT.VIRTUAL style, these attributes - * are requested again as needed. + * attributes of the items are set to their default values. If the + * table was created with the <code>SWT.VIRTUAL</code> style, these + * attributes are requested again as needed. * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1033,6 +1053,7 @@ public Rectangle getClientArea () { /** * Returns the column at the given, zero-relative index in the * receiver. Throws an exception if the index is out of range. + * Columns are returned in the order that they were created. * If no <code>TableColumn</code>s were created by the programmer, * this method will throw <code>ERROR_INVALID_RANGE</code> despite * the fact that a single column of data may be visible in the table. @@ -1049,6 +1070,12 @@ public Rectangle getClientArea () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see Table#getColumnOrder() + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move */ public TableColumn getColumn (int index) { checkWidget(); @@ -1148,7 +1175,8 @@ public int [] getColumnOrder () { /** * Returns an array of <code>TableColumn</code>s which are the - * columns in the receiver. If no <code>TableColumn</code>s were + * columns in the receiver. Columns are returned in the order + * that they were created. If no <code>TableColumn</code>s were * created by the programmer, the array is empty, despite the fact * that visually, one column of items may be visible. This occurs * when the programmer uses the table like a list, adding items but @@ -1165,6 +1193,12 @@ public int [] getColumnOrder () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see Table#getColumnOrder() + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move */ public TableColumn [] getColumns () { checkWidget(); @@ -1291,9 +1325,16 @@ public TableItem getItem (int index) { * Returns the item at the given point in the receiver * or null if no such item exists. The point is in the * coordinate system of the receiver. + * <p> + * The item that is returned represents an item that could be selected by the user. + * For example, if selection only occurs in items in the first column, then null is + * returned if the point is outside of the item. + * Note that the SWT.FULL_SELECTION style hint, which specifies the selection policy, + * determines the extent of the selection. + * </p> * * @param point the point used to locate the item - * @return the item at the given point + * @return the item at the given point, or null if the point is not in a selectable item * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the point is null</li> @@ -2169,7 +2210,7 @@ public void remove (int [] indices) { /** * Removes all of the items from the receiver. - * <p> + * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> @@ -2499,6 +2540,7 @@ public void select (int index) { * if start is greater than end. * If the receiver is single-select and there is more than one item in the * given range, then all indices are ignored. + * </p> * * @param start the start of the range * @param end the end of the range @@ -2541,6 +2583,7 @@ public void select (int start, int end) { * Indices that are out of range and duplicate indices are ignored. * If the receiver is single-select and multiple indices are specified, * then all indices are ignored. + * </p> * * @param indices the array of indices for the items to select * @@ -2581,6 +2624,7 @@ public void select (int [] indices) { * Selects all of the items in the receiver. * <p> * If the receiver is single-select, do nothing. + * </p> * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2841,7 +2885,7 @@ void setScrollWidth (int /*long*/ column, TableItem item) { * value will clear the sort indicator. The current sort column is cleared * before the new column is set. * - * @param column the column used by the sort indicator + * @param column the column used by the sort indicator or <code>null</code> * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the column is disposed</li> @@ -2924,6 +2968,7 @@ public void setSelection (int index) { * if start is greater than end. * If the receiver is single-select and there is more than one item in the * given range, then all indices are ignored. + * </p> * * @param start the start index of the items to select * @param end the end index of the items to select @@ -2959,6 +3004,7 @@ public void setSelection (int start, int end) { * Indices that are out of range and duplicate indices are ignored. * If the receiver is single-select and multiple indices are specified, * then all indices are ignored. + * </p> * * @param indices the indices of the items to select * @@ -2988,6 +3034,26 @@ public void setSelection (int [] indices) { if (fixColumn) hideFirstColumn (); } +/** + * Sets the receiver's selection to the given item. + * The current selection is cleared before the new item is selected. + * <p> + * If the item is not in the receiver, then it is ignored. + * </p> + * + * @param item the item to select + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setSelection (TableItem item) { if (item == null) error (SWT.ERROR_NULL_ARGUMENT); setSelection (new TableItem [] {item}); @@ -3001,6 +3067,7 @@ public void setSelection (TableItem item) { * Items that are not in the receiver are ignored. * If the receiver is single-select and multiple items are specified, * then all items are ignored. + * </p> * * @param items the array of items * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java index 37a268534d..f87f5d2d32 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java @@ -19,13 +19,13 @@ import org.eclipse.swt.events.*; /** * Instances of this class represent a column in a table widget. - * <dl> + * <p><dl> * <dt><b>Styles:</b></dt> * <dd>LEFT, RIGHT, CENTER</dd> * <dt><b>Events:</b></dt> * <dd> Move, Resize, Selection</dd> * </dl> - * <p> + * </p><p> * Note: Only one of the styles LEFT, RIGHT and CENTER may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -93,10 +93,11 @@ public TableColumn (Table parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -279,6 +280,19 @@ public boolean getResizable () { return OS.gtk_tree_view_column_get_resizable (handle); } +/** + * Returns the receiver's tool tip text, or null if it has + * not been set. + * + * @return the receiver's tool tip text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public String getToolTipText () { checkWidget(); return toolTipText; @@ -582,6 +596,19 @@ public void setText (String string) { } } +/** + * Sets the receiver's tool tip text to the argument, which + * may be null indicating that no tool tip text should be shown. + * + * @param string the new tool tip text (or null) + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setToolTipText (String string) { checkWidget(); Shell shell = parent._getShell (); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java index 93a7cf29d3..4a34d2f8ef 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java @@ -52,10 +52,11 @@ public class TableItem extends Item { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -176,6 +177,19 @@ public Color getBackground () { return Color.gtk_new (display, gdkColor); } +/** + * Returns a rectangle describing the receiver's size and location + * relative to its parent. + * + * @return the receiver's bounding rectangle + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public Rectangle getBounds () { // TODO fully test on early and later versions of GTK // shifted a bit too far right on later versions of GTK - however, old Tree also had this problem diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java index 7137786c96..78a0b16eb3 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java @@ -17,6 +17,23 @@ import org.eclipse.swt.internal.gtk.*; import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*; +/** + * Instances of this class represent popup windows that are used + * to inform or warn the user. + * <p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>BALLOON, ICON_ERROR, ICON_INFORMATION, ICON_WARNING</dd> + * <dt><b>Events:</b></dt> + * <dd>Selection</dd> + * </dl> + * </p><p> + * IMPORTANT: This class is intended to be subclassed <em>only</em> + * within the SWT implementation. + * </p> + * + * @since 3.2 + */ public class ToolTip extends Widget { Shell parent; String text, message; @@ -33,6 +50,36 @@ public class ToolTip extends Widget { static final int IMAGE_SIZE = 16; static final int DELAY = 8000; +/** + * Constructs a new instance of this class given its parent + * and a style value describing its behavior and appearance. + * <p> + * The style value is either one of the style constants defined in + * class <code>SWT</code> which is applicable to instances of this + * class, or must be built by <em>bitwise OR</em>'ing together + * (that is, using the <code>int</code> "|" operator) two or more + * of those <code>SWT</code> style constants. The class description + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control to construct + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> + * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> + * </ul> + * + * @see SWT#ICON_ERROR + * @see SWT#ICON_INFORMATION + * @see SWT#ICON_WARNING + * @see Widget#checkSubclass + * @see Widget#getStyle + */ public ToolTip (Shell parent, int style) { super (parent, checkStyle (style)); this.parent = parent; @@ -45,6 +92,26 @@ static int checkStyle (int style) { return checkBits (style, SWT.ICON_INFORMATION, SWT.ICON_WARNING, SWT.ICON_ERROR, 0, 0, 0); } +/** + * Adds the listener to the collection of listeners who will + * be notified when the receiver's value changes, by sending + * it one of the messages defined in the <code>SelectionListener</code> + * interface. + * + * @param listener the listener which should be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see SelectionListener + * @see #removeSelectionListener + * @see SelectionEvent + */ public void addSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -190,6 +257,18 @@ void destroyWidget () { } } +/** + * Returns <code>true</code> if the receiver is automatically + * hidden by the platform, and <code>false</code> otherwise. + * + * @return the receiver's auto hide state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + */ public boolean getAutoHide () { checkWidget (); return autohide; @@ -216,6 +295,17 @@ Point getLocation () { return new Point(x, y); } +/** + * Returns the receiver's message, which will be an empty + * string if it has never been set. + * + * @return the receiver's message + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public String getMessage () { checkWidget (); return message; @@ -225,6 +315,16 @@ String getNameText () { return getText (); } +/** + * Returns the receiver's parent, which must be a <code>Shell</code>. + * + * @return the receiver's parent + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public Shell getParent () { checkWidget (); return parent; @@ -263,11 +363,39 @@ Point getSize (int maxWidth) { return new Point(width, height); } +/** + * Returns the receiver's text, which will be an empty + * string if it has never been set. + * + * @return the receiver's text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public String getText () { checkWidget (); return text; } +/** + * Returns <code>true</code> if the receiver is visible, and + * <code>false</code> otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, this method + * may still indicate that it is considered visible even though + * it may not actually be showing. + * </p> + * + * @return the receiver's visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public boolean getVisible () { checkWidget (); if ((style & SWT.BALLOON) != 0) return OS.GTK_WIDGET_VISIBLE (handle); @@ -356,6 +484,20 @@ void hookEvents () { } } +/** + * Returns <code>true</code> if the receiver is visible and all + * of the receiver's ancestors are visible and <code>false</code> + * otherwise. + * + * @return the receiver's visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #getVisible + */ public boolean isVisible () { checkWidget (); return getVisible (); @@ -382,6 +524,23 @@ void releaseWidget () { borderPolygon = null; } +/** + * Removes the listener from the collection of listeners who will + * be notified when the receiver's value changes. + * + * @param listener the listener which should no longer be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see SelectionListener + * @see #addSelectionListener + */ public void removeSelectionListener (SelectionListener listener) { checkWidget(); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -390,12 +549,43 @@ public void removeSelectionListener (SelectionListener listener) { eventTable.unhook (SWT.DefaultSelection, listener); } +/** + * Makes the receiver hide automatically when <code>true</code>, + * and remain visible when <code>false</code>. + * + * @param autoHide the auto hide state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #getVisible + * @see #setVisible + */ public void setAutoHide (boolean autohide) { checkWidget (); this.autohide = autohide; //TODO - update when visible } +/** + * Sets the location of the receiver, which must be a tooltip, + * to the point specified by the arguments which are relative + * to the display. + * <p> + * Note that this is different from most widgets where the + * location of the widget is relative to the parent. + * </p> + * + * @param x the new x coordinate for the receiver + * @param y the new y coordinate for the receiver + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setLocation (int x, int y) { checkWidget (); this.x = x; @@ -410,12 +600,47 @@ public void setLocation (int x, int y) { } } +/** + * Sets the location of the receiver, which must be a tooltip, + * to the point specified by the argument which is relative + * to the display. + * <p> + * Note that this is different from most widgets where the + * location of the widget is relative to the parent. + * </p><p> + * Note that the platform window manager ultimately has control + * over the location of tooltips. + * </p> + * + * @param location the new location for the receiver + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setLocation (Point location) { checkWidget (); if (location == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); setLocation (location.x, location.y); } +/** + * Sets the receiver's message. + * + * @param string the new message + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setMessage (String string) { checkWidget (); if (string == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -431,6 +656,19 @@ public void setMessage (String string) { if (OS.GTK_WIDGET_VISIBLE (handle)) configure (); } +/** + * Sets the receiver's text. + * + * @param string the new text + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setText (String string) { checkWidget (); if (string == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -456,6 +694,22 @@ public void setText (String string) { if (OS.GTK_WIDGET_VISIBLE (handle)) configure (); } +/** + * Marks the receiver as visible if the argument is <code>true</code>, + * and marks it invisible otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, marking + * it visible may not actually cause it to be displayed. + * </p> + * + * @param visible the new visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setVisible (boolean visible) { if (timerId != 0) OS.gtk_timeout_remove(timerId); timerId = 0; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java index d4f43dff73..ed0fbc2ea9 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java @@ -19,14 +19,14 @@ import org.eclipse.swt.internal.gtk.*; /** * Instances of this class represent icons that can be placed on the * system tray or task bar status area. - * + * <p> * <dl> * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> * <dd>DefaultSelection, MenuDetect, Selection</dd> * </dl> - * <p> + * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> * @@ -181,6 +181,19 @@ public Tray getParent () { return parent; } +/** + * Returns the receiver's tool tip, or null if it has + * not been set. + * + * @return the receiver's tool tip text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public ToolTip getToolTip () { checkWidget (); return toolTip; @@ -356,6 +369,19 @@ public void setImage (Image image) { } } +/** + * Sets the receiver's tool tip to the argument, which + * may be null indicating that no tool tip should be shown. + * + * @param toolTip the new tool tip (or null) + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ public void setToolTip (ToolTip toolTip) { checkWidget (); ToolTip oldTip = this.toolTip, newTip = toolTip; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java index e0d1cf8d6e..74ae8e83fe 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java @@ -12,6 +12,7 @@ package org.eclipse.swt.widgets; import org.eclipse.swt.internal.photon.*; +import org.eclipse.swt.widgets.TabItem; import org.eclipse.swt.*; import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*; @@ -636,6 +637,29 @@ void setSelection (int index, boolean notify) { } /** + * Sets the receiver's selection to the given item. + * The current selected is first cleared, then the new item is + * selected. + * + * @param item the item to select + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.2 + */ +public void setSelection (TabItem item) { + checkWidget (); + if (item == null) error (SWT.ERROR_NULL_ARGUMENT); + setSelection (new TabItem [] {item}); +} + +/** * Sets the receiver's selection to be the given array of items. * The current selected is first cleared, then the new items are * selected. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabItem.java index eeabcf2346..b8f7d22fd7 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabItem.java @@ -87,11 +87,11 @@ public TabItem (TabFolder parent, int style) { * * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct - * @param index the index to store the receiver in its parent + * @param index the zero-relative index to store the receiver in its parent * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> - * <li>ERROR_INVALID_RANGE - if the index is either negative or greater than the parent's current tab count</li> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the parent (inclusive)</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -232,14 +232,14 @@ public void setImage (Image image) { * the mnemonic character. * </p> * <p> - * Mnemonics are indicated by an '&' that causes the next + * Mnemonics are indicated by an '&' that causes the next * character to be the mnemonic. When the user presses a * key sequence that matches the mnemonic, a selection * event occurs. On most platforms, the mnemonic appears * underlined but may be emphasised in a platform specific - * manner. The mnemonic indicator character '&' can be + * manner. The mnemonic indicator character '&' can be * escaped by doubling it in the string, causing a single - *'&' to be displayed. + * '&' to be displayed. * </p> * * @param string the new text |