Fat-Client-Development - Setting the properties of the GUI-Elements, Part 2

In the previous step code was presented to set the properties (in detail: the text in the title-bar) of a JFrame.
The properties were read from a language-dependant file containing a XML-structure defining the fitting properties for each GUI-element.

In this step, the code is extended to set the properties also for JLabel, JTextField and JButton.
Also, the algorithm to get properties which are defined as 'Common' (i.e. belonging to more than one GUI-element), is documented.
For a detailed explanation of the XML-structure with the properties please see Structure of the xml-file with language dependant strings for the user-interface.

Preface:

This document does not contain the complete code.
This decision was made to avoid an overloading. The idea was to give an explanation how the XML-structure is searched and the properties are set at the GUI-elements.

For a complete listing of the code please follow the links at the code-snippets.

The code written in this tutorial is highly optimized !
It is not essential that you completely understand the code for getting an idea how Fat-Clients are developed.

Credits:

Several and none; using recursive structures is a common process - I just applied it for that special case.

Prerequisites:

• JS_FC01g - Setting the properties of the GUI-elements completed - and its prerequisites too.

Edit the content of file 'DisplayStrings.xml' to add the properties for the JLabel:

The properties for the GUI-element 'lbl_Welcome' (of type Jlabel) and 'btn_Maintain' (of type Jbutton) are added.
Both elements were coded in step JS_FC01d - Create and code the class for the GUI.

• Open the file 'DisplayStrings.xml' (to find the right directory is a test; if you are unsure see step JS_FC01g - Setting the properties of the GUI-elements) and add the following lines:

<!-- Root-Element; has to be there otherwise the parser reports an error -->
<root>
<!--            ********************************************* -->
<!-- ********** Section with individual values for the frames *********** -->
  <FrameIndividual>
    <Frame>
      <FrameClass>js_errdb.clientframes.JS_ErrDB_CommandCenter</FrameClass>
      <FrameTitle>CommandCenter - Maintain Error-DB; © www.javascout.biz</FrameTitle>
      <Element>
        <ElementName>lbl_Welcome</ElementName>
        <CommonElementReference>lbl_Welcome</CommonElementReference>
        <ToolTipText>Welcome at the JavaScout-Tutorial for developing Fat-Clients</ToolTipText>
      </Element>
      <Element>
        <ElementName>btn_Maintain</ElementName>
        <CommonElementReference>lbl_Welcome</CommonElementReference>
        <ElementText>Maintain 'Projects'</ElementText>
      </Element>
    </Frame>
  </FrameIndividual>
  <CommonElements>
    <CommonElement>
      <ElementName>lbl_Welcome</ElementName>
      <ElementText>Welcome at the JavaScout-Tutorial for developing Fat-Clients; please select a sub-task !</ElementText>
    </CommonElement>
  </CommonElements>
</root>

• You might ask why there was a <CommonElement> introduced when there is only one GUI-element 'lbl_Welcome' present.
The reference was set to show and test the code to search <CommonElements>. The code to do this is documented later.

top.

Define the constants representing errors :

• As there might be inconsistencies within the XML-structure, some constants representing errors habe to be added:
The status-code is defined in the interface JSBS_XML_Constants :

/*
 * FRAMETITLE_NOT_PRESENT:
 * The property <FrameTitle> is not present for the searched <FrameClassName>. */
    public static int CONST_FRAMETITLE_NOT_PRESENT = 13;
/*
 * Stati concerning <Frame> properties within the XML-structure. */
/*
 * GUI_ELEMENT_NOT_PRESENT:
 * There is not even one <Element> present as a child of a <Frame>.
 * This can not be as every <Frame> has a GUI-<Element>. */
    public static int CONST_GUI_ELEMENT_NOT_PRESENT = 21;
/*
 * Stati concerning <CommonElement> properties within the XML-structure. */
/*
 * GUI_ELEMENT_COMMON_NOT_PRESENT:
 * There was a reference found to a common GUI-ELEMENT
 * but there is no such element within the XML-structure. */
    public static int CONST_GUI_ELEMENT_COMMON_NOT_PRESENT = 31;
/*
 * COMMONELEMENTS_DIVISION_NOT_PRESENT:
 * There is no <CommonElements> division as a direct child of the root-element. */
    public static int CONST_COMMONELEMENTS_DIVISION_NOT_PRESENT = 32;
/*    */
/*
 * UNKNOWN_ERROR: Something went wrong but exact reason is unknown */
    public static int CONST_UNKNOWN_ERROR = 999;
}

The complete code for the interface can be found in JSBS_XML_Constants.

