source: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/QueryFormControl.java@ 26174

/**
 *#########################################################################
 * QueryFormControl.java - part of the demo-client for Greenstone 3, of the 
 * Greenstone digital library suite from the New Zealand Digital Library 
 * Project at the  * University of Waikato, New Zealand.
 * <BR><BR>
 * Copyright (C) 2008 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.
 *########################################################################
 */

package org.greenstone.gs3client;

import java.awt.Color;
import java.awt.FlowLayout;
import java.awt.GridBagLayout;
import java.awt.GridBagConstraints;
import java.util.HashMap;
import java.util.Vector;

import javax.swing.BorderFactory;
import javax.swing.JCheckBox;
import javax.swing.JComboBox;
import javax.swing.JComponent;
import javax.swing.JLabel;
import javax.swing.JList;
import javax.swing.JPanel;
import javax.swing.JTextField;
import javax.swing.border.Border;

import org.greenstone.gs3client.data.QueryFormData;
import org.greenstone.gs3client.data.QueryFormData.QueryFormParam;
import org.greenstone.gsdl3.util.GSXML;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;

/** 
 * Represents a control in a query form. This wrapper class is a subclass of 
 * QueryFormParam that presents its QueryFormParam details as an appropriate 
 * GUI item *with* label (based on the QueryFormParam's type) for display 
 * in its own JPanel.   
 * This wrapper class is a widget that knows to display this QueryFormParam -- 
 * and any child &lt;param&gt;s or &lt;option&gt;s -- in its own JPanel.
 * @author ak19
*/
class QueryFormControl extends QueryFormParam {
    /** the widget that's a visual representation of this QueryFormParam */
    protected JComponent ref;
    /* Width in units of this form control's component 
     * Width only used when calculating layout for type=MULTI */
    int width;  // 1 to 3 units: 1 for checkboxes, 2 for combos, 
                // 3 for lists and textboxes. 0 for everything else.
    
    /** Constructor that creates a QueryFormControl for a &lt;param&gt; element 
     * @param param - a &lt;param&gt; element in a Query Service's describe 
     * response XML message */
    public QueryFormControl(Element param) {
        super(param);
        
        // work out the widths (else it remains at 0)
        if(this.type.equals(GSXML.PARAM_TYPE_INTEGER)
                || this.type.equals(GSXML.PARAM_TYPE_BOOLEAN))
        {
            width = 1;
        } else if(this.type.equals(GSXML.PARAM_TYPE_ENUM_SINGLE)
                || this.type.equals(GSXML.PARAM_TYPE_ENUM_MULTI)) 
        {
            width = 2;
        } else if(this.type.equals(GSXML.PARAM_TYPE_STRING))
        {
            width = 3;
        } else { // all other types of controls have 0 width
            width = 0;
        }
    }   
    
    /** Constructor that creates a QueryFormControl for a &lt;param&gt; element 
     * inside a panel. 
     * @param param - a &lt;param&gt; element in a Query Service's describe 
     * response XML message 
     * @param parentPanel - the panel inside which this QueryFormControl is to 
     * display itself. */
    public QueryFormControl(Element param, JPanel parentPanel) {
        super(param);
        createWidget(param); // This will set this.ref 
                            // In type=multi case, ref is a panel)
        
        // The following if statements have to be done in this order 
        
        // For all other values of this.type:
        // Now, in both textfield and enum cases (but not the others that
        // haven't been dealt with yet like INVISIBLE, FILE, ENUM, etc),
        // add the newly created GUI obj (in ref) to the parentPanel.
        // And attach a label if instructed to do so.
        if(this.ref != null) {
            JPanel panel = new JPanel(new FlowLayout(FlowLayout.LEFT));
            panel.add(new JLabel(this.displayItem));
            panel.add(this.ref);
            parentPanel.add(panel);
        }
        
        // this.ref is still null for MultiPanel, until now when we create it:
        if(this.type.equals(GSXML.PARAM_TYPE_MULTI)) { 
            createMultiPanel(param, parentPanel);
            //width = -1;
        }
        
        // finally let's change the colours - as long as ref exists
        // (invisible QueryFormData have no ref Component, so check for 
        // null case)
        if(this.ref != null) {
            ColourCombo.changeColor(this.ref.getComponents());
            ColourCombo.changeColor(this.ref);
            ColourCombo.changeAncestorColor(this.ref);
        }
    }   
    
