/*
 * Copyright (c) 2008-2013 Haulmont. All rights reserved.
 * Use is subject to license terms, see http://www.cuba-platform.com/license for details.
 */
package com.haulmont.cuba.gui.components;

import java.beans.PropertyChangeListener;
import java.util.Collection;

/**
 * A named listener to UI events
 *
 * @author abramov
 * @version $Id$
 */
public interface Action {

    public static final String PROP_CAPTION = "caption";
    public static final String PROP_ICON = "icon";
    public static final String PROP_ENABLED = "enabled";
    public static final String PROP_VISIBLE = "visible";

    /**
     * @return  action's identifier
     */
    String getId();

    /**
     * @return  action's localized caption
     */
    String getCaption();
    void setCaption(String caption);

    /**
     *
     * @return action's shortcut
     */
    KeyCombination getShortcut();
    void setShortcut(KeyCombination shortcut);

    /**
     * Set shortcut from string representation.
     *
     * @param shortcut string of type "Modifiers-Key", e.g. "Alt-N". Case-insensitive.
     */
    void setShortcut(String shortcut);

    /**
     * @return  action's icon
     */
    String getIcon();
    void setIcon(String icon);

    /**
     * @return  whether the action is currently enabled
     */
    boolean isEnabled();
    void setEnabled(boolean enabled);

    /**
     * @return  whether the action is currently visible
     */
    boolean isVisible();
    void setVisible(boolean visible);

    /**
     * Refresh enabled, visible, caption, icon, etc properties <br/>
     * Used in components and system actions for activation permissions
     */
    void refreshState();

    /**
     * @return  a single component owning the action. If there are several owners, first will be returned.
     */
    Component.ActionOwner getOwner();

    /**
     * @return the collection of owners
     */
    Collection<Component.ActionOwner> getOwners();

    /**
     * Add an owner component.
     * @param actionOwner   owner component
     */
    void addOwner(Component.ActionOwner actionOwner);

    /**
     * Remove an owner component.
     * @param actionOwner   owner component
     */
    void removeOwner(Component.ActionOwner actionOwner);

    /**
     * This method is invoked by owning component.
     * @param component invoking component
     */
    void actionPerform(Component component);

    /**
     * Adds a listener to be notified about Enabled, Caption or Icon property changes.
     *
     * @param listener  a <code>PropertyChangeListener</code> object
     */
    public void addPropertyChangeListener(PropertyChangeListener listener);

    /**
     * Removes a listener.
     *
     * @param listener  a <code>PropertyChangeListener</code> object
     * @see #addPropertyChangeListener
     */
    public void removePropertyChangeListener(PropertyChangeListener listener);
}
@@ -1585,16 +1585,59 @@
 Refresh 
+internal state of the action to initialize 
 enabled,
@@ -1664,16 +1664,17 @@
 con, etc
+.
  propert
@@ -1681,74 +1681,355 @@
 ies 
-%3Cbr/%3E%0D%0A     * Used in components and system actions for activation
+depending%0D%0A     * on programmatically set values and user permissions set at runtime.%0D%0A     *%0D%0A     * %3Cp/%3E For example, this method is called by visual components holding actions when they are connected to%0D%0A     * datasources. At this moment the action can find out what entity it is connected to and change its state%0D%0A     * according to the user
  per
@@ -2036,16 +2036,17 @@
 missions
+.
 %0D%0A     *

Fix permission initialization for Standard list actions (added some explanation in JavaDoc) #PL-2657