top.

Code for searching the XML-structure and transferring the properties to the GUI-element :

• The code is split into several methods.
The first one can search the XML-structure with given parameters of the Frame-Class-name and the name of the GUI-element.
This finds (if defined within the XML-structure) a (DOM-)element with the properties for the requested GUI-Element.

• The following code is a snippet from the class JSBS_XML_DisplayStrings.
Please do not worry when you get an error saying that method mergeCommonElementProperties(. . .) is not found.
This method will be coded in the next paragraph.

/* 
 * List searched without finding a <Frame>-element with fitting class-name;
 * return the error. */
      StatusCode = CONST_FRAMECLASS_NOT_PRESENT;
      return StatusCode;
    }
/*
 * ************************************************** */
/*
 * Method to get a DOM-Element belonging to the <FrameIndividual> division of the XML-structure */
    private Element getGUI_Element(String parmstrFrameClassName, String parmstrElementName) {
/* 
 * Variables:
 */
/* Element for the <FrameIndividual> Division, element for one <Frame>,
 * element for the <FrameClass>, String with the name of the FrameClass,
 * element for one GUI-Element within the <Frame>,
 * element for the <ElementName> and String with the content of it (the name). */
      Element elementFrameIndividual;
      Element elementFrame;
      Element elementFrameClass;
      String  strFrameClassName;
      Element elementGUI_Element;
      Element elementElementName;
      String  strElementName;
/* List of all <Frame>-elements, size and index for searching it. */
      List listFrame;
      int intlistFrameSize;
      int intlistFrameIndex = 0;
/* List of all GUI-<Element>-elements, size and index for searching it. */
      List listGUI_Element;
      int intlistGUI_ElementSize;
      int intlistGUI_ElementIndex = 0;
/* 
 * Set the StatusCode to OK to see at the end of the method if anything went wrong. */
      StatusCode = CONST_OK;
/* 
 * General check if there are child-elements named <FrameIndividual> present. */
      elementFrameIndividual = XML_RootElement.getChild("FrameIndividual");
      if (elementFrameIndividual == null) {
        StatusCode = CONST_FRAMEINDIVIDUAL_DIVISION_NOT_PRESENT;
        return null;
      }
/* 
 * Get the list of <Frame>-elements and the number of elements within. */
      listFrame = elementFrameIndividual.getChildren();
      intlistFrameSize = listFrame.size();
      if (intlistFrameSize == 0) {
        StatusCode = CONST_FRAMECLASS_NOT_PRESENT;
        return null;
      }
/* 
 * Inspect each element of the list to find the element
   fitting the Class-Name of the JFrame passed as parameter. */
      for (intlistFrameIndex = 0; intlistFrameIndex < intlistFrameSize; intlistFrameIndex++) {
        elementFrame = (Element) listFrame.get(intlistFrameIndex);
/* Get the element with the <FrameClass> to compare its content
 * with the Class-Name of the passed parameter. */
        elementFrameClass = elementFrame.getChild("FrameClass");
        if (elementFrameClass == null) {
          StatusCode = CONST_FRAMECLASS_NOT_PRESENT;
          return null;
        }
        strFrameClassName = elementFrameClass.getTextTrim();
        if (strFrameClassName.compareTo(parmstrFrameClassName) == 0) {
/* Fitting <Frame>-element found within the list;
 * extract the list of GUI-elements and inspect each of it. */
          listGUI_Element = elementFrame.getChildren("Element");
          intlistGUI_ElementSize = listGUI_Element.size();
          if (intlistGUI_ElementSize == 0) {
            StatusCode = CONST_GUI_ELEMENT_NOT_PRESENT;
            return null;
          }
          for (intlistGUI_ElementIndex = 0; intlistGUI_ElementIndex < intlistGUI_ElementSize; intlistGUI_ElementIndex++) {
            elementGUI_Element = (Element) listGUI_Element.get(intlistGUI_ElementIndex);
/* Get the element <ElementName> to compare its content (name of the GUI-element)
 * and compare it with the name of the GUI-element passed as parameter. */
            elementElementName = elementGUI_Element.getChild("ElementName");
            if (elementElementName == null) {
/* Found a GUI-element without a name.
 * Should not happen but is not a reason to end; skip further inspection */
              strElementName = "";
            }
            else {
              strElementName = elementElementName.getTextTrim();
            }
            if (strElementName.compareTo(parmstrElementName) == 0) {
/* Fitting element found within the XML-structure;
 * check if there are properties at a <CommonElement> and merge if necessary.
 * Check and merge is done in a separate method to limit the depth of 'for' and 'if'
 * hierachies in this method. */
              mergeCommonElementProperties(elementGUI_Element);
              return elementGUI_Element;
            }
          }
        }
      }
/* Searched GUI-element not found within the XML-structure; return the error. */
      StatusCode = CONST_GUI_ELEMENT_NOT_PRESENT;
      return null;
    }
}