    /** Creates the appropriate form control for the &lt;param&gt; element,
     * based on its type.
     * @param param - a &lt;param&gt; element in a Query Service's describe 
     * response XML message */
    public void createWidget(Element param)
    {
        if(this.type.equals(GSXML.PARAM_TYPE_INTEGER) 
                    || this.type.equals(GSXML.PARAM_TYPE_STRING)) 
        {
            createTextField();
        }
        else if (this.type.equals(GSXML.PARAM_TYPE_BOOLEAN)) 
        {
            createBooleanField();
        }
        else if(this.type.equals(GSXML.PARAM_TYPE_ENUM_SINGLE)
                || this.type.equals(GSXML.PARAM_TYPE_ENUM_MULTI)) 
        {
            createEnumListing(param); // either a combo or list
        }
    } // end method setUpWidget()
    
    /** Creates check box controls for the &lt;param&gt; elements whose 
     * types are GSXML.PARAM_TYPE_BOOLEAN. */
    public void createBooleanField() {
        JCheckBox checkbox = new JCheckBox();
        if(def.equals("1"))
            checkbox.setSelected(true);
        this.ref = checkbox;
    }

    /** Creates text fields for the &lt;param&gt; elements whose types are
     * GSXML.PARAM_TYPE_STRING or GSXML.PARAM_TYPE_INTEGER). */
    public void createTextField() { 
        int cols = this.type.equals(GSXML.PARAM_TYPE_INTEGER) ? 4 : 15;
        this.ref = new JTextField(cols);
        if(!def.equals(""))
            ((JTextField)this.ref).setText(def);
    }
    
    /** Creates combo boxes/drop-downs for the &lt;param&gt; elements
     * whose types are GSXML.PARAM_TYPE_ENUM_SINGLE and listboxes for those
     * whose types are GSXML.PARAM_TYPE_ENUM_MULTI. 
     * @param param - a &lt;param&gt; element in a Query Service's describe 
     * response XML message */
    public void createEnumListing(Element param) 
    {
        NodeList nl = param.getElementsByTagName(GSXML.PARAM_OPTION_ELEM);
        // If no <option> elements, we do nothing
        if(nl != null && nl.getLength() > 0) {
            subElements = new QueryFormData[nl.getLength()];
            Vector selectedIndices = new Vector(subElements.length);
            for(int i = 0; i < subElements.length; i++){
                Element e = (Element)nl.item(i);
                subElements[i] = new QueryFormData(e); 
                    // create list items for each <option>
                
                // Keep track of which options should be selected by
                // default, by storing these indices.
                // Don't use def.equals() but def.indexOf():
                // i.e. select those items where this.name occurs in def,
                // because def is a comma separated list of default values
                if(def.indexOf(subElements[i].name) != -1) 
                    selectedIndices.add(new Integer(i));
            }
            // Now create the widgets
            if(this.type.equals(GSXML.PARAM_TYPE_ENUM_MULTI)) {
                this.ref = new JList(subElements);
                        // by default, JList is set to what we want:
                        // MULTIPLE_INTERVAL_SELECTION
                if(!def.equals("")) {
                    int[] selIndices = new int[selectedIndices.size()];
                    for(int i = 0; i < selectedIndices.size(); i++)
                        selIndices[i] = 
                            ((Integer)selectedIndices.get(i)).intValue();
                    
                    ((JList)this.ref).setSelectedIndices(selIndices);
                }
            }
            else { // ENUM_SINGLE and BOOLEAN get a JComboBox 
                this.ref = new JComboBox(subElements);
                if(!def.equals("")) { // for JCombobox, only 1 item default at a time
                    ((JComboBox)this.ref).setSelectedIndex(
                            ((Integer)selectedIndices.get(0)).intValue());
                }
            }
        } 
        else { // no <option>s, look for a <displayItem>
            nl = param.getElementsByTagName(GSXML.DISPLAY_TEXT_ELEM);
            if(nl != null && nl.getLength() > 0) {
            Element displayItem = (Element)nl.item(0);
            this.ref = new JLabel(GSXML.getNodeText(displayItem));
            }
        }
    } 
    
