source: trunk/gli/src/org/greenstone/gatherer/Dictionary.java@ 4436

package org.greenstone.gatherer;
/**
 *#########################################################################
 *
 * A component of the Gatherer application, part of the Greenstone digital
 * library suite from the New Zealand Digital Library Project at the
 * University of Waikato, New Zealand.
 *
 * <BR><BR>
 *
 * Author: John Thompson, Greenstone Digital Library, University of Waikato
 *
 * <BR><BR>
 *
 * Copyright (C) 1999 New Zealand Digital Library Project
 *
 * <BR><BR>
 *
 * 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.
 *
 * <BR><BR>
 *
 * 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.
 *
 * <BR><BR>
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *########################################################################
 */
import java.util.*;
import javax.swing.*;
import javax.swing.plaf.*;
import javax.swing.text.*;
import javax.swing.tree.*;
import org.greenstone.gatherer.gui.border.TitledBorder;
import org.greenstone.gatherer.util.DictionaryTreeNode;
import org.greenstone.gatherer.util.MutableComboBoxEntry;
import org.greenstone.gatherer.util.ArrayTools;
import org.greenstone.gatherer.util.Utility;
/** Extends the ResourceBundle class to allow for the automatic insertion of  arguments. Note that the key names beginning Farg are reserved for formatting. <BR>
 * <BR>
 * Property files usable by this class have the Backus-Naur form: <BR>
 * <BR>
 * FileLine ::= Comment | Mapping <BR>
 * Comment  ::= '#' SString <BR>
 * Mapping  ::= NZString ':' SString ( Argument SString )* <BR>
 * NZString ::= ( Char | Int ) SString <BR>
 * Argument ::= '{' Int '}' <BR>
 * SString  ::= String . ['"','#',...] -> ['\"','\#',...] <BR>
 * <BR>
 * In order to add a new dictionary Locale, simply copy the existing dictionary.properties files, replace the values (Strings after the ':') with the new language specific ones being careful to maintain formatting and Gatherer placed arguments, then save the new dictionary as: <br>
 * <BR>
 * dictionary_<I>locale</I>.properties<BR>
 * <BR>
 * where locale is made of two two-letter codes seperated by an underscore. The first code is in lower-case and defines the language. The second is in upper-case and defines the country. For example the default dictionary could also correctly be called:
 * <BR>
 * dictionary_en_NZ.properties<BR>
 * @author John Thompson, Greenstone Digital Library, University of Waikato
 * @version 2.3
 */