• The following code for the method mergeCommonElementProperties(. . .) is a snippet from the class JSBS_XML_DisplayStrings.
Please do not worry when you get an error saying that method getCommonElement(. . .) is not found.
This method will be coded in the next paragraph.

/*
 * ************************************************** */
/*
 * Method to check if properties are define with a DOM-element belonging to the <CommonElements>
 * and – if one exists – transfer its properties */
    private void mergeCommonElementProperties(Element parmelementGUI_Element) {
/* 
 * Variables:
 * element for the <CommonElementReference> and String with the content of it. */
      Element elementCommonElementReference;
      String  strCommonElementReference;
/*
 * Elements containing the properties of the one passed as parameter. */
      Element elementElementText_Param;
      Element elementToolTipText_Param;
/* 
 * Test if the element with the pointer to the CommonElement is present. */
      elementCommonElementReference = parmelementGUI_Element.getChild("CommonElementReference");
      if (elementCommonElementReference == null) {
/* No reference present; further processing can be skipped. */
        return;
      }
/* Get the name of the <CommonReference>-element and then call the method to get it. */
      strCommonElementReference = elementCommonElementReference.getTextTrim();
      Element locelementCommonReference = getCommonElement(strCommonElementReference);
      if (locelementCommonReference == null) {
/* Referenced element not found; should not happen – so report an error. */
        StatusCode = CONST_GUI_ELEMENT_COMMON_NOT_PRESENT;
        return;
      }
/*
 * Transfer properties from the <CommonElement> (just fetched)
 * to the element passed as parameter. 
 * Explanation of the algorithm only for the first transfer. */
      String strElementVariableName = "ElementText";
/* Check if property was not individually defined. */
      elementElementText_Param = parmelementGUI_Element.getChild(strElementVariableName);
      if ( elementElementText_Param != null) {
/* Element not found; use property from <CommonElement> if present. */
        Element locelementElementText_Common = locelementCommonReference.getChild(strElementVariableName);
        if (locelementElementText_Common != null) {
/* Element found as property with the <CommonElement>;
 * transfer data to the element passed as parameter. */
          Element locelementElementText_New = new Element(strElementVariableName);
          locelementElementText_New.setText(locelementElementText_Common.getTextTrim());
          parmelementGUI_Element.addContent(locelementElementText_New);
        }
      }
/* Transfer ToolTipText. */
      strElementVariableName = "ToolTipText";
      elementToolTipText_Param = parmelementGUI_Element.getChild(strElementVariableName);
      if ( elementToolTipText_Param != null) {
        Element locelementToolTipText_Common = locelementCommonReference.getChild(strElementVariableName);
        if (locelementToolTipText_Common != null) {
          Element locelementToolTipText_New = new Element(strElementVariableName);
          locelementToolTipText_New.setText(locelementToolTipText_Common.getTextTrim());
          parmelementGUI_Element.addContent(locelementToolTipText_New);
        }
      }
    }

• As last private method, the code for getCommonElement(. . .) is coded. This is a snipped from the class JSBS_XML_DisplayStrings.
/*
 * ************************************************** */
