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.Window, 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.Window, 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.Window)
 119          */
 120         USER_ATTENTION_WINDOW
 121     }
 122 
 123     /**
 124      * Kinds of available window progress states.
 125      *
 126      * @see #setWindowProgressState(java.awt.Window, 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 AWTPermission("showWindowWithoutWarningBanner")} and an
 183      *  {@code AWTPermission("canProcessApplicationEvents")}
 184      *  permissions.
 185      */
 186     private void checkPermissions(){
 187         SecurityManager sm = System.getSecurityManager();
 188         if (sm != null) {
 189             sm.checkPermission(new AWTPermission(
 190                     "canProcessApplicationEvents"));
 191             sm.checkPermission(new AWTPermission(
 192                     "showWindowWithoutWarningBanner"));
 193         }
 194     }
 195     
 196     private Taskbar() {
 197         Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
 198         if (defaultToolkit instanceof SunToolkit) {
 199             peer = ((SunToolkit) defaultToolkit).createTaskbarPeer(this);
 200         }
 201     }
 202 
 203     /**
 204      * Returns the {@code Taskbar} instance of the current
 205      * taskbar context.  On some platforms the Taskbar API may not be
 206      * supported; use the {@link #isTaskbarSupported} method to
 207      * determine if the current taskbar is supported.
 208      * @return the Taskbar instance
 209      * @throws HeadlessException if {@link
 210      * GraphicsEnvironment#isHeadless()} returns {@code true}
 211      * @throws UnsupportedOperationException if this class is not
 212      * supported on the current platform
 213      * @see #isTaskbarSupported()
 214      * @see java.awt.GraphicsEnvironment#isHeadless
 215      */
 216     public static synchronized Taskbar getTaskbar(){
 217         if (GraphicsEnvironment.isHeadless()) throw new HeadlessException();
 218 
 219         if (!Taskbar.isTaskbarSupported()) {
 220             throw new UnsupportedOperationException("Taskbar API is not " +
 221                                                     "supported on the current platform");
 222         }
 223 
 224         sun.awt.AppContext context = sun.awt.AppContext.getAppContext();
 225         Taskbar taskbar = (Taskbar)context.get(Taskbar.class);
 226 
 227         if (taskbar == null) {
 228             taskbar = new Taskbar();
 229             context.put(Taskbar.class, taskbar);
 230         }
 231 
 232         return taskbar;
 233     }
 234 
 235     /**
 236      * Tests whether this class is supported on the current platform.
 237      * If it's supported, use {@link #getTaskbar()} to retrieve an
 238      * instance.
 239      *
 240      * @return {@code true} if this class is supported on the
 241      *         current platform; {@code false} otherwise
 242      * @see #getTaskbar()
 243      */
 244     public static boolean isTaskbarSupported(){
 245         Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
 246         if (defaultToolkit instanceof SunToolkit) {
 247             return ((SunToolkit)defaultToolkit).isTaskbarSupported();
 248         }
 249         return false;
 250     }
 251 
 252     /**
 253      * Requests user attention to this application.
 254      *
 255      * Depending on the platform, this may be visually indicated by a bouncing
 256      * or flashing icon in the task area. It may have no effect on an already active
 257      * application.
 258      *
 259      * On some platforms (e.g. Mac OS) this effect may disappear upon app activation
 260      * and cannot be dismissed by setting {@code enabled} to false.
 261      * Other platforms may require an additional call
 262      * {@link #requestUserAttention} to dismiss this request
 263      * with {@code enabled} parameter set to false.
 264      *
 265      * @param enabled disables this request if false
 266      * @param critical if this is an important request
 267      * @throws SecurityException if a security manager exists and it denies the
 268      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 269      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 270      * @throws UnsupportedOperationException if the current platform
 271      * does not support the {@link Taskbar.Feature#USER_ATTENTION} feature
 272      */
 273     public void requestUserAttention(final boolean enabled, final boolean critical) {
 274         checkPermissions();
 275         checkFeatureSupport(Feature.USER_ATTENTION);
 276         peer.requestUserAttention(enabled, critical);
 277     }
 278 
 279     /**
 280      * Requests user attention to the specified window until it is activated.
 281      *
 282      * On an already active window requesting attention does nothing.
 283      *
 284      * @param w window
 285      * @throws SecurityException if a security manager exists and it denies the
 286      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 287      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 288      * @throws UnsupportedOperationException if the current platform
 289      * does not support the {@link Taskbar.Feature#USER_ATTENTION_WINDOW} feature
 290      */
 291     public void requestWindowUserAttention(Window w) {
 292         checkPermissions();
 293         checkFeatureSupport(Feature.USER_ATTENTION_WINDOW);
 294         peer.requestWindowUserAttention(w);
 295     }
 296 
 297     /**
 298      * Attaches the contents of the provided PopupMenu to the application icon
 299      * in the task area.
 300      *
 301      * @param menu the PopupMenu to attach to this application
 302      * @throws SecurityException if a security manager exists and it denies the
 303      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 304      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 305      * @throws UnsupportedOperationException if the current platform
 306      * does not support the {@link Taskbar.Feature#MENU} feature
 307      */
 308     public void setMenu(final PopupMenu menu) {
 309         checkPermissions();
 310         checkFeatureSupport(Feature.MENU);
 311         peer.setMenu(menu);
 312     }
 313 
 314     /**
 315      * Gets PopupMenu used to add items to this application's icon in system task area.
 316      *
 317      * @return the PopupMenu
 318      * @throws SecurityException if a security manager exists and it denies the
 319      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 320      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 321      * @throws UnsupportedOperationException if the current platform
 322      * does not support the {@link Taskbar.Feature#MENU} feature
 323      */
 324     public PopupMenu getMenu() {
 325         checkPermissions();
 326         checkFeatureSupport(Feature.MENU);
 327         return peer.getMenu();
 328     }
 329 
 330     /**
 331      * Changes this application's icon to the provided image.
 332      *
 333      * @param image to change
 334      * @throws SecurityException if a security manager exists and it denies the
 335      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 336      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 337      * @throws UnsupportedOperationException if the current platform
 338      * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
 339      */
 340     public void setIconImage(final Image image) {
 341         checkPermissions();
 342         checkFeatureSupport(Feature.ICON_IMAGE);
 343         peer.setIconImage(image);
 344     }
 345 
 346     /**
 347      * Obtains an image of this application's icon.
 348      *
 349      * @return an image of this application's icon
 350      * @throws SecurityException if a security manager exists and it denies the
 351      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 352      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 353      * @throws UnsupportedOperationException if the current platform
 354      * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
 355      */
 356     public Image getIconImage() {
 357         checkPermissions();
 358         checkFeatureSupport(Feature.ICON_IMAGE);
 359         return peer.getIconImage();
 360     }
 361 
 362     /**
 363      * Affixes a small system-provided badge to this application's icon.
 364      * Usually a number.
 365      *
 366      * Some platforms do not support string values and accept only integer
 367      * values. In this case, pass an integer represented as a string as parameter.
 368      * This can be tested by {@code Feature.ICON_BADGE_TEXT} and
 369      * {@code Feature.ICON_BADGE_NUMBER}.
 370      *
 371      * Passing {@code null} as parameter hides the badge.
 372      * @param badge label to affix to the icon
 373      * @throws SecurityException if a security manager exists and it denies the
 374      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 375      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 376      * @throws UnsupportedOperationException if the current platform
 377      * does not support the {@link Taskbar.Feature#ICON_BADGE_NUMBER}
 378      * or {@link Taskbar.Feature#ICON_BADGE_TEXT} feature
 379      */
 380     public void setIconBadge(final String badge) {
 381         checkPermissions();
 382         checkFeatureSupport(Feature.ICON_BADGE_NUMBER);
 383         peer.setIconBadge(badge);
 384     }
 385 
 386     /**
 387      * Affixes a small badge to this application's icon in the task area
 388      * for the specified window.
 389      * It may be disabled by system settings.
 390      *
 391      * @param w window to update
 392      * @param badge image to affix to the icon
 393      * @throws SecurityException if a security manager exists and it denies the
 394      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 395      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 396      * @throws UnsupportedOperationException if the current platform
 397      * does not support the {@link Taskbar.Feature#ICON_BADGE_IMAGE_WINDOW} feature
 398      */
 399     public void setWindowIconBadge(Window w, final Image badge) {
 400         checkPermissions();
 401         checkFeatureSupport(Feature.ICON_BADGE_IMAGE_WINDOW);
 402         if (w != null) {
 403             peer.setWindowIconBadge(w, badge);
 404         }
 405     }
 406 
 407 
 408     /**
 409      * Affixes a small system-provided progress bar to this application's icon.
 410      *
 411      * @param value from 0 to 100, other to disable progress indication
 412      * @throws SecurityException if a security manager exists and it denies the
 413      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 414      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 415      * @throws UnsupportedOperationException if the current platform
 416      * does not support the {@link Taskbar.Feature#PROGRESS_VALUE} feature
 417      */
 418     public void setProgressValue(int value) {
 419         checkPermissions();
 420         checkFeatureSupport(Feature.PROGRESS_VALUE);
 421         peer.setProgressValue(value);
 422     }
 423 
 424     /**
 425      * Displays progress for specified window.
 426      *
 427      * @param w window to update
 428      * @param value from 0 to 100, other to disable progress indication
 429      * @throws SecurityException if a security manager exists and it denies the
 430      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 431      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 432      * @throws UnsupportedOperationException if the current platform
 433      * does not support the {@link Taskbar.Feature#PROGRESS_VALUE_WINDOW} feature
 434      */
 435     public void setWindowProgressValue(Window w, int value) {
 436         checkPermissions();
 437         checkFeatureSupport(Feature.PROGRESS_VALUE_WINDOW);
 438         if (w != null) {
 439             peer.setWindowProgressValue(w, value);
 440         }
 441     }
 442 
 443     /**
 444      * Sets a progress state for a specified window.
 445      *
 446      * @param w window
 447      * @param state to change to
 448      * @see State#OFF
 449      * @see State#NORMAL
 450      * @see State#PAUSED
 451      * @see State#INDETERMINATE
 452      * @see State#ERROR
 453      * @throws SecurityException if a security manager exists and it denies the
 454      * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
 455      * {@code RuntimePermission("canProcessApplicationEvents")} permission.
 456      * @throws UnsupportedOperationException if the current platform
 457      * does not support the {@link Taskbar.Feature#PROGRESS_STATE_WINDOW} feature
 458      */
 459     public void setWindowProgressState(Window w, State state) {
 460         checkPermissions();
 461         checkFeatureSupport(Feature.PROGRESS_STATE_WINDOW);
 462         if (w != null) {
 463             peer.setWindowProgressState(w, state);
 464         }
 465     }
 466 }