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:
     * <ul>
     * <li>It is expected that it will be called <strong>once</strong> during the lifetime
     *     of a <code>CallbackInputOutput</code>, and may throw an exception if called more
     *     than once</li>
     * <li>The number of actions allowed is limited to 5.  Any more than that will throw an
     *     IllegalArgumentException</li>
     * <li>The actions must have icons retrievable from <code>Action.getValue(Action.SMALL_ICON)</code>.
     *     This is enforced</li>
     * <li>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.</li>
     * </ul>
     * <p>
     * The typical use case for this method is to provide a &quot;stop&quot; action; other uses
     * are, of course, possible.
     * <p>
     * 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);
}