/*
 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.awt;

import sun.awt.SunToolkit;

/**
 * The {@code Taskbar} class allows a Java application to interact with 
 * system task area(Taskbar, Dock, etc.).
 * 
 * There are a variety of interactions depending on running platform such as
 * displaying progress of some task, appending user specified menu to application
 * icon context menu, etc.
 * 
 * Linux support is limited to Unity, however to make this features work on Unity
 * the app should be run from a .desktop file with specified java.desktop.appName
 * system property set to this .desktop file name:
 * Exec=java -Djava.desktop.appName=MyApp.desktop -jar /path/to/myapp.jar
 * see https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles
 */

public class Taskbar {
    
    /**
     * List of provided features.
     */
    public static enum Feature {

        /**
         * @see #setIconBadge(java.lang.String) 
         */
        ICON_BADGE_TEXT,

        /**
         * @see #setIconBadge(java.lang.String) 
         */
        ICON_BADGE_NUMBER,

        /**
         * @see #setWindowIconBadge(java.awt.Window, java.awt.Image) 
         */
        ICON_BADGE_IMAGE_WINDOW,

        /**
         * @see #setIconImage(java.awt.Image) 
         */
        ICON_IMAGE,

        /**
         * @see #setMenu(java.awt.PopupMenu) 
         * @see #getMenu() 
         */
        MENU,

        /**
         * @see #setWindowProgressState(java.awt.Window, int) 
         */
        PROGRESS_STATE_WINDOW,

        /**
         * @see #setProgressValue(int) 
         */
        PROGRESS_VALUE,

        /**
         * @see #setWindowProgressValue(java.awt.Window, int)  
         */
        PROGRESS_VALUE_WINDOW,

        /**
         * @see #requestUserAttention(boolean, boolean) 
         */
        USER_ATTENTION,

        /**
         * @see #requestWindowUserAttention(java.awt.Window) 
         */
        USER_ATTENTION_WINDOW
    }

    /**
     * Stops displaying the progress.
     */
    public static final int STATE_OFF = 0x0;

    /**
     * The progress indicator displays with normal color and determinate mode.
     */
    public static final int STATE_NORMAL = 0x1;

    /**
     * Shows progress as paused, progress can be resumed by user.
     * Switches to the determinate display.
     */
    public static final int STATE_PAUSED = 0x2;

    /**
     * The progress indicator displays activity without specifying what 
     * proportion of the progress is complete.
     */
    public static final int STATE_INDETERMINATE = 0x3;

    /**
     * Shows that an error has occurred.
     * Switches to the determinate display.
     */
    public static final int STATE_ERROR = 0x4;
            
    private TaskbarPeer peer;
    
    /**
     * Tests whether a {@code Feature} is supported on the current platform.
     * @param feature the specified {@link Feature}
     * @return true if the specified feature is supported on the current platform
     */
    public boolean isSupported(Feature feature) {
        return peer.isSupported(feature);
    }

    /**
     * Checks if the feature type is supported.
     *
     * @param featureType the action type in question
     * @throws UnsupportedOperationException if the specified action type is not
     *         supported on the current platform
     */
    private void checkFeatureSupport(Feature featureType){
        if (!isSupported(featureType)) {
            throw new UnsupportedOperationException("The " + featureType.name()
                    + " feature is not supported on the current platform!");
        }
    }
    private Taskbar() {
        Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
        if (defaultToolkit instanceof SunToolkit) {
            peer = ((SunToolkit) defaultToolkit).createTaskbarPeer(this);
        }
    }
    
    /**
     * Returns the <code>Taskbar</code> instance of the current
     * browser context.  On some platforms the Taskbar API may not be
     * supported; use the {@link #isTaskbarSupported} method to
     * determine if the current taskbar is supported.
     * @return the Taskbar instance of the current browser context
     * @throws HeadlessException if {@link
     * GraphicsEnvironment#isHeadless()} returns {@code true}
     * @throws UnsupportedOperationException if this class is not
     * supported on the current platform
     * @see #isTaskbarSupported()
     * @see java.awt.GraphicsEnvironment#isHeadless
     */
    public static synchronized Taskbar getTaskbar(){
        if (GraphicsEnvironment.isHeadless()) throw new HeadlessException();

        if (!Taskbar.isTaskbarSupported()) {
            throw new UnsupportedOperationException("Taskbar API is not " +
                                                    "supported on the current platform");
        }

        sun.awt.AppContext context = sun.awt.AppContext.getAppContext();
        Taskbar taskbar = (Taskbar)context.get(Taskbar.class);

        if (taskbar == null) {
            taskbar = new Taskbar();
            context.put(Taskbar.class, taskbar);
        }

        return taskbar;
    }
    
