001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.swt.widgets;
011:
012: import org.eclipse.swt.*;
013: import org.eclipse.swt.events.*;
014: import org.eclipse.swt.graphics.*;
015:
016: /**
017: * Instances of this class represent icons that can be placed on the
018: * system tray or task bar status area.
019: * <p>
020: * <dl>
021: * <dt><b>Styles:</b></dt>
022: * <dd>(none)</dd>
023: * <dt><b>Events:</b></dt>
024: * <dd>DefaultSelection, MenuDetect, Selection</dd>
025: * </dl>
026: * </p><p>
027: * IMPORTANT: This class is <em>not</em> intended to be subclassed.
028: * </p>
029: *
030: * @since 3.0
031: */
032: public class TrayItem extends Item {
033: Tray parent;
034: ToolTip toolTip;
035: String toolTipText;
036: boolean visible = true;
037:
038: /**
039: * Constructs a new instance of this class given its parent
040: * (which must be a <code>Tray</code>) and a style value
041: * describing its behavior and appearance. The item is added
042: * to the end of the items maintained by its parent.
043: * <p>
044: * The style value is either one of the style constants defined in
045: * class <code>SWT</code> which is applicable to instances of this
046: * class, or must be built by <em>bitwise OR</em>'ing together
047: * (that is, using the <code>int</code> "|" operator) two or more
048: * of those <code>SWT</code> style constants. The class description
049: * lists the style constants that are applicable to the class.
050: * Style bits are also inherited from superclasses.
051: * </p>
052: *
053: * @param parent a composite control which will be the parent of the new instance (cannot be null)
054: * @param style the style of control to construct
055: *
056: * @exception IllegalArgumentException <ul>
057: * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
058: * </ul>
059: * @exception SWTException <ul>
060: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
061: * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
062: * </ul>
063: *
064: * @see SWT
065: * @see Widget#checkSubclass
066: * @see Widget#getStyle
067: */
068: public TrayItem(Tray parent, int style) {
069: super (parent, style);
070: this .parent = parent;
071: parent.createItem(this , parent.getItemCount());
072: }
073:
074: /**
075: * Adds the listener to the collection of listeners who will
076: * be notified when the platform-specific context menu trigger
077: * has occurred, by sending it one of the messages defined in
078: * the <code>MenuDetectListener</code> interface.
079: *
080: * @param listener the listener which should be notified
081: *
082: * @exception IllegalArgumentException <ul>
083: * <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
084: * </ul>
085: * @exception SWTException <ul>
086: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
087: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
088: * </ul>
089: *
090: * @see MenuDetectListener
091: * @see #removeMenuDetectListener
092: *
093: * @since 3.3
094: */
095: public void addMenuDetectListener(MenuDetectListener listener) {
096: checkWidget();
097: if (listener == null)
098: error(SWT.ERROR_NULL_ARGUMENT);
099: }
100:
101: /**
102: * Adds the listener to the collection of listeners who will
103: * be notified when the receiver is selected by the user, by sending
104: * it one of the messages defined in the <code>SelectionListener</code>
105: * interface.
106: * <p>
107: * <code>widgetSelected</code> is called when the receiver is selected
108: * <code>widgetDefaultSelected</code> is called when the receiver is double-clicked
109: * </p>
110: *
111: * @param listener the listener which should be notified when the receiver is selected by the user
112: *
113: * @exception IllegalArgumentException <ul>
114: * <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
115: * </ul>
116: * @exception SWTException <ul>
117: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
118: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
119: * </ul>
120: *
121: * @see SelectionListener
122: * @see #removeSelectionListener
123: * @see SelectionEvent
124: */
125: public void addSelectionListener(SelectionListener listener) {
126: checkWidget();
127: if (listener == null)
128: error(SWT.ERROR_NULL_ARGUMENT);
129: }
130:
131: protected void checkSubclass() {
132: if (!isValidSubclass())
133: error(SWT.ERROR_INVALID_SUBCLASS);
134: }
135:
136: void destroyWidget() {
137: parent.destroyItem(this );
138: releaseHandle();
139: }
140:
141: /**
142: * Returns the receiver's parent, which must be a <code>Tray</code>.
143: *
144: * @return the receiver's parent
145: *
146: * @exception SWTException <ul>
147: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
148: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
149: * </ul>
150: *
151: * @since 3.2
152: */
153: public Tray getParent() {
154: checkWidget();
155: return parent;
156: }
157:
158: /**
159: * Returns the receiver's tool tip, or null if it has
160: * not been set.
161: *
162: * @return the receiver's tool tip text
163: *
164: * @exception SWTException <ul>
165: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
166: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
167: * </ul>
168: *
169: * @since 3.2
170: */
171: public ToolTip getToolTip() {
172: checkWidget();
173: return toolTip;
174: }
175:
176: /**
177: * Returns the receiver's tool tip text, or null if it has
178: * not been set.
179: *
180: * @return the receiver's tool tip text
181: *
182: * @exception SWTException <ul>
183: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
184: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
185: * </ul>
186: */
187: public String getToolTipText() {
188: checkWidget();
189: return toolTipText;
190: }
191:
192: /**
193: * Returns <code>true</code> if the receiver is visible and
194: * <code>false</code> otherwise.
195: *
196: * @return the receiver's visibility
197: *
198: * @exception SWTException <ul>
199: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
200: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
201: * </ul>
202: */
203: public boolean getVisible() {
204: checkWidget();
205: return visible;
206: }
207:
208: void releaseHandle() {
209: super .releaseHandle();
210: parent = null;
211: }
212:
213: /**
214: * Removes the listener from the collection of listeners who will
215: * be notified when the platform-specific context menu trigger has
216: * occurred.
217: *
218: * @param listener the listener which should no longer be notified
219: *
220: * @exception IllegalArgumentException <ul>
221: * <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
222: * </ul>
223: * @exception SWTException <ul>
224: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
225: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
226: * </ul>
227: *
228: * @see MenuDetectListener
229: * @see #addMenuDetectListener
230: *
231: * @since 3.3
232: */
233: public void removeMenuDetectListener(MenuDetectListener listener) {
234: checkWidget();
235: if (listener == null)
236: error(SWT.ERROR_NULL_ARGUMENT);
237: }
238:
239: /**
240: * Removes the listener from the collection of listeners who will
241: * be notified when the receiver is selected by the user.
242: *
243: * @param listener the listener which should no longer be notified
244: *
245: * @exception IllegalArgumentException <ul>
246: * <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
247: * </ul>
248: * @exception SWTException <ul>
249: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
250: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
251: * </ul>
252: *
253: * @see SelectionListener
254: * @see #addSelectionListener
255: */
256: public void removeSelectionListener(SelectionListener listener) {
257: checkWidget();
258: if (listener == null)
259: error(SWT.ERROR_NULL_ARGUMENT);
260: }
261:
262: /**
263: * Sets the receiver's image.
264: *
265: * @param image the new image
266: *
267: * @exception IllegalArgumentException <ul>
268: * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
269: * </ul>
270: * @exception SWTException <ul>
271: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
272: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
273: * </ul>
274: */
275: public void setImage(Image image) {
276: checkWidget();
277: if (image != null && image.isDisposed())
278: error(SWT.ERROR_INVALID_ARGUMENT);
279: super .setImage(image);
280: }
281:
282: /**
283: * Sets the receiver's tool tip to the argument, which
284: * may be null indicating that no tool tip should be shown.
285: *
286: * @param toolTip the new tool tip (or null)
287: *
288: * @exception SWTException <ul>
289: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
290: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
291: * </ul>
292: *
293: * @since 3.2
294: */
295: public void setToolTip(ToolTip toolTip) {
296: checkWidget();
297: this .toolTip = toolTip;
298: }
299:
300: /**
301: * Sets the receiver's tool tip text to the argument, which
302: * may be null indicating that no tool tip text should be shown.
303: *
304: * @param value the new tool tip text (or null)
305: *
306: * @exception SWTException <ul>
307: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
308: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
309: * </ul>
310: */
311: public void setToolTipText(String string) {
312: checkWidget();
313: toolTipText = string;
314: }
315:
316: /**
317: * Makes the receiver visible if the argument is <code>true</code>,
318: * and makes it invisible otherwise.
319: *
320: * @param visible the new visibility state
321: *
322: * @exception SWTException <ul>
323: * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
324: * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
325: * </ul>
326: */
327: public void setVisible(boolean visible) {
328: checkWidget();
329: if (this.visible == visible)
330: return;
331: if (visible)
332: sendEvent(SWT.Show);
333: this.visible = visible;
334: if (!visible)
335: sendEvent(SWT.Hide);
336: }
337: }
|