    /**
     * A multi-panel is created for a *set* of controls that occur more than 
     * once.
     * Processes &lt;param type="multi"&gt; in a Query Service's describe 
     * response XML. (I.e. the type is GSXML.PARAM_TYPE_MULTI)
     * Complicated case: can have 'occurs' field set. And this &lt;param&gt; 
     * element can have multiple &lt;param&gt;s itself, each with the 'ignore' 
     * possibly set and each with its own &lt;option&gt; elements.
     * @param param - a &lt;param&gt; element in a Query Service's describe 
     * response XML message
     * @param parentPanel - the panel inside which the multipanel is to display
     * itself.
    */
    public void createMultiPanel(Element param, JPanel parentPanel) {
        // Create the widgets for MULTI at least once:
        int num_occurs = occurs.equals("") ? 1 : Integer.parseInt(occurs);
        NodeList nl = param.getElementsByTagName(GSXML.PARAM_ELEM);
        
        // This panel is now a multi panel: contains multiple associated
        // widgets each in their own panels along with their labels. 
        // All *grouped* sub <param> elements in a panel each, and these 
        // panels on top of each other. 
        GridBagLayout gbLayout = new GridBagLayout();
        GridBagConstraints gbConstraints = new GridBagConstraints();
        // fixed for all components
        //gbConstraints.anchor = GridBagConstraints.NORTHWEST;
        gbConstraints.insets = new java.awt.Insets(2, 2, 2, 2);
        gbConstraints.ipadx = 5;
        gbConstraints.ipady = 3;
        gbConstraints.fill = GridBagConstraints.BOTH;
        gbConstraints.weightx = 0;
        gbConstraints.weighty = 0;
        JPanel panel = new JPanel(gbLayout);
            //new GraphPaperLayout(new Dimension(nl.getLength(), num_occurs+1)));
            // num_occurs + 1: extra row to allow for the row of headings
        Border lineBorder = BorderFactory.createLineBorder(Color.GRAY);
        panel.setBorder(lineBorder);
        this.ref = panel; // this QueryFormControl objects JComp ref variable 
        
        // For GridBagLayout calculations
        int[] colWidths = null; // store the width of each column
        int colPosition = 0; // the column position of the widget in the layout 
        
        // Instantiating and positioning the Query Form controls 
        if(nl != null && nl.getLength() > 0) {
            colWidths = new int[nl.getLength()]; // to store the width of the columns
            // For each <param> child of Element param, we create a QueryFormParam
            // object which is stored in the subElements array
            // We do this 'occurs' number of times (minimum 'occurs' is once) 
            subElements = new QueryFormParam[nl.getLength() * num_occurs];
            for(int j = 1; j <= num_occurs; j++) {
                // Now process all <param> elements and put them into this.ref panel
                int numParams = nl.getLength();
                for(int i = 0; i < numParams; i++){
                    Element e = (Element)nl.item(i); // get the child
                    QueryFormControl paramEl = new QueryFormControl(e);
                    subElements[(j-1) * numParams+i] = paramEl;
                    
                    // GridBagLayout calculations                   
                    if(j == 1) { // When processing the first row, store the col widths
                        colWidths[i] = paramEl.width;
                    }           
                    // Calculate the column position of the form control in the layout
                    // ColPosition of current control is the sum of the widths of all
                    // previous controls (all controls to the left of it in this row)
                    if(i > 0) {
                        // increment column position of this control by previous 
                        // widget's width 
                        colPosition += colWidths[i-1];
                    } else { // i == 0, reset colPosition to 0
                        colPosition = 0; 
                    }
                    
                    // If 'ignore' is set, check whether we should ignore the 
                    // widget at this occurs-iteration of the loop
                    if(!paramEl.ignore.equals("")) {
                        int ignorePos = Integer.parseInt(paramEl.ignore);
                        if(ignorePos != (j-1)) {
                            // occurs-iteration (outer loop) when indexed from 0 
                            // doesn't match ignorePos so can set up this widget
                            paramEl.createWidget(e);
                                // false means label not attached to widget
                            // j is row, i is col
                            this.addGridBagComponent(panel, paramEl.ref, gbLayout, 
                                gbConstraints, colPosition, j, paramEl.width, 1);
                        } 
                        // else if the outer loop iteration-index matched, 
                        // ignore widget
                    } 
                    else { // when 'ignore' member var not set, set up this widget
                        paramEl.createWidget(e);
                        this.addGridBagComponent(panel, paramEl.ref, gbLayout, 
                            gbConstraints, colPosition, j, paramEl.width, 1);
                    }
                } // end for on subElements
                // add each panel of grouped param elements to this multi panel
                // this.panel.add(singlePanel);
            } // end for on num_occurs
            
            // Now add a heading row: labelling each column in the multipanel:
            // JPanel headingPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
            // get the labels from the subelements' displayElement:
            for(int i = 0; i < subElements.length/num_occurs; i++) {
                // Calculate the column position of the form control in the layout 
                // ColPosition of current control is the sum of the widths of all
                // previous controls (all controls to the left of it in this row)
                if(i == 0) {
                    colPosition = 0;
                } else { // i > 0
                    colPosition += colWidths[i-1];
                }
                JLabel colHeading = new JLabel(subElements[i].displayItem);
                // add it to the top of this multi panel 
                this.addGridBagComponent(panel, colHeading, 
                    gbLayout, gbConstraints, colPosition, 0, 1, 1); 
                                        // col i, row 0, size (1,1)
            }

            // Add the multi panel to the parent. 
            // First it is nested in a panel laid out with FlowLayout in order 
            // to not have the multipanel centred in an ugly manner.
            JPanel outerPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
            outerPanel.add(panel); // same as adding this.ref
            parentPanel.add(outerPanel);
        } // end if
        
    } // end processing <param type=multi>
    
