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