/*
 * File    : Actions.java
 * Created : 18-dec-2001 10:48
 * By      : fbusquets
 *
 * JClic - Authoring and playing system for educational activities
 *
 * Copyright (C) 2000 - 2005 Francesc Busquets & Departament
 * d'Educacio de la Generalitat de Catalunya
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program 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 for more details (see the LICENSE file).
 */

package edu.xtec.util;

import java.awt.Component;
import java.awt.Container;
import java.awt.event.ActionEvent;
import java.util.HashMap;
import java.util.Iterator;
import javax.swing.AbstractAction;
import javax.swing.Action;
import javax.swing.ActionMap;
import javax.swing.JComponent;

/**
 * Miscellaneous utilities for managing {@link javax.swing.Action} objects.
 *
 * EXAMPLES:
 *
 * Creation of a new action, with reference to a original key:
 *
 * <CODE>
 *  AbstractAction beginAction=new AbstractAction(DefaultEditorKit.beginAction){
 *    public void actionPerformed(ActionEvent e){
 *    // ...
 *  }
 * };
 * </CODE>
 *
 * Creation of a new action, with a new key:
 *
 * <CODE>
 * AbstractAction prevTargetAction=new AbstractAction("prev-target"){
 *  public void actionPerformed(ActionEvent e){
 *    // ...
 *  }
 * };
 * </CODE>
 *
 * Action that references an existing one:
 *
 * <CODE>
 * Action kitUpAction=null;
 * AbstractAction upAction=new AbstractAction(DefaultEditorKit.upAction){
 *  public void actionPerformed(ActionEvent e){
 *    if(kitUpAction!=null){
 *      // .... pre-action
 *    kitUpAction.actionPerformed(e);
 *      // .... post-action
 *    }
 *  }
 * };
 * </CODE>
 *
 * Actions mapping:
 *
 * <CODE>
 * protected void setActions(){
 *  // get existing actions:
 *  kitUpAction=getActionMap().get(DefaultEditorKit.upAction);
 *
 *  // actionKeys init:
 *  java.util.HashMap actionKeys=Actions.getActionKeys(this);
 *
 *  // build new ActionMap:
 *  ActionMap am=new ActionMap();
 *  am.setParent(getActionMap());
 *  setActionMap(am);
 *
 *  //Actions derived to trace (only for debug purposes):
 *  Actions.mapTraceAction(this, actionKeys, DefaultEditorKit.readOnlyAction);
 *  Actions.mapTraceAction(this, actionKeys, DefaultEditorKit.writableAction);
 *  Actions.mapTraceAction(this, actionKeys, "requestFocus");
 *  Actions.mapTraceAction(this, actionKeys, "toggle-componentOrientation");
 *
 *  //Actions to disable:
 *  Actions.mapNullAction(this, actionKeys, DefaultEditorKit.beepAction);
 *
 *  //New actions:
 *  Actions.mapAction(this, actionKeys, beginAction);
 *  Actions.mapAction(this, actionKeys, upAction);
 *
 *  //Original actions mapped to other methods:
 *  Actions.mapAction(this, actionKeys, beginAction, DefaultEditorKit.previousWordAction);
 *  Actions.mapAction(this, actionKeys, prevTargetAction, DefaultEditorKit.beginParagraphAction);
 *
 *  //Uncomment this line only if you want to hide all other actions:
 *  //am.setParent(null);
 *  //
 *
 *  // Assign keystrokes to a new action:
 *  getInputMap().put(KeyStroke.getKeyStroke(java.awt.event.KeyEvent.VK_TAB, java.awt.Event.SHIFT_MASK), prevTargetAction.getValue(Action.NAME));
 * }
 * </CODE>
 * @author Francesc Busquets (fbusquets@xtec.net)
 * @version 1.0.0.0
 */
public abstract class Actions {
    