public class Dictionary 
    extends HashMap {
    /** A String which more explicitly states the Locale of this dictionary. */
    public String language = null;
    /** A static reference to ourself. */
    static public Dictionary self;
    /** The font used when displaying various html text. */
    private FontUIResource font = null;
    /** A reference to remind us of the current locale. */
    private Locale locale = null;
    /** The ResourceBundle which contains the raw key-value mappings. Loaded from a file named "dictionary<I>locale</I>.properties*/
    private ResourceBundle dictionary = null;
    /**  Constructs the Dictionary class by first checking if a Locale has been set. If not the default locale is used, and a ResourceBundle is created. Finally a single important String, Language, is made available outside the class so a more read-able version of the Locale of this Dictionary is present.
     * @param locale The <strong>Locale</strong> used to load the desired dictionary resource bundle.
      */
    public Dictionary(Locale locale, FontUIResource font) {
    super();
    this.self = this;
    // Initialize.
    this.font = font;
    if(locale == null) {
        this.locale = Locale.getDefault();
    }
    else {
        this.locale = locale;
        Locale.setDefault(locale);
    }
    dictionary = ResourceBundle.getBundle(Utility.DICTIONARY, this.locale);
    // Now quickly read in language name.
    language = dictionary.getString("Language");
    }
    /** Change the currently loaded dictionary and update registered (ie dynamic) components as possible. */
    public void changeDictionary(Locale locale) {
    this.locale = locale;
    // Load new dictionary
    dictionary = ResourceBundle.getBundle(Utility.DICTIONARY, locale);
    // Refresh all registered component
    for(Iterator keys = keySet().iterator(); keys.hasNext(); ) {
        Object component = keys.next();
        String[] args = (String[]) get(component);
        if(component instanceof AbstractButton) {
        register((AbstractButton)component, args, true);
        }
        else if(component instanceof JComboBox) {
        register((JComboBox)component, args, true);
        }
        else if(component instanceof JDialog) {
        register((JDialog)component, args, true);
        }
        else if(component instanceof JFrame) {
        register((JFrame)component, args, true);
        }
        else if(component instanceof JLabel) {
        register((JLabel)component, args, true);
        }
        else if(component instanceof JTabbedPane) {
        register((JTabbedPane)component, args, true);
        }
        else if(component instanceof JTextComponent) {
        register((JTextComponent)component, args, true);
        }
        else if(component instanceof JTree) {
        register((JTree)component, args, true);
        }
        else if(component instanceof TitledBorder) {
        register((TitledBorder)component, args, true);
        }
        args = null;
        component = null;
    }
    }
    /** Remove the component from our registered components list. */
    public void deregister(Object component) {
    remove(component);
    }

    /** Overloaded to call get with both a key and an empty argument array.
      * @param key A <strong>String</strong> which is mapped to a initial String within the ResourceBundle.
      * @return A <strong>String</strong> which has been referenced by the key String and that either contains no argument fields, or has had the argument fields automatiically populated with formatting Strings of with argument String provided in the get call.
      */
    public String get(String key) {
    return get(key, (String[])null);
    }
    /** Convienence method with transforms the second string argument into a string array. */
    public String get(String key, String arg) {
    String[] args = new String[1];
    args[0] = arg;
    return get(key, args);
    }
    /** Used to retrieve a property value from the Locale specific ResourceBundle, based upon the key and arguments supplied. If the key cannot be found or if some other part of the call fails a default (English) error message is returned. <BR>
      * Here the get recieves a second argument which is an array of Strings used to populate argument fields, denoted {<I>n</I>}, within the value String returned. Note that argument numbers greater than or equal to 32 are automatically mapped to the formatting String named Farg<I>n</I>.
      * @param key A <strong>String</strong> which is mapped to a initial String within the ResourceBundle.
      * @param args A <strong>String[]</strong> used to populate argument fields within the complete String.
      * @return A <strong>String</strong> which has been referenced by the key String and that either contains no argument fields, or has had the argument fields automatiically populated with formatting Strings of with argument String provided in the get call.
      */
    public String get(String key, String args[]) {
    try {
        String initial = dictionary.getString(key);
                // If the string contains arguments we have to insert them.
        String complete = "";
                // While we still have initial string left.
        while(initial.length() > 0 && initial.indexOf('{') != -1 && initial.indexOf('}') != -1) {
        // Remove preamble
        int opening = initial.indexOf('{');
        int closing = initial.indexOf('}');
        complete = complete + initial.substring(0, opening);
        // Parse arg_num
        String arg_str = initial.substring(opening + 1, closing);
        int arg_num = Integer.parseInt(arg_str);
        if(closing + 1 < initial.length()) {
            initial = initial.substring(closing + 1);
        }
        else {
            initial = "";
        }
        // Insert argument
        if(args != null && 0 <= arg_num && arg_num < args.length) {
            complete = complete + args[arg_num];
        }
        else if(arg_num >= 32) {
            String f_subargs[] = new String[1];
            if(font != null) {
            f_subargs[0] = font.getFontName();
            }
            else {
            f_subargs[0] = "Arial";
            }
            complete = complete + get("Farg" + arg_num, f_subargs);
        }
        }
        return complete + initial;
    }
    catch (Exception e) {
        if(!key.endsWith("_Tooltip")) {
        Gatherer.println("Missing value for key: " + key);
        }
        return key;
    }
    }
    /** Retrieve the two letter code of the current language we are using, according to the stored locale.
      * @return A <strong>String</strong> containing the two letter ISO639 language code.
      */
    public String getLanguage() {
    return locale.getLanguage();
    }
    /** Register an abstract button component. */
    public void register(AbstractButton component, String[] args, boolean already_registered) {
    if(component != null) {
                // Determine the key
        String key = "";
        if(!already_registered) {
        key = component.getText();
        }
        else {
        key = args[args.length - 1];
        }
                // Update the component using the AWTEvent queue
        String value = get(key, args);
        String tooltip = get(key + "_Tooltip", (String[])null);
        ChangeTask task = new AbstractButtonChangeTask(component, key, value, tooltip);
        SwingUtilities.invokeLater(task);
                // Register as necessary
        if(!already_registered) {
        args = ArrayTools.add(args, key);
        put(component, args);
        }
    }
    }
    /** Register a combobox component. */
    public void register(JComboBox component, String[] args, boolean already_registered) {
    if(component != null) {
                // If not already registered then args will be null.
        if(!already_registered) {
        args = new String[component.getItemCount()];
        }
                // Retrieve the tooltip. The key is mostly derived from the comboboxes name.
        String key = component.getName();
        String tooltip = get(key + "_Tooltip", (String[])null);
        ChangeTask task = new JComboBoxChangeTask(component, key, -1, tooltip);
        SwingUtilities.invokeLater(task);
                // Iterate through the combobox, updating values and recording the original key of each item in args.
        for(int i = 0; i < args.length; i++) {
        if(args[i] == null) {
            args[i] = component.getItemAt(i).toString();
        }
        String value = get(args[i], (String[])null);
        task = new JComboBoxChangeTask(component, key, i, value);
        SwingUtilities.invokeLater(task);
        }
                // Register if necessary
        if(!already_registered) {
        put(component, args);
        }
    }
    }
    /** Register a dialog component. */
    public void register(JDialog component, String[] args, boolean already_registered) {
    if(component != null) {
                // Determine the key
        String key = "";
        if(!already_registered) {
        key = component.getTitle();
        }
        else {
        key = args[args.length - 1];
        }
                // Update the component using the AWTEvent queue
        String value = get(key, args);
        ChangeTask task = new JDialogChangeTask(component, key, value);
        SwingUtilities.invokeLater(task);
                // Register as necessary
        if(!already_registered) {
        args = ArrayTools.add(args, key);
        put(component, args);
        }
    }
    }
    /** Register a frame component. */
    public void register(JFrame component, String[] args, boolean already_registered) {
    if(component != null) {
                // Determine the key
        String key = "";
        if(!already_registered) {
        key = component.getTitle();
        }
        else {
        key = args[args.length - 1];
        }
                // Update the component using the AWTEvent queue
        String value = get(key, args);
        ChangeTask task = new JFrameChangeTask(component, key, value);
        SwingUtilities.invokeLater(task);
                // Register as necessary
        if(!already_registered) {
        args = ArrayTools.add(args, key);
        put(component, args);
        }
    }
    }
    /** Register a label component. */
    public void register(JLabel component, String[] args, boolean already_registered) {
    if(component != null) {
                // Determine the key
        String key = "";
        if(!already_registered) {
        key = component.getText();
        }
        else {
        key = args[args.length - 1];
        }
                // Update the component using the AWTEvent queue
        String value = get(key, args);
        ChangeTask task = new JLabelChangeTask(component, key, value);
        SwingUtilities.invokeLater(task);
                // Register as necessary
        if(!already_registered) {
        args = ArrayTools.add(args, key);
        put(component, args);
        }
    }
    }
    /** Register a tab pane component. */
    public void register(JTabbedPane component, String[] args, boolean already_registered) {
    if(component != null) {
                // If not already registered then args will be null.
        if(!already_registered) {
        args = new String[component.getTabCount()];
        }
                // Iterate through the tabbed panes tabs, updating values and recording the original key of each item in args.
        for(int i = 0; i < args.length; i++) {
        if(args[i] == null) {
            args[i] = component.getTitleAt(i);
        }
        String value = get(args[i], (String[])null);
        String tooltip = get(args[i] + "_Tooltip", (String[])null);
        ChangeTask task = new JTabbedPaneChangeTask(component, args[i], i, value, tooltip);
        SwingUtilities.invokeLater(task);
        }
                // Register if necessary
        if(!already_registered) {
        put(component, args);
        }
    }
    }
    /** Register a text component. */
    public void register(JTextComponent component, String[] args, boolean already_registered) {
    if(component != null) {
                // Determine the key
        String key = "";
        if(!already_registered) {
        key = component.getText();
        }
        else {
        key = args[args.length - 1];
        }
                // Update the component using the AWTEvent queue
        String value = get(key, args);
        String tooltip = get(key + "_Tooltip", (String[])null);
        ChangeTask task = new JTextComponentChangeTask(component, key, value, tooltip);
        SwingUtilities.invokeLater(task);
                // Register as necessary
        if(!already_registered) {
        args = ArrayTools.add(args, key);
        put(component, args);
        }
    }
    }
    /** Register a tree component. */
    public void register(JTree component, String[] args, boolean already_registered) {
    if(component != null) {
                // Retrieve the tooltip using the components name
        String key = component.getName();
        String tooltip = get(key + "_Tooltip", (String[])null);
        ChangeTask task = new JTreeChangeTask(component, key, tooltip);
        SwingUtilities.invokeLater(task);
                // A tree can never be previously registered. In otherwords the keys are harvested each time. Thus for a tree to remain consistant its up to the implementer to implement DictionaryTreeNode for the tree nodes!
        ArrayList nodes = new ArrayList();
        nodes.add(component.getModel().getRoot());
        while(nodes.size() > 0) {
        DictionaryTreeNode node = (DictionaryTreeNode) nodes.remove(0);
        // Update
        String value = get(node.getKey(), (String[])null);
        task = new JTreeChangeTask(component, node.getKey(), node, value);
        SwingUtilities.invokeLater(task);
        // Add children to nodes
        for(int i = 0; i < node.getChildCount(); i++) {
            nodes.add(node.getChildAt(i));
        }
        }
    }
    }
    /** Register a titled border component. */
    public void register(TitledBorder component, String[] args, boolean already_registered) {
    if(component != null) {
                // Determine the key
        String key = "";
        if(!already_registered) {
        key = component.getTitle();
        }
        else {
        key = args[args.length - 1];
        }
                // Update the component using the AWTEvent queue
        String value = get(key, args);
        ChangeTask task = new TitledBorderChangeTask(component, key, value);
        SwingUtilities.invokeLater(task);
                // Register as necessary
        if(!already_registered) {
        args = ArrayTools.add(args, key);
        put(component, args);
        }
    }
    }
    /** A get method called internally by components that have been previously been registered, which means that arg[index] is the original key value. Index is usually the last entry in the array, however this is not true for comboboxes, tabbed panes and trees. */
    private String get(String[] args, int index) {
    return get(args[index], args);
    }

    private abstract class ChangeTask
    implements Runnable {
    protected String key;
    protected String value;
    public ChangeTask(String key, String value) {
        this.key = key;
        this.value = value;
    }
    public void run() {
    }
    }
    /** Update the text and tooltip for this button. */
    private class AbstractButtonChangeTask
    extends ChangeTask {
    private AbstractButton component;
    private String tooltip;
    public AbstractButtonChangeTask(AbstractButton component, String key, String value, String tooltip) {
        super(key, value);
        this.component = component;
        this.tooltip = tooltip;
    }
    public void run() {
        component.setText(value);
        if(!tooltip.equals(key+"_Tooltip")) {
        component.setToolTipText(tooltip);
        }
        else {
        component.setToolTipText(null);
        }
    }
    }
    /** Update the text associated with a combobox. If the index used is -1 then we are setting the tooltip for this combobox. */
    private class JComboBoxChangeTask
    extends ChangeTask {
    private int index;
    private JComboBox component;
    public JComboBoxChangeTask(JComboBox component, String key, int index, String value) {
        super(key, value);
        this.component = component;
        this.index = index;
    }
    public void run() {
        if(index != -1) {
        try {
            MutableComboBoxEntry entry = (MutableComboBoxEntry)component.getItemAt(index);
            entry.setText(value);
        }
        catch (Exception error) {
        }
        }
        else {
        if(!value.equals(key+"_Tooltip")) {
            component.setToolTipText(value);
        }
        else {
            component.setToolTipText(null);
        }
        }
    }
    }
    /** Update the title of this dialog. */
    private class JDialogChangeTask
    extends ChangeTask {
    private JDialog component;
    public JDialogChangeTask(JDialog component, String key, String value) {
        super(key, value);
        this.component = component;
    }
    public void run() {
        component.setTitle(value);
    }
    }
    /** Update the title of this frame. */
    private class JFrameChangeTask
    extends ChangeTask {
    private JFrame component;
    public JFrameChangeTask(JFrame component, String key, String value) {
        super(key, value);
        this.component = component;
    }
    public void run() {
        component.setTitle(value);
    }
    }
    /** Update the text of this label. */
    private class JLabelChangeTask
    extends ChangeTask {
    private JLabel component;
    public JLabelChangeTask(JLabel component, String key, String value) {
        super(key, value);
        this.component = component;
    }
    public void run() {
        component.setText(value);
    }
    }
    /** Updates a tabbed panes tab title and tooltip. */
    private class JTabbedPaneChangeTask
    extends ChangeTask {
    private int index;
    private JTabbedPane component;
    private String tooltip;
    public JTabbedPaneChangeTask(JTabbedPane component, String key, int index, String value, String tooltip) {
        super(key, value);
        this.component = component;
        this.index = index;
        this.tooltip = tooltip;
    }
    public void run() {
        component.setTitleAt(index, value);
        if(!tooltip.equals(key+"_Tooltip")) {
        component.setToolTipTextAt(index, tooltip);
        }
        else {
        component.setToolTipTextAt(index, null);
        }
    }
    }
    /** Update the text and tooltip of this text component. */
    private class JTextComponentChangeTask
    extends ChangeTask {
    private JTextComponent component;
    private String tooltip;
    public JTextComponentChangeTask(JTextComponent component, String key, String value, String tooltip) {
        super(key, value);
        this.component = component;
        this.tooltip = tooltip;
    }
    public void run() {
        component.setText(value);
        if(!tooltip.equals(key+"_Tooltip")) {
        component.setToolTipText(tooltip);
        }
        else {
        component.setToolTipText(null);
        }
    }
    }
    /** Update the tooltip of a tree and its tree node's labels. Shouldn't really ever be used on a dynamic tree, but is quite useful for a 'contents' tree type control. */
    private class JTreeChangeTask
    extends ChangeTask {
    private DictionaryTreeNode node;
    private JTree component;
    public JTreeChangeTask(JTree component, String key, String value) {
        super(key, value);
        this.component = component;
    }
    public JTreeChangeTask(JTree component, String key, DictionaryTreeNode node, String value) {
        super(key, value);
        this.component = component;
        this.node = node;
    }
    public void run() {
        if(value != null) {
        node.setText(value);
        ((DefaultTreeModel)component.getModel()).nodeChanged((TreeNode)node);
        }
                // Set the tool tip
        else {
        if(!value.equals(key+"_Tooltip")) {
            component.setToolTipText(value);
        }
        else {
            component.setToolTipText(null);
        }
        }
    }
    }
    /** Update the title of this titled border. */
    private class TitledBorderChangeTask
    extends ChangeTask {
    private TitledBorder component;
    public TitledBorderChangeTask(TitledBorder component, String key, String value) {
        super(key, value);
        this.component = component;
    }
    public void run() {
        component.setTitle(value);
        component.getParent().repaint();
    }
    }
}