1 /*
   2  * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt;
  27 
  28 import java.awt.peer.TaskbarPeer;
  29 import sun.awt.SunToolkit;
  30 
  31 /**
  32  * The {@code Taskbar} class allows a Java application to interact with
  33  * the system task area (taskbar, Dock, etc.).
  34  *
  35  * <p>
  36  * There are a variety of interactions depending on the current platform such as
  37  * displaying progress of some task, appending user-specified menu to the application
  38  * icon context menu, etc.
  39  *
  40  * @implNote Linux support is currently limited to Unity. However to make these
  41  * features work on Unity, the app should be run from a .desktop file with
  42  * specified {@code java.desktop.appName} system property set to this .desktop
  43  * file name:
  44  * {@code Exec=java -Djava.desktop.appName=MyApp.desktop -jar /path/to/myapp.jar}
  45  * see <a href="https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles">
  46  * https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles</a>
  47  *
  48  * @since 9
  49  */
  50 
  51 public class Taskbar {
  52 
  53     /**
  54      * List of provided features. Each platform supports a different
  55      * set of features.  You may use the {@link Taskbar#isSupported}
  56      * method to determine if the given feature is supported by the
  57      * current platform.
  58      */
  59     public static enum Feature {
  60 
  61         /**
  62          * Represents a textual icon badge feature.
  63          * @see #setIconBadge(java.lang.String)
  64          */
  65         ICON_BADGE_TEXT,
  66 
  67         /**
  68          * Represents a numerical icon badge feature.
  69          * @see #setIconBadge(java.lang.String)
  70          */
  71         ICON_BADGE_NUMBER,
  72 
  73         /**
  74          * Represents a graphical icon badge feature for a window.
  75          * @see #setWindowIconBadge(java.awt.Window, java.awt.Image)
  76          */
  77         ICON_BADGE_IMAGE_WINDOW,
  78 
  79         /**
  80          * Represents an icon feature.
  81          * @see #setIconImage(java.awt.Image)
  82          */
  83         ICON_IMAGE,
  84 
  85         /**
  86          * Represents a menu feature.
  87          * @see #setMenu(java.awt.PopupMenu)
  88          * @see #getMenu()
  89          */
  90         MENU,
  91 
  92         /**
  93          * Represents a progress state feature for a specified window.
  94          * @see #setWindowProgressState(java.awt.Frame, State)
  95          */
  96         PROGRESS_STATE_WINDOW,
  97 
  98         /**
  99          * Represents a progress value feature.
 100          * @see #setProgressValue(int)
 101          */
 102         PROGRESS_VALUE,
 103 
 104         /**
 105          * Represents a progress value feature for a specified window.
 106          * @see #setWindowProgressValue(java.awt.Frame, int)
 107          */
 108         PROGRESS_VALUE_WINDOW,
 109 
 110         /**
 111          * Represents a user attention request feature.
 112          * @see #requestUserAttention(boolean, boolean)
 113          */
 114         USER_ATTENTION,
 115 
 116         /**
 117          * Represents a user attention request feature for a specified window.
 118          * @see #requestWindowUserAttention(java.awt.Frame)
 119          */
 120         USER_ATTENTION_WINDOW
 121     }
 122 
 123     /**
 124      * Kinds of available window progress states.
 125      *
 126      * @see #setWindowProgressState(java.awt.Frame, java.awt.Taskbar.State)
 127      */
 128     public static enum State {
 129         /**
 130          * Stops displaying the progress.
 131          */
 132         OFF,
 133         /**
 134          * The progress indicator displays with normal color and determinate
 135          * mode.
 136          */
 137         NORMAL,
 138         /**
 139          * Shows progress as paused, progress can be resumed by the user.
 140          * Switches to the determinate display.
 141          */
 142         PAUSED,
 143         /**
 144          * The progress indicator displays activity without specifying what
 145          * proportion of the progress is complete.
 146          */
 147         INDETERMINATE,
 148         /**
 149          * Shows that an error has occurred. Switches to the determinate
 150          * display.
 151          */
 152         ERROR
 153     }
 154 
 155     private TaskbarPeer peer;
 156 
 157     /**
 158      * Tests whether a {@code Feature} is supported on the current platform.
 159      * @param feature the specified {@link Feature}
 160      * @return true if the specified feature is supported on the current platform
 161      */
 162     public boolean isSupported(Feature feature) {
 163         return peer.isSupported(feature);
 164     }
 165 
 166     /**
 167      * Checks if the feature type is supported.
 168      *
 169      * @param featureType the action type in question
 170      * @throws UnsupportedOperationException if the specified action type is not
 171      *         supported on the current platform
 172      */
 173     private void checkFeatureSupport(Feature featureType){
 174         if (!isSupported(featureType)) {
 175             throw new UnsupportedOperationException("The " + featureType.name()
 176                     + " feature is not supported on the current platform!");
 177         }
 178     }
 179 
 180     /**
 181      *  Calls to the security manager's {@code checkPermission} method with
 182      *  an {@code RuntimePermission("canProcessApplicationEvents")} permissions.
 183      */
 184     private void checkEventsProcessingPermission(){
 185         SecurityManager sm = System.getSecurityManager();
 186         if (sm != null) {
 187             sm.checkPermission(new RuntimePermission(
 188                     "canProcessApplicationEvents"));
 189         }
 190     }
 191 
 192     private Taskbar() {
 193         Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
 194         if (defaultToolkit instanceof SunToolkit) {
 195             peer = ((SunToolkit) defaultToolkit).createTaskbarPeer(this);
 196         }
 197     }
 198 
 199     /**
 200      * Returns the {@code Taskbar} instance of the current
 201      * taskbar context.  On some platforms the Taskbar API may not be
 202      * supported; use the {@link #isTaskbarSupported} method to
 203      * determine if the current taskbar is supported.
 204      * @return the Taskbar instance
 205      * @throws HeadlessException if {@link
 206      * GraphicsEnvironment#isHeadless()} returns {@code true}
 207      * @throws UnsupportedOperationException if this class is not
 208      * supported on the current platform
 209      * @see #isTaskbarSupported()
 210      * @see java.awt.GraphicsEnvironment#isHeadless
 211      */
 212     public static synchronized Taskbar getTaskbar(){
 213         if (GraphicsEnvironment.isHeadless()) throw new HeadlessException();
 214 
 215         if (!Taskbar.isTaskbarSupported()) {
 216             throw new UnsupportedOperationException("Taskbar API is not " +
 217                                                     "supported on the current platform");
 218         }
 219 
 220         sun.awt.AppContext context = sun.awt.AppContext.getAppContext();
 221         Taskbar taskbar = (Taskbar)context.get(Taskbar.class);
 222 
 223         if (taskbar == null) {
 224             taskbar = new Taskbar();
 225             context.put(Taskbar.class, taskbar);
 226         }
 227 
 228         return taskbar;
 229     }
 230 
 231     /**
 232      * Tests whether this class is supported on the current platform.
 233      * If it's supported, use {@link #getTaskbar()} to retrieve an
 234      * instance.
 235      *
 236      * @return {@code true} if this class is supported on the
 237      *         current platform; {@code false} otherwise
 238      * @see #getTaskbar()
 239      */
 240     public static boolean isTaskbarSupported(){
 241         Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
 242         if (defaultToolkit instanceof SunToolkit) {
 243             return ((SunToolkit)defaultToolkit).isTaskbarSupported();
 244         }
 245         return false;
 246     }
 247 
 248     /**
 249      * Requests user attention to this application.
 250      *
 251      * Depending on the platform, this may be visually indicated by a bouncing
 252      * or flashing icon in the task area. It may have no effect on an already active
 253      * application.
 254      *
 255      * On some platforms (e.g. Mac OS) this effect may disappear upon app activation
 256      * and cannot be dismissed by setting {@code enabled} to false.
 257      * Other platforms may require an additional call
 258      * {@link #requestUserAttention} to dismiss this request
 259      * with {@code enabled} parameter set to false.
 260      *
 261      * @param enabled disables this request if false
 262      * @param critical if this is an important request
 263      * @throws SecurityException if a security manager exists and it denies the
 264      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 265      * @throws UnsupportedOperationException if the current platform
 266      * does not support the {@link Taskbar.Feature#USER_ATTENTION} feature
 267      */
 268     public void requestUserAttention(final boolean enabled, final boolean critical) {
 269         checkEventsProcessingPermission();
 270         checkFeatureSupport(Feature.USER_ATTENTION);
 271         peer.requestUserAttention(enabled, critical);
 272     }
 273 
 274     /**
 275      * Requests user attention to the specified window.
 276      *
 277      * Has no effect if this window is not visible in the task area.
 278      *
 279      * @param w window
 280      * @throws SecurityException if a security manager exists and it denies the
 281      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 282      * @throws UnsupportedOperationException if the current platform
 283      * does not support the {@link Taskbar.Feature#USER_ATTENTION_WINDOW} feature
 284      */
 285     public void requestWindowUserAttention(Frame w) {
 286         checkEventsProcessingPermission();
 287         checkFeatureSupport(Feature.USER_ATTENTION_WINDOW);
 288         peer.requestWindowUserAttention(w);
 289     }
 290 
 291     /**
 292      * Attaches the contents of the provided PopupMenu to the application icon
 293      * in the task area.
 294      *
 295      * @param menu the PopupMenu to attach to this application
 296      * @throws SecurityException if a security manager exists and it denies the
 297      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 298      * @throws UnsupportedOperationException if the current platform
 299      * does not support the {@link Taskbar.Feature#MENU} feature
 300      */
 301     public void setMenu(final PopupMenu menu) {
 302         checkEventsProcessingPermission();
 303         checkFeatureSupport(Feature.MENU);
 304         peer.setMenu(menu);
 305     }
 306 
 307     /**
 308      * Gets PopupMenu used to add items to this application's icon in system task area.
 309      *
 310      * @return the PopupMenu
 311      * @throws SecurityException if a security manager exists and it denies the
 312      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 313      * @throws UnsupportedOperationException if the current platform
 314      * does not support the {@link Taskbar.Feature#MENU} feature
 315      */
 316     public PopupMenu getMenu() {
 317         checkEventsProcessingPermission();
 318         checkFeatureSupport(Feature.MENU);
 319         return peer.getMenu();
 320     }
 321 
 322     /**
 323      * Changes this application's icon to the provided image.
 324      *
 325      * @param image to change
 326      * @throws SecurityException if a security manager exists and it denies the
 327      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 328      * @throws UnsupportedOperationException if the current platform
 329      * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
 330      */
 331     public void setIconImage(final Image image) {
 332         checkEventsProcessingPermission();
 333         checkFeatureSupport(Feature.ICON_IMAGE);
 334         peer.setIconImage(image);
 335     }
 336 
 337     /**
 338      * Obtains an image of this application's icon.
 339      *
 340      * @return an image of this application's icon
 341      * @throws SecurityException if a security manager exists and it denies the
 342      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 343      * @throws UnsupportedOperationException if the current platform
 344      * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
 345      */
 346     public Image getIconImage() {
 347         checkEventsProcessingPermission();
 348         checkFeatureSupport(Feature.ICON_IMAGE);
 349         return peer.getIconImage();
 350     }
 351 
 352     /**
 353      * Affixes a small system-provided badge to this application's icon.
 354      * Usually a number.
 355      *
 356      * Some platforms do not support string values and accept only integer
 357      * values. In this case, pass an integer represented as a string as parameter.
 358      * This can be tested by {@code Feature.ICON_BADGE_TEXT} and
 359      * {@code Feature.ICON_BADGE_NUMBER}.
 360      *
 361      * Passing {@code null} as parameter hides the badge.
 362      * @param badge label to affix to the icon
 363      * @throws SecurityException if a security manager exists and it denies the
 364      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 365      * @throws UnsupportedOperationException if the current platform
 366      * does not support the {@link Taskbar.Feature#ICON_BADGE_NUMBER}
 367      * or {@link Taskbar.Feature#ICON_BADGE_TEXT} feature
 368      */
 369     public void setIconBadge(final String badge) {
 370         checkEventsProcessingPermission();
 371         checkFeatureSupport(Feature.ICON_BADGE_NUMBER);
 372         peer.setIconBadge(badge);
 373     }
 374 
 375     /**
 376      * Affixes a small badge to this application's icon in the task area
 377      * for the specified window.
 378      * It may be disabled by system settings.
 379      *
 380      * Has no effect if this window is not visible in the task area.
 381      *
 382      * @param w window to update
 383      * @param badge image to affix to the icon
 384      * @throws SecurityException if a security manager exists and it denies the
 385      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 386      * @throws UnsupportedOperationException if the current platform
 387      * does not support the {@link Taskbar.Feature#ICON_BADGE_IMAGE_WINDOW} feature
 388      */
 389     public void setWindowIconBadge(Frame w, final Image badge) {
 390         checkEventsProcessingPermission();
 391         checkFeatureSupport(Feature.ICON_BADGE_IMAGE_WINDOW);
 392         if (w != null) {
 393             peer.setWindowIconBadge(w, badge);
 394         }
 395     }
 396 
 397 
 398     /**
 399      * Affixes a small system-provided progress bar to this application's icon.
 400      *
 401      * @param value from 0 to 100, other to disable progress indication
 402      * @throws SecurityException if a security manager exists and it denies the
 403      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 404      * @throws UnsupportedOperationException if the current platform
 405      * does not support the {@link Taskbar.Feature#PROGRESS_VALUE} feature
 406      */
 407     public void setProgressValue(int value) {
 408         checkEventsProcessingPermission();
 409         checkFeatureSupport(Feature.PROGRESS_VALUE);
 410         peer.setProgressValue(value);
 411     }
 412 
 413     /**
 414      * Displays a determinate progress bar in the task area for the specified
 415      * window.
 416      *
 417      * Has no effect if this window is not visible in the task area.
 418      * <br>
 419      * The visual behavior is platform and {@link State} dependent.
 420      * <br>
 421      * This call cancels the {@link State#INDETERMINATE INDETERMINATE} state
 422      * of the window.
 423      * <br>
 424      * Note that when multiple windows is grouped in the task area
 425      * the behavior is platform specific.
 426      *
 427      * @param w window to update
 428      * @param value from 0 to 100, other to switch to {@link State#OFF} state
 429      *              and disable progress indication
 430      * @see #setWindowProgressState(java.awt.Frame, State)
 431      * @throws SecurityException if a security manager exists and it denies the
 432      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 433      * @throws UnsupportedOperationException if the current platform
 434      * does not support the {@link Taskbar.Feature#PROGRESS_VALUE_WINDOW} feature
 435      */
 436     public void setWindowProgressValue(Frame w, int value) {
 437         checkEventsProcessingPermission();
 438         checkFeatureSupport(Feature.PROGRESS_VALUE_WINDOW);
 439         if (w != null) {
 440             peer.setWindowProgressValue(w, value);
 441         }
 442     }
 443 
 444     /**
 445      * Sets a progress state for a specified window.
 446      *
 447      * Has no effect if this window is not visible in the task area.
 448      * <br>
 449      * Each state displays a progress in a platform-dependent way.
 450      * <br>
 451      * Note than switching from {@link State#INDETERMINATE INDETERMINATE} state
 452      * to any of determinate states may reset value set by
 453      * {@link #setWindowProgressValue(java.awt.Window, int) setWindowProgressValue}
 454      *
 455      * @param w window
 456      * @param state to change to
 457      * @see State#OFF
 458      * @see State#NORMAL
 459      * @see State#PAUSED
 460      * @see State#ERROR
 461      * @see State#INDETERMINATE
 462      * @see #setWindowProgressValue(java.awt.Frame, int)
 463      * @throws SecurityException if a security manager exists and it denies the
 464      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 465      * @throws UnsupportedOperationException if the current platform
 466      * does not support the {@link Taskbar.Feature#PROGRESS_STATE_WINDOW} feature
 467      */
 468     public void setWindowProgressState(Frame w, State state) {
 469         checkEventsProcessingPermission();
 470         checkFeatureSupport(Feature.PROGRESS_STATE_WINDOW);
 471         if (w != null) {
 472             peer.setWindowProgressState(w, state);
 473         }
 474     }
 475 }