    /**
     * The multi-panel is laid out with a GridBagLayout in order to make 
     * the layout more attractive (so that the form controls don't have as 
     * odd sizes as before when GraphPaperLayout was used).
     * This method sets the constraints for the given control and then adds 
     * it to the given JPanel.
     * This method is called to add a control (or heading label) to the 
     * multi-panel using GridBagLayout.
     * @param panel is the panel to add the control (or heading label) to.
     * @param comp is the Query Form control or heading JLabel to be laid out.
     * @param gbLayout is the GridBagLayout object used to lay out the panel.
     * @param gbConstraints is the GridBagConstraints object for the panel's
     * GridBagLayout.
     * @param col is the column value of the top-left of the control (for 
     * setting the GridBagLayout's gridx value).
     * @param row is the row value of the top-left of the control (for 
     * setting the GridBagLayout's gridy value).
     * @param w is the number of columns spanned by the control (for setting 
     * the GridBagLayout's gridwidth value).
     * @param h is the number of rows spanned by the control (for setting 
     * the GridBagLayout's gridheight value). 
    */
    protected void addGridBagComponent(JPanel panel, JComponent comp,
            GridBagLayout gbLayout, GridBagConstraints gbConstraints,
        int col, int row, int w, int h) 
    {
        // different for all components
        gbConstraints.gridx = col;
        gbConstraints.gridy = row;
        gbConstraints.gridwidth = w;
        gbConstraints.gridheight = h;
        
        gbLayout.setConstraints(comp, gbConstraints);
        panel.add(comp);
    }
    
