1 /*

     2  * CDDL HEADER START

     3  *

     4  * The contents of this file are subject to the terms of the

     5  * Common Development and Distribution License (the "License").

     6  * You may not use this file except in compliance with the License.

     7  *

     8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

     9  * or http://www.opensolaris.org/os/licensing.

    10  * See the License for the specific language governing permissions

    11  * and limitations under the License.

    12  *

    13  * When distributing Covered Code, include this CDDL HEADER in each

    14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.

    15  * If applicable, add the following below this CDDL HEADER, with the

    16  * fields enclosed by brackets "[]" replaced with your own identifying

    17  * information: Portions Copyright [yyyy] [name of copyright owner]

    18  *

    19  * CDDL HEADER END

    20  */

    21 

    22 /*

    23  * Copyright (c) 2010, 2012, Oracle and/or its affiliates. All rights reserved.

    24  */

    25 

    26 package com.oracle.solaris.vp.panel.common.view;

    27 

    28 import javax.swing.Action;

    29 

    30 /**

    31  * The {@code BusyIndicator} displays a visual indication of work in progress

    32  * and blocks the user from interacting with the client.

    33  * <p>

    34  * A {@code BusyIndicator} should be shown whenever work is being done that must

    35  * preclude user interaction.  For brief tasks, however, the {@code

    36  * BusyIndicator} must be lightweight to avoid a "flicker" effect resulting from

    37  * quickly showing and hiding visual elements.

    38  * <p>

    39  * For this reason, the {@code BusyIndicator} supports two stages:

    40  * <p>

    41  * <ol>

    42  *   <li>

    43  *     the initial stage, where the user is blocked from interacting with the

    44  *     UI

    45  *   </li>

    46  *   <li>

    47  *     the secondary stage, where a {@link #setMessage status message} and other

    48  *     optional components (such as a progress bar) are shown

    49  *   </li>

    50  * </ol>

    51  * <p>

    52  * The {@code BusyIndicator} transitions through these stages automatically.

    53  * The delay between them can be set using the {@link #setDelay} method.  It is

    54  * typically under 5 seconds, but can vary by implementation.

    55  * <p>

    56  * When {@link #setBusyIndicatorDisplayed hidden}, the {@code BusyIndicator}

    57  * will revert back to its default settings.

    58  */

    59 public interface BusyIndicator {

    60     //

    61     // BusyIndicator methods

    62     //

    63 

    64     /**

    65      * Gets any {@code Action}s to be presented to the user.

    66      */

    67     Action[] getActions();

    68 

    69     /**

    70      * Gets the delay (in milliseconds) to wait in the initial stage before

    71      * transitioning to the secondary stage.

    72      */

    73     int getDelay();

    74 

    75     /**

    76      * Gets a status message to display.

    77      *

    78      * @return	    the message to display, or {@code null} to display a default

    79      *		    message

    80      */

    81     String getMessage();

    82 

    83     /**

    84      * Returns a {@code boolean} indicating whether this {@code BusyIndicator}

    85      * is displayed.

    86      */

    87     boolean isBusyIndicatorDisplayed();

    88 

    89     /**

    90      * Sets any {@code Action}s to be presented to the user.

    91      */

    92     void setActions(Action... actions);

    93 

    94     /**

    95      * Sets the delay (in milliseconds) to wait in the initial stage before

    96      * transitioning to the secondary stage.

    97      */

    98     void setDelay(int delay);

    99 

   100     /**

   101      * Displays or hides this busy indicator.  If {@code displayed} is {@code

   102      * false}, all settings ({@link #setMessage message}, {@link #setDelay

   103      * delay}, {@link #getActions actions}, etc.) are reset to their defaults.

   104      *

   105      * @param	    displayed

   106      *		    whether to display/hide this {@code BusyIndicator}

   107      */

   108     void setBusyIndicatorDisplayed(boolean displayed);

   109 

   110     /**

   111      * Sets a status message to display.

   112      *

   113      * @param	    message

   114      *		    the message to display, or {@code null} to display a default

   115      *		    message

   116      */

   117     void setMessage(String message);

   118 }