    /**
     * Collects the keys of all the actions linked to a specific
     * {@link javax.swing.JComponent} and groups them in arrays by action names.
     * @param jc The JComponent with the actions linked to.
     * @return A HashMap formed by pairs of action names (key) and arrays of action keys
     * (value). Usually each action name has only one action key associated to it, and
     * the value of the pair is an object array with only one string, but this is not
     * an imperative: several actions can be associated to a single name.
     */
    public static HashMap getActionKeys(JComponent jc){
        HashMap result=new HashMap();
        ActionMap am=jc.getActionMap();
        Object[] amKeys=am.allKeys();
        for(int i=0; i<amKeys.length; i++){
            Action act=am.get(amKeys[i]);
            Object o=act.getValue(Action.NAME);
            if(o==null)
                o="";
            String name=o.toString();
            Object[] keys=(Object[])result.get(name);
            if(keys==null)
                keys=new Object[]{amKeys[i]};
            else{
                Object[] k2=new Object[keys.length+1];
                int j=0;
                for(j=0; j<keys.length; j++)
                    k2[j]=keys[j];
                k2[j]=amKeys[i];
                keys=k2;
            }
            result.put(name, keys);
        }
        return result;
    }
    
    /**
     * This function is for debug purposes only. Prints out the
     * @param actionKeys
     * @param am
     */
    public static void dumpActionKeys(HashMap actionKeys, ActionMap am){
        Iterator itKeys=actionKeys.keySet().iterator();
        while(itKeys.hasNext()){
            Object key=itKeys.next();
            System.out.println(key+":");
            Object[] value=(Object[])actionKeys.get(key);
            for(int i=0; i<value.length; i++)
                System.out.println(" - "+value[i]+" >> "+am.get(value[i]));
        }
    }
    
    public static void mapAction(JComponent jc, HashMap actionKeys, Action act){
        if(actionKeys==null)
            actionKeys=getActionKeys(jc);
        ActionMap am=jc.getActionMap();
        Object name=act.getValue(Action.NAME);
        Object[] keys=(Object[])actionKeys.get(name);
        boolean replaced=false;
        if(keys!=null)
            for(int i=0; i<keys.length; i++){
                am.put(keys[i], act);
                if(keys[i].equals(name))
                    replaced=true;
            }
        if(!replaced)
            am.put(name, act);
    }
    
    public static void mapAction(JComponent jc, HashMap actionKeys, Action act, Object key){
        if(actionKeys==null)
            actionKeys=getActionKeys(jc);
        ActionMap am=jc.getActionMap();
        Object[] keys=(Object[])actionKeys.get(key);
        boolean replaced=false;
        if(keys!=null)
            for(int i=0; i<keys.length; i++){
                am.put(keys[i], act);
                if(keys[i].equals(key))
                    replaced=true;
            }
        if(!replaced)
            am.put(key, act);
    }
    
    public static class NullAction extends AbstractAction{
        public NullAction(String name){
            super(name);
        }
        public void actionPerformed(ActionEvent e){
            // do nothing
        }
    }
    
    public static void mapNullAction(JComponent jc, HashMap actionKeys, String s){
        mapAction(jc, actionKeys, new edu.xtec.util.Actions.NullAction(s));
    }
    
    public static class TraceAction extends AbstractAction{
        Action bkAction=null;
        Object bkKey=null;
        public TraceAction(Action act, Object key){
            super((String)(key instanceof String ? key:""));
            bkAction=act;
            bkKey=key;
        }
        public void actionPerformed(ActionEvent e){
            System.out.println("TRACE: "+(bkAction!=null ? bkAction.getValue(Action.NAME):"")+" "+bkKey);
            if(bkAction!=null)
                bkAction.actionPerformed(e);
        }
    }
    
    public static void mapTraceAction(JComponent jc, HashMap actionKeys, String s){
        mapAction(jc, actionKeys, new edu.xtec.util.Actions.TraceAction(jc.getActionMap().get(s), s));
    }
    
    public static void traceHierarchy(Component cmp, int level){
        StringBuffer sb=new StringBuffer();
        for(int i=0; i<level; i++)
            sb.append(" ");
        sb.append(cmp);
        System.out.println(sb.substring(0));
        if(cmp instanceof Container){
            Container c=(Container)cmp;
            Component[] childs=c.getComponents();
            for(int i=0; i<childs.length; i++)
                traceHierarchy(childs[i], level+1);
        }
    }
}