/*
 *                 Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 *
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2004 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.netbeans.core.output2;

import org.openide.windows.InputOutput;

import javax.swing.*;

/**
 * An extension to the InputOutput interface allowing toolbar actions to be provided.
 */
public interface CallbackInputOutput extends InputOutput {
    /**
     * Provide actions which may be displayed on the toolbar in the output window.
     * This method has the following constraints:
     * 

     * 
It is expected that it will be called once during the lifetime
     *     of a CallbackInputOutput, and may throw an exception if called more
     *     than once
     * 
The number of actions allowed is limited to 5.  Any more than that will throw an
     *     IllegalArgumentException
     * 
The actions must have icons retrievable from Action.getValue(Action.SMALL_ICON).
     *     This is enforced
     * 
To avoid memory leaks and other problems, the actions passed here will be wrapped
     *     an a proxy action that weakly references the original.  The caller must retain a strong
     *     reference to the passed actions until the stream has been closed or they are no longer
     *     needed for other reasons.  If a strong reference is not held, the actions may become
     *     disabled prematurely.
     * 
     * 

     * The typical use case for this method is to provide a "stop" action; other uses
     * are, of course, possible.
     * 

     * If a passed action has a name and accelerator key, it may also be included in the output
     * view's popup menu and bound as a keyboard action.
     *
     * @param a An array of actions with icons
     * @throws IllegalArgumentException If more than 5 actions are in the array, or any of the actions have
     *         null arguments
     * @throws IllegalStateException If called repeatedly
     * @throws NullPointerException If any of the actions are null
     */
    public void setToolbarActions (Action[] a);
}