/*
 * Method to get a DOM-Element belonging to the <CommonElements> division of the XML-structure */
    private Element getCommonElement(String parmstrElementName) {
/* 
 * Variables:
 */
/* Element for the <CommonElements> Division, element for one <CommonElement>,
 * element for the <CommonElementName> and String with the content of it (the name). */
      Element elementCommonElements;
      Element elementCommonElement;
      Element elementGUI_Element;
      Element elementCommonElementName;
      String  strCommonElementName;
/* List of all <CommonElement>-elements, size and index for searching it. */
      List listCommonElement;
      int intlistCommonElementSize;
      int intlistCommonElementIndex = 0;
/* 
 * General check if there are child-elements named <CommonElements> present. */
      elementCommonElements = XML_RootElement.getChild("CommonElements");
      if (elementCommonElements == null) {
        StatusCode = CONST_COMMONELEMENTS_DIVISION_NOT_PRESENT;
        return null;
      }
/* 
 * Get the list of <CommonElement>-elements and the number of elements within. */
      listCommonElement = elementCommonElements.getChildren();
      intlistCommonElementSize = listCommonElement.size();
      if (intlistCommonElementSize == 0) {
        StatusCode = CONST_COMMONELEMENTS_DIVISION_NOT_PRESENT;
        return null;
      }
/* 
 * Inspect each element of the list to find the element
   fitting the element-name passed as parameter. */
      for (intlistCommonElementIndex = 0; intlistCommonElementIndex < intlistCommonElementSize; intlistCommonElementIndex++) {
        elementCommonElement = (Element) listCommonElement.get(intlistCommonElementIndex);
/* Get the element with the <ElmentName> to compare its contents with the passed parameter. */
        elementCommonElementName = elementCommonElement.getChild("ElementName");
        if (elementCommonElementName != null) {
/* Compare if the element was found; otherwise skip and do not consider it as error. */
          strCommonElementName = elementCommonElementName.getTextTrim();
          if (strCommonElementName.compareTo(parmstrElementName) == 0) {
/* Fitting <CommonElement>-element found within the list; return it ! */
            return elementCommonElement;
          }
        }
      }
/* Searched common-element not found within the XML-structure; return the error. */
      StatusCode = CONST_GUI_ELEMENT_COMMON_NOT_PRESENT;
      return null;
    }

• What is missing for now, are 'public' methods that transfer the properties to the GUI-elements.
The one for a JLabel is documented here; another for JButton can be found in the document with the complete class JSBS_XML_DisplayStrings.

/*
 * ************************************************** */
/*
 * Method to transfer the properties defined in the XML-structure
 * to a GUI-element of type JLabel */
    public int processJLabel(JLabel parmJLabel, String parmstrFrameClassName) {
/*
 * Variables:
 */
/* Fitting element out of the XML-structure and
 * elements representing all properties to be transferred to the JLabel */
      Element elementGUI_Element;
      Element elementGUI_ElementText;
      Element elementGUI_ToolTipText;
/*
 * Name of the JLabel; used as identifier to get the fitting GUI-element out of the XML-structure */
      String strLabelName = parmJLabel.getName();
/*
 * Get the fitting GUI-element using the method implemented above */
      elementGUI_Element = getGUI_Element(parmstrFrameClassName, strLabelName);
      if (elementGUI_Element == null) {
        StatusCode = CONST_GUI_ELEMENT_NOT_PRESENT;
        return StatusCode;
      }
 /*
 * Transfer the properties of the GUI-element to the JLabel passed as parameter */
      elementGUI_ElementText = elementGUI_Element.getChild("ElementText");
      if (elementGUI_ElementText != null) parmJLabel.setText(elementGUI_ElementText.getTextTrim());
      elementGUI_ToolTipText = elementGUI_Element.getChild("ToolTipText");
      if (elementGUI_ToolTipText != null) parmJLabel.setToolTipText(elementGUI_ToolTipText.getTextTrim());
/*
 * Return the Status-code of this class; it reflects if errors occured during processing */
      return StatusCode;
    }

• Finally, the recursive method (processLanguageDependantElements(. . .)) that inspects all GUI-elements has to be extended that the above coded methods are called when type of 'JLabel' or 'JButton' are concerned.
The one for a JLabel is documented here; another for JButton can be found in the document with the complete class JSBS_FrameServices.

. . . . . .
. . . . . .
/* Return-Code to pass the status, that was reported by called methods, back */
      int intStatusCode = 0;
      int locintStatusCode = 0;
/* 
 * Check what type is the 'Container' of and call the suitable method */
     if (parmContainer instanceof JLabel) {
        JLabel locJLabel = (JLabel) parmContainer;
        locintStatusCode =
          parmfrmJSBS_StartFrame.structJSBS_XML_DisplayStrings.processJLabel(locJLabel,
                                                                              parmstrFrameClassName);
        if (locintStatusCode > 0) intStatusCode = locintStatusCode;
        return intStatusCode;
      }
/* */
     if (parmContainer instanceof JButton) {
. . . . . .
. . . . . .

  
  

top.

Run the application to see a result of the implemented code

• To see the result of the just typed code, run the application again by selecting >Run>Run....
Select 'JS_ErrDB_CommandCenter' (in the left column under 'Java Application') and click the button [ Run ].



• The application should look like this. Please obey that the text in the GUI-elements reflects the content of the file 'DisplayStrings.xml'.



• What happens if the button 'Maintain 'Projects'' is clicked ?
How to start another frame is shown in the next step.

top.

Next Step:

• As the XML-structure with the language dependant strings are now in the memory, we will develop a recursive method to set the text to the elements of the GUI.
JS_FC01h - Setting the properties of the GUI-elements - part 2.