    /**
     * Tests whether this class is supported on the current platform.
     * If it's supported, use {@link #getTaskbar()} to retrieve an
     * instance.
     *
     * @return <code>true</code> if this class is supported on the
     *         current platform; <code>false</code> otherwise
     * @see #getTaskbar()
     */
    public static boolean isTaskbarSupported(){
        Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
        if (defaultToolkit instanceof SunToolkit) {
            return ((SunToolkit)defaultToolkit).isTaskbarSupported();
        }
        return false;
    }

    /**
     * Requests user attention to this application.
     * 
     * Depending on platform, this may be visually indicated by bouncing 
     * or flashing icon in task area. It may has no effect on an already active
     * application.
     * 
     * On some platforms(e.g. Mac OS) this effect may disappear upon app activation
     * and cannot be dismissed by setting {@code enabled} to false.
     * On other platforms may require additional call to 
     * {@link #requestUserAttention} to dismiss this request
     * with {@code enabled} parameter set to false.
     * 
     * @param enabled disables this request if false
     * @param critical if this is an important request
     */
    public void requestUserAttention(final boolean enabled, final boolean critical) {
        checkFeatureSupport(Feature.USER_ATTENTION);
        peer.requestUserAttention(enabled, critical);
    }

    /**
     * Requests user attention to the specified window until it is activated.
     * 
     * On an already active window requesting attention does nothing.
     * 
     * @param w window
     */
    public void requestWindowUserAttention(Window w) {
        checkFeatureSupport(Feature.USER_ATTENTION_WINDOW);
        peer.requestWindowUserAttention(w);
    }

    /**
     * Attaches the contents of the provided PopupMenu to the application icon
     * in system task area.
     *
     * @param menu the PopupMenu to attach to this application
     */
    public void setMenu(final PopupMenu menu) {
        checkFeatureSupport(Feature.MENU);
        peer.setMenu(menu);
    }

    /**
     * Gets PopupMenu used to add items to this application's icon in system task area. 
     * 
     * @return the PopupMenu 
     */
    public PopupMenu getMenu() {
        checkFeatureSupport(Feature.MENU);
        return peer.getMenu();
    }

    /**
     * Changes this application's icon to the provided image.
     *
     * @param image to change
     */
    public void setIconImage(final Image image) {
        checkFeatureSupport(Feature.ICON_IMAGE);
        peer.setIconImage(image);
    }

    /**
     * Obtains an image of this application's icon.
     *
     * @return an image of this application's icon
     */
    public Image getIconImage() {
        checkFeatureSupport(Feature.ICON_IMAGE);
        return peer.getIconImage();
    }

    /**
     * Affixes a small system provided badge to this application's icon.
     * Usually a number. 
     * 
     * Some platforms does not support string values and accepts only integer
     * values. In this case pass an integer represented as string as a parameter.
     * This can be tested by {@code Feature.ICON_BADGE_STRING} and 
     * {@code Feature.ICON_BADGE_NUMBER}.
     * 
     * Passing {@code null} as parameter hides the badge. 
     * @param badge label to affix to the icon
     */
    public void setIconBadge(final String badge) {
        checkFeatureSupport(Feature.ICON_BADGE_NUMBER);
        peer.setIconBadge(badge);
    }

    /**
     * Affixes a small badge to this application's icon in task area
     * for the specified window.
     * It may be disabled by system settings.
     *
     * @param w window to update 
     * @param badge image to affix to the icon
     */
    public void setWindowIconBadge(Window w, final Image badge) {
        checkFeatureSupport(Feature.ICON_BADGE_IMAGE_WINDOW);
        if (w != null) {
            peer.setWindowIconBadge(w, badge);
        }
    }


    /**
     * Affixes a small system provided progress bar to this application's icon.
     *
     * @param value from 0 to 100, other to disable progress indication
     */
    public void setProgressValue(int value) {
        checkFeatureSupport(Feature.PROGRESS_VALUE);
        peer.setProgressValue(value);
    }

    /**
     * Displays progress for specified window.
     *
     * @param w window to update
     * @param value from 0 to 100, other to disable progress indication
     */
    public void setWindowProgressValue(Window w, int value) {
        checkFeatureSupport(Feature.PROGRESS_VALUE_WINDOW);
        if (w != null) {
            peer.setWindowProgressValue(w, value);
        }
    }

    /**
     * Sets a progress state for a specified window.
     *
     * @param w window
     * @param state to change to
     * @see #STATE_OFF
     * @see #STATE_NORMAL
     * @see #STATE_PAUSED
     * @see #STATE_INDETERMINATE
     * @see #STATE_ERROR
     */
    public void setWindowProgressState(Window w, int state) {
        checkFeatureSupport(Feature.PROGRESS_STATE_WINDOW);
        if (state < STATE_OFF && state > STATE_ERROR) {
            throw new IllegalArgumentException("Invalid state value");
        }
        if (w != null) {
            peer.setWindowProgressState(w, state);
        }
    }
    
    private native void initIDs();
    
}