    /** If called after the form containing these param controls has been 
     * displayed and the user has entered/selected values (i.e. after the search 
     * button to execute a query has been pressed), then this method puts  
     * the controls' associated QueryFormParam names and the user-
     * entered/-selected values into the HashMap nameValsmap (= the argument).
     * Note that for the GSXML.PARAM_TYPE_MULTI case - where each related set 
     * of controls may occur several times (depending on member variable 
     * 'occurs') - the value entered/selected for each control that has the 
     * same *name* (= key into the HashMap) is added into the HashMap as
     * a comma-separated list associated with its name-key.
     * This method requires that argument nameValsmap is a non-null HashMap.
     * @param nameValsMap - a non-null HashMap. At the end of this method,
     * the nameValsMap HashMap will contain mappings from query parameter field  
     * names to their user-entered values (for the field's associated 
     * form controls).
    */
    public void setSelectedValue(HashMap nameValsMap) {
        // When setSelectedValue() is called on subElements
        // that have their ignore member var set at any stage,
        // their this.ref will be null, so can add "" for those cases.
        if(this.ref == null) {
            //Also the case for *ignored* ParamElementGUIs whose widgets
            //never got instantiated (to do with member var 'ignore')
            
            //In these cases, there is no value that the user input, 
            //so just add ""
            if(nameValsMap.containsKey(this.name)) {
                //just append to existing value for key:
                String cumVal = (String)nameValsMap.get(this.name);
                cumVal += ",";
                nameValsMap.put(this.name, cumVal);
            } else { 
                // widget.type=invisible, set to default
                if(this.type.equals(GSXML.PARAM_TYPE_INVISIBLE) 
                        && !this.def.equals(""))
                    nameValsMap.put(this.name, this.def);
                else //put empty string in there for now
                    nameValsMap.put(this.name, "");
            }
            return; //that's it, don't go any further
        }
        
        // Complex type: can contain multiple child parameters/options
        // Need all names that match to have associated values in 
        // comma-separated list
        if(this.type.equals(GSXML.PARAM_TYPE_MULTI)) {
            for(int i = 0; i < subElements.length; i++) {
                ((QueryFormControl)subElements[i]).setSelectedValue(
                        nameValsMap);
            }
        } else if(this.type.equals(GSXML.PARAM_TYPE_ENUM_MULTI)) {
            // JList
            JList list = (JList)this.ref;
            Object[] selectedParams = list.getSelectedValues();
            for(int i = 0; i < selectedParams.length; i++) {
                String value = ((QueryFormData)selectedParams[i]).name; 
                if(nameValsMap.containsKey(this.name))
                    //append value to existing value for the same key
                    value = (String)nameValsMap.get(this.name) + "," + value;
                nameValsMap.put(this.name, value);
            }
        } else if(this.type.equals(GSXML.PARAM_TYPE_ENUM_SINGLE)) {
            // JCombobox
            JComboBox combo = (JComboBox)this.ref;
            QueryFormData selectedParam = (QueryFormData)combo.getSelectedItem();
            String value = selectedParam.name; 
            if(nameValsMap.containsKey(this.name)) // key exists, so append
                value = (String)nameValsMap.get(this.name) + "," + value;
            nameValsMap.put(this.name, value);
        } else if (this.type.equals(GSXML.PARAM_TYPE_BOOLEAN)) {
            JCheckBox checkbox = (JCheckBox)this.ref;
            String value = "0"; //"off" 
            if(checkbox.isSelected()) //boolean is "on"
                value = "1"; 
            if(nameValsMap.containsKey(this.name)) // key exists, so append
                value = (String)nameValsMap.get(this.name) + "," + value;
            nameValsMap.put(this.name, value);
        } else if(this.type.equals(GSXML.PARAM_TYPE_INTEGER) 
                || this.type.equals(GSXML.PARAM_TYPE_STRING)) { 
            // Textfield 
            JTextField field = (JTextField)this.ref;
            String value = field.getText();
            if(nameValsMap.containsKey(this.name)) // key exists, so append
                value = (String)nameValsMap.get(this.name) + "," + value;
            nameValsMap.put(this.name, value);
        }
    }
}