KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > swt > widgets > ToolTip


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.swt.widgets;
12
13
14 import org.eclipse.swt.graphics.*;
15 import org.eclipse.swt.internal.win32.*;
16 import org.eclipse.swt.*;
17 import org.eclipse.swt.events.*;
18
19 /**
20  * Instances of this class represent popup windows that are used
21  * to inform or warn the user.
22  * <p>
23  * <dl>
24  * <dt><b>Styles:</b></dt>
25  * <dd>BALLOON, ICON_ERROR, ICON_INFORMATION, ICON_WARNING</dd>
26  * <dt><b>Events:</b></dt>
27  * <dd>Selection</dd>
28  * </dl>
29  * </p><p>
30  * Note: Only one of the styles ICON_ERROR, ICON_INFORMATION,
31  * and ICON_WARNING may be specified.
32  * </p><p>
33  * IMPORTANT: This class is intended to be subclassed <em>only</em>
34  * within the SWT implementation.
35  * </p>
36  *
37  * @since 3.2
38  */
39
40 public class ToolTip extends Widget {
41     Shell parent;
42     TrayItem item;
43     String JavaDoc text = "", message = "";
44     int id, x, y;
45     boolean autoHide = true, hasLocation, visible;
46     static final int TIMER_ID = 100;
47
48 /**
49  * Constructs a new instance of this class given its parent
50  * and a style value describing its behavior and appearance.
51  * <p>
52  * The style value is either one of the style constants defined in
53  * class <code>SWT</code> which is applicable to instances of this
54  * class, or must be built by <em>bitwise OR</em>'ing together
55  * (that is, using the <code>int</code> "|" operator) two or more
56  * of those <code>SWT</code> style constants. The class description
57  * lists the style constants that are applicable to the class.
58  * Style bits are also inherited from superclasses.
59  * </p>
60  *
61  * @param parent a composite control which will be the parent of the new instance (cannot be null)
62  * @param style the style of control to construct
63  *
64  * @exception IllegalArgumentException <ul>
65  * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
66  * </ul>
67  * @exception SWTException <ul>
68  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
69  * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
70  * </ul>
71  *
72  * @see SWT#ICON_ERROR
73  * @see SWT#ICON_INFORMATION
74  * @see SWT#ICON_WARNING
75  * @see Widget#checkSubclass
76  * @see Widget#getStyle
77  */
78 public ToolTip (Shell parent, int style) {
79     super (parent, checkStyle (style));
80     this.parent = parent;
81     checkOrientation (parent);
82     parent.createToolTip (this);
83 }
84
85 static int checkStyle (int style) {
86     int mask = SWT.ICON_ERROR | SWT.ICON_INFORMATION | SWT.ICON_WARNING;
87     if ((style & mask) == 0) return style;
88     return checkBits (style, SWT.ICON_INFORMATION, SWT.ICON_WARNING, SWT.ICON_ERROR, 0, 0, 0);
89 }
90
91 /**
92  * Adds the listener to the collection of listeners who will
93  * be notified when the receiver is selected by the user, by sending
94  * it one of the messages defined in the <code>SelectionListener</code>
95  * interface.
96  * <p>
97  * <code>widgetSelected</code> is called when the receiver is selected.
98  * <code>widgetDefaultSelected</code> is not called.
99  * </p>
100  *
101  * @param listener the listener which should be notified when the receiver is selected by the user
102  *
103  * @exception IllegalArgumentException <ul>
104  * <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
105  * </ul>
106  * @exception SWTException <ul>
107  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
108  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
109  * </ul>
110  *
111  * @see SelectionListener
112  * @see #removeSelectionListener
113  * @see SelectionEvent
114  */
115 public void addSelectionListener (SelectionListener listener) {
116     checkWidget ();
117     if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
118     TypedListener typedListener = new TypedListener(listener);
119     addListener (SWT.Selection,typedListener);
120     addListener (SWT.DefaultSelection,typedListener);
121 }
122
123 void destroyWidget () {
124     if (parent != null) parent.destroyToolTip (this);
125     releaseHandle ();
126 }
127
128 /**
129  * Returns <code>true</code> if the receiver is automatically
130  * hidden by the platform, and <code>false</code> otherwise.
131  *
132  * @return the receiver's auto hide state
133  *
134  * @exception SWTException <ul>
135  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
136  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
137  * </ul>
138  *
139  */
140 public boolean getAutoHide () {
141     checkWidget();
142     return autoHide;
143 }
144
145 /**
146  * Returns the receiver's message, which will be an empty
147  * string if it has never been set.
148  *
149  * @return the receiver's message
150  *
151  * @exception SWTException <ul>
152  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
153  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
154  * </ul>
155  */
156 public String JavaDoc getMessage () {
157     checkWidget();
158     return message;
159 }
160
161 /**
162  * Returns the receiver's parent, which must be a <code>Shell</code>.
163  *
164  * @return the receiver's parent
165  *
166  * @exception SWTException <ul>
167  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
168  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
169  * </ul>
170  */
171 public Shell getParent () {
172     checkWidget ();
173     return parent;
174 }
175
176 /**
177  * Returns the receiver's text, which will be an empty
178  * string if it has never been set.
179  *
180  * @return the receiver's 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 JavaDoc getText () {
188     checkWidget();
189     return text;
190 }
191
192 /**
193  * Returns <code>true</code> if the receiver is visible, and
194  * <code>false</code> otherwise.
195  * <p>
196  * If one of the receiver's ancestors is not visible or some
197  * other condition makes the receiver not visible, this method
198  * may still indicate that it is considered visible even though
199  * it may not actually be showing.
200  * </p>
201  *
202  * @return the receiver's visibility state
203  *
204  * @exception SWTException <ul>
205  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
206  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
207  * </ul>
208  */
209 public boolean getVisible () {
210     checkWidget();
211     if (OS.IsWinCE) return false;
212     if (item != null) return visible;
213     int hwndToolTip = hwndToolTip ();
214     if (OS.SendMessage (hwndToolTip, OS.TTM_GETCURRENTTOOL, 0, 0) != 0) {
215         TOOLINFO lpti = new TOOLINFO ();
216         lpti.cbSize = TOOLINFO.sizeof;
217         if (OS.SendMessage (hwndToolTip, OS.TTM_GETCURRENTTOOL, 0, lpti) != 0) {
218             return (lpti.uFlags & OS.TTF_IDISHWND) == 0 && lpti.uId == id;
219         }
220     }
221     return false;
222 }
223
224 int hwndToolTip () {
225     return (style & SWT.BALLOON) != 0 ? parent.balloonTipHandle () : parent.toolTipHandle ();
226 }
227
228 /**
229  * Returns <code>true</code> if the receiver is visible and all
230  * of the receiver's ancestors are visible and <code>false</code>
231  * otherwise.
232  *
233  * @return the receiver's visibility state
234  *
235  * @exception SWTException <ul>
236  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
237  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
238  * </ul>
239  *
240  * @see #getVisible
241  */
242 public boolean isVisible () {
243     checkWidget ();
244     if (item != null) return getVisible () && item.getVisible ();
245     return getVisible ();
246 }
247
248 void releaseHandle () {
249     super.releaseHandle ();
250     parent = null;
251     item = null;
252     id = -1;
253 }
254
255 void releaseWidget () {
256     super.releaseWidget ();
257     if (item == null) {
258         if (autoHide) {
259             int hwndToolTip = hwndToolTip ();
260             if (OS.SendMessage (hwndToolTip, OS.TTM_GETCURRENTTOOL, 0, 0) != 0) {
261                 TOOLINFO lpti = new TOOLINFO ();
262                 lpti.cbSize = TOOLINFO.sizeof;
263                 if (OS.SendMessage (hwndToolTip, OS.TTM_GETCURRENTTOOL, 0, lpti) != 0) {
264                     if ((lpti.uFlags & OS.TTF_IDISHWND) == 0) {
265                         if (lpti.uId == id) {
266                             OS.SendMessage (hwndToolTip, OS.TTM_TRACKACTIVATE, 0, lpti);
267                             OS.SendMessage (hwndToolTip, OS.TTM_POP, 0, 0);
268                             OS.KillTimer (hwndToolTip, TIMER_ID);
269                         }
270                     }
271                 }
272             }
273         }
274     }
275     if (item != null && item.toolTip == this) {
276         item.toolTip = null;
277     }
278     item = null;
279     text = message = null;
280 }
281
282 /**
283  * Removes the listener from the collection of listeners who will
284  * be notified when the receiver is selected by the user.
285  *
286  * @param listener the listener which should no longer be notified
287  *
288  * @exception IllegalArgumentException <ul>
289  * <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
290  * </ul>
291  * @exception SWTException <ul>
292  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
293  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
294  * </ul>
295  *
296  * @see SelectionListener
297  * @see #addSelectionListener
298  */
299 public void removeSelectionListener (SelectionListener listener) {
300     checkWidget ();
301     if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
302     if (eventTable == null) return;
303     eventTable.unhook (SWT.Selection, listener);
304     eventTable.unhook (SWT.DefaultSelection,listener);
305 }
306
307 /**
308  * Makes the receiver hide automatically when <code>true</code>,
309  * and remain visible when <code>false</code>.
310  *
311  * @param autoHide the auto hide state
312  *
313  * @exception SWTException <ul>
314  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
315  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
316  * </ul>
317  *
318  * @see #getVisible
319  * @see #setVisible
320  */
321 public void setAutoHide (boolean autoHide) {
322     checkWidget ();
323     this.autoHide = autoHide;
324     //TODO - update when visible
325 }
326
327 /**
328  * Sets the location of the receiver, which must be a tooltip,
329  * to the point specified by the arguments which are relative
330  * to the display.
331  * <p>
332  * Note that this is different from most widgets where the
333  * location of the widget is relative to the parent.
334  * </p>
335  *
336  * @param x the new x coordinate for the receiver
337  * @param y the new y coordinate for the receiver
338  *
339  * @exception SWTException <ul>
340  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
341  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
342  * </ul>
343  */
344 public void setLocation (int x, int y) {
345     checkWidget ();
346     this.x = x;
347     this.y = y;
348     hasLocation = true;
349     //TODO - update when visible
350 }
351
352 /**
353  * Sets the location of the receiver, which must be a tooltip,
354  * to the point specified by the argument which is relative
355  * to the display.
356  * <p>
357  * Note that this is different from most widgets where the
358  * location of the widget is relative to the parent.
359  * </p><p>
360  * Note that the platform window manager ultimately has control
361  * over the location of tooltips.
362  * </p>
363  *
364  * @param location the new location for the receiver
365  *
366  * @exception IllegalArgumentException <ul>
367  * <li>ERROR_NULL_ARGUMENT - if the point is null</li>
368  * </ul>
369  * @exception SWTException <ul>
370  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
371  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
372  * </ul>
373  */
374 public void setLocation (Point location) {
375     checkWidget ();
376     if (location == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
377     setLocation (location.x, location.y);
378 }
379
380 /**
381  * Sets the receiver's message.
382  *
383  * @param string the new message
384  *
385  * @exception IllegalArgumentException <ul>
386  * <li>ERROR_NULL_ARGUMENT - if the text is null</li>
387  * </ul>
388  * @exception SWTException <ul>
389  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
390  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
391  * </ul>
392  */
393 public void setMessage (String JavaDoc string) {
394     checkWidget ();
395     if (string == null) error (SWT.ERROR_NULL_ARGUMENT);
396     message = string;
397     //TODO - update when visible
398 }
399
400 /**
401  * Sets the receiver's text.
402  *
403  * @param string the new text
404  *
405  * @exception IllegalArgumentException <ul>
406  * <li>ERROR_NULL_ARGUMENT - if the text is null</li>
407  * </ul>
408  * @exception SWTException <ul>
409  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
410  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
411  * </ul>
412  */
413 public void setText (String JavaDoc string) {
414     checkWidget ();
415     if (string == null) error (SWT.ERROR_NULL_ARGUMENT);
416     text = string;
417     //TODO - update when visible
418 }
419
420 /**
421  * Marks the receiver as visible if the argument is <code>true</code>,
422  * and marks it invisible otherwise.
423  * <p>
424  * If one of the receiver's ancestors is not visible or some
425  * other condition makes the receiver not visible, marking
426  * it visible may not actually cause it to be displayed.
427  * </p>
428  *
429  * @param visible the new visibility state
430  *
431  * @exception SWTException <ul>
432  * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
433  * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
434  * </ul>
435  */
436 public void setVisible (boolean visible) {
437     checkWidget ();
438     if (OS.IsWinCE) return;
439     if (visible == getVisible ()) return;
440     if (item == null) {
441         int hwnd = parent.handle;
442         TOOLINFO lpti = new TOOLINFO ();
443         lpti.cbSize = TOOLINFO.sizeof;
444         lpti.uId = id;
445         lpti.hwnd = hwnd;
446         int hwndToolTip = hwndToolTip ();
447         Shell shell = parent.getShell ();
448         if (text.length () != 0) {
449             int icon = OS.TTI_NONE;
450             if ((style & SWT.ICON_INFORMATION) != 0) icon = OS.TTI_INFO;
451             if ((style & SWT.ICON_WARNING) != 0) icon = OS.TTI_WARNING;
452             if ((style & SWT.ICON_ERROR) != 0) icon = OS.TTI_ERROR;
453             shell.setToolTipTitle (hwndToolTip, text, icon);
454         } else {
455             shell.setToolTipTitle (hwndToolTip, null, 0);
456         }
457         int maxWidth = 0;
458         if (OS.IsWinCE || OS.WIN32_VERSION < OS.VERSION (4, 10)) {
459             RECT rect = new RECT ();
460             OS.SystemParametersInfo (OS.SPI_GETWORKAREA, 0, rect, 0);
461             maxWidth = (rect.right - rect.left) / 4;
462         } else {
463             int hmonitor = OS.MonitorFromWindow (hwnd, OS.MONITOR_DEFAULTTONEAREST);
464             MONITORINFO lpmi = new MONITORINFO ();
465             lpmi.cbSize = MONITORINFO.sizeof;
466             OS.GetMonitorInfo (hmonitor, lpmi);
467             maxWidth = (lpmi.rcWork_right - lpmi.rcWork_left) / 4;
468         }
469         OS.SendMessage (hwndToolTip, OS.TTM_SETMAXTIPWIDTH, 0, maxWidth);
470         if (visible) {
471             int nX = x, nY = y;
472             if (!hasLocation) {
473                 POINT pt = new POINT ();
474                 if (OS.GetCursorPos (pt)) {
475                     nX = pt.x;
476                     nY = pt.y;
477                 }
478             }
479             int lParam = (nX & 0xFFFF) | ((nY << 16) & 0xFFFF0000);
480             OS.SendMessage (hwndToolTip, OS.TTM_TRACKPOSITION, 0, lParam);
481             
482             /*
483             * Feature in Windows. Windows will not show a tool tip
484             * if the cursor is outside the parent window (even on XP,
485             * TTM_POPUP will not do this). The fix is to temporarily
486             * move the cursor into the tool window, show the tool tip,
487             * and then restore the cursor.
488             */
489             POINT pt = new POINT ();
490             OS.GetCursorPos (pt);
491             RECT rect = new RECT ();
492             OS.GetClientRect (hwnd, rect);
493             OS.MapWindowPoints (hwnd, 0, rect, 2);
494             if (!OS.PtInRect (rect, pt)) {
495                 int hCursor = OS.GetCursor ();
496                 OS.SetCursor (0);
497                 OS.SetCursorPos (rect.left, rect.top);
498                 OS.SendMessage (hwndToolTip, OS.TTM_TRACKACTIVATE, 1, lpti);
499                 OS.SetCursorPos (pt.x, pt.y);
500                 OS.SetCursor (hCursor);
501             } else {
502                 OS.SendMessage (hwndToolTip, OS.TTM_TRACKACTIVATE, 1, lpti);
503             }
504             
505             int time = OS.SendMessage (hwndToolTip, OS.TTM_GETDELAYTIME, OS.TTDT_AUTOPOP, 0);
506             OS.SetTimer (hwndToolTip, TIMER_ID, time, 0);
507         } else {
508             OS.SendMessage (hwndToolTip, OS.TTM_TRACKACTIVATE, 0, lpti);
509             OS.SendMessage (hwndToolTip, OS.TTM_POP, 0, 0);
510             OS.KillTimer (hwndToolTip, TIMER_ID);
511         }
512         return;
513     }
514     if (item != null && OS.SHELL32_MAJOR >= 5) {
515         if (visible) {
516             NOTIFYICONDATA iconData = OS.IsUnicode ? (NOTIFYICONDATA) new NOTIFYICONDATAW () : new NOTIFYICONDATAA ();
517             TCHAR buffer1 = new TCHAR (0, text, true);
518             TCHAR buffer2 = new TCHAR (0, message, true);
519             if (OS.IsUnicode) {
520                 char [] szInfoTitle = ((NOTIFYICONDATAW) iconData).szInfoTitle;
521                 int length1 = Math.min (szInfoTitle.length - 1, buffer1.length ());
522                 System.arraycopy (buffer1.chars, 0, szInfoTitle, 0, length1);
523                 char [] szInfo = ((NOTIFYICONDATAW) iconData).szInfo;
524                 int length2 = Math.min (szInfo.length - 1, buffer2.length ());
525                 System.arraycopy (buffer2.chars, 0, szInfo, 0, length2);
526             } else {
527                 byte [] szInfoTitle = ((NOTIFYICONDATAA) iconData).szInfoTitle;
528                 int length = Math.min (szInfoTitle.length - 1, buffer1.length ());
529                 System.arraycopy (buffer1.bytes, 0, szInfoTitle, 0, length);
530                 byte [] szInfo = ((NOTIFYICONDATAA) iconData).szInfo;
531                 int length2 = Math.min (szInfo.length - 1, buffer2.length ());
532                 System.arraycopy (buffer2.bytes, 0, szInfo, 0, length2);
533             }
534             Display display = item.getDisplay ();
535             iconData.cbSize = NOTIFYICONDATA.sizeof;
536             iconData.uID = item.id;
537             iconData.hWnd = display.hwndMessage;
538             iconData.uFlags = OS.NIF_INFO;
539             if ((style & SWT.ICON_INFORMATION) != 0) iconData.dwInfoFlags = OS.NIIF_INFO;
540             if ((style & SWT.ICON_WARNING) != 0) iconData.dwInfoFlags = OS.NIIF_WARNING;
541             if ((style & SWT.ICON_ERROR) != 0) iconData.dwInfoFlags = OS.NIIF_ERROR;
542             sendEvent (SWT.Show);
543             this.visible = OS.Shell_NotifyIcon (OS.NIM_MODIFY, iconData);
544         } else {
545             //TODO - hide the tray item
546 }
547     }
548 }
549 }
550
Popular Tags