Standard implementation of the Command-Center layout

This document starts with a sample that is easier to explain.
To see the XML-structure used in this tutorial-project please follow this link.

This structure is divided into three divisions:

• FrameIndividual
  Within this section every element of a GUI (except buttons, for which a seperate xml-file exist) that can contain a text, is listed.
  For each element either unique properties are defined or a reference to a specification within the 'Common' division is given.

• CommonElements
  Properties for elements of a GUI which are used in more than one frame - and where the properties should be consistent.
  E.g. a product-code is used in several frames but should always have the same label (Product Code) and the same validation (e.g. for a maximum length). So the properties can be defined in the 'Common' division and a refernce to this definition is made in each element in the 'FrameSpecific' division where the product-code is referred.

• ValidationMessages
  There, messages for a not fulfilled validation are defined.
  E.g. if the properties of a element define a maximum length and more characters are entered, then a language-dependant text - like 'entry to long' - can be retrieved for that failed validation.
  At the time of writng (Mai 2006), the content of this division is very basic.
  Improvements may be made depending on the requierements arising.

Prerequisites:

• None;
  this document accompanies the development of a fat-client with Java (Develop a Fat-Client in Java) and explains the structure of the xml-file with language-dependant text-elements for the GUI.

Example:

• This example is an excerpt from a not yet published project.
  That means, the listed example has nothing to do with the Tutorial to Develop a Fat-Client in Java.

• The sample - an excerpt from the file 'DisplayStrings.xml':
  <!-- Root-Element; has to be there otherwise the parser reports an error -->
<root>
<!--            ********************************************* -->
<!-- ********** Section with individual values for the frames *********** -->
  <FrameIndividual>
    <Frame>
      <FrameClass>js_handelssepp.clientframes.Product</FrameClass>
      <FrameTitle>HandelsSepp - Maintain Product data</FrameTitle>
      <Element>
        <ElementName>lbl_ProductCode</ElementName>
        <CommonElementReference>lbl_ProductCode</CommonElementReference>
      </Element>
      <Element>
        <ElementName>txt_ProductCode</ElementName>
        <CommonElementReference>txt_ProductCode</CommonElementReference>
        <Mandatory></Mandatory>
      </Element>
    </Frame>
    <Frame>
      <FrameClass>js_handelssepp.clientframes.ProductSearch</FrameClass>
      <FrameTitle>HandelsSepp - Search for a product by name or fragments of the code</FrameTitle>
      <Element>
        <ElementName>lbl_ProductCodeSearch</ElementName>
        <CommonElementReference>lbl_ProductCode</CommonElementReference>
        <ToolTipText>Beginning characters of the Product-Code to search for</ToolTipText>
      </Element>
      <Element>
        <ElementName>txt_ProductCodeSearch</ElementName>
        <CommonElementReference>txt_ProductCode</CommonElementReference>
        <ToolTipText>Beginning characters of the Product-Code to search for</ToolTipText>
        <MessageText>Beginning characters of the Product-Code to search for</MessageText>
        <MinimumLength>2</MinimumLength>
        <Mandatory></Mandatory>
      </Element>
    </Frame>
  </FrameIndividual>
<!--            ***************************************************************** -->
<!-- ********** Section with common values for elements of a kind on several frames *********** -->
  <CommonElements>
    <CommonElement>
      <ElementName>lbl_ProductCode</ElementName>
      <ElementText>Product-Code</ElementText>
      <ToolTipText>Product-Code; the unique code of the product</ToolTipText>
    </CommonElement>
    <CommonElement>
      <ElementName>txt_ProductCode</ElementName>
      <MinimumLength>4</MinimumLength>
      <MaximumLength>20</MaximumLength>
      <ToolTipText>Product-Code; the unique code of the product</ToolTipText>
      <MessageText>Product-Code; the unique code of the product</MessageText>
    </CommonElement>
  </CommonElements>
<!--            ******************************************** -->
<!-- ********** Section with messages for failed validations *********** -->
  <ValidationMessages>
    <InputTooShort>Input too short; minimum number of characters requiered: </InputTooShort>
    <InputTooLong>Input too long; maximum number of characters allowed: </InputTooLong>
  </ValidationMessages>
</root>

top.

Detailed description of attributes:

• <root>.is enclosing the whole xml-structure.
  An attribute name for the whole xml-structure is requiered, as the parser (to read the file and build a structure within a Java-application) is not capable to read more than one xml-structures within in one file.

• <FrameIndividual>.is enclosing all elements of the GUI (except buttons, for which 'Buttons.xml' exists).

• <Frame>.is enclosing all elements (except buttons) of one Frame - where the term 'Frame' in Java is similar to a 'Window'.

• <FrameClass>.is the fully qualified class-name of the Frame.

• <FrameTitle>.is the text which is displayed in the Titlebar of a Frame.

• <Element>.is enclosing all elements of the Frame (except buttons).

• <ElementName>.is the name of the element as it was defined with the method java_element.setName(„element_name“) in the Java-code.

• <CommonElementReference>.is the reference to the properties of an element in the <CommonElements> division.
  Properties which are not defined are taken from the element in the <CommonElements> division. This allows to define properties at one place for elements that are used similar on more than one frame. For a better understanding please see the Example above.

• <ElementText> is the text the element is filled with. This applies mainly to JLabel. If it is defined for other elements (e.g. JText), then the entry-area is filled with this text at the time the frame is built.

• <ToolTipText> is the text that is displayed as 'ToolTip' when the mouse-pointer is moved over the element.

• <MessageText> is defined for a project not already documented. This text is displayed at a 'Message-Area' at the bottom of the frame when the element 'has the focus' i.e. the cursor is in that element (JTextField, JComboBox) and entered data goes into that field.
  Advantage over <ToolTipText> is, that the mouse-pointer does not have to be over the element to see the 'Help'.

• <MinimumLength> is the minimum number of characters that have to be entered into that element - if applicable (e.g. JTextField, JComboBox).
  This validation only starts if there was made an entry; it does not count if the entry to the element is 0 characters long.

• <MaximumLength> is the maximum number of characters that are allowed to be entered to that element - if applicable (e.g. JTextField, JComboBox).

• <Mandatory> is an attribute with an empty string as value. If that attribute exists for an <Element>, than an entry has to be made for that element.
  This attribute is only applicable within the <FrameIndividual> division; it has no effect in the <CommonElement> division.

• <CommonElements>.contains properties for elements that are used similar on more than one frame.
  All attributes described for <Element> apply, with the exemption of <Mandatory>, which has no effect here.

• <ValidationMessages>.contains text for not fulfilled validations. At the time of writing (May 2006) the content of this division is very basic.

• <InputTooShort>.is a message that the number of characters (specified by property <MinimumLength>) is not yet reached.
  The validation and processing of the message is done in a method within the application (to be written).

• <InputTooLong>.is a message to show that the number of characters (specified by property <MaximumLength>) is exceeded.
  The validation and processing of the message is done in a method within the application (to be written).

top.

Priority of properties between FrameIndividual-values and CommonElements-values:

• First, the element is searched in the division <FrameIndividual>.
  If it is not found there, an error is reported.

• If an attribute <CommonElementReference> is found, then the attributes are read from there.

• After the attributes from the <CommonElements> division are read, there is checked, if there are some more attributes for the element are defined in the <FrameIndividual> division.

• If there are, the properties of these attributes overwrite the properties defined in the <CommonElements> division.

• Example from the excerpt above:
  1.) <ElementName>txt_ProductCodeSearch</ElementName>
     in <FrameClass>js_handelssepp.clientframes.ProductSearch</FrameClass>
     refers to <CommonElementReference>txt_ProductCode</CommonElementReference>.
  2.) At <ElementName>txt_ProductCode</ElementText> in the <CommonElements>, the following properties are defined:
     <MinimumLength>4</MinimumLength>,
     <MaximumLength>20</MaximumLength>,
     <ToolTipText>Product-Code; the unique code of the product</ToolTipText>,
     <MessageText>Product-Code; the unique code of the product</MessageText>.
  3.) As attributes
     <ToolTipText>Beginning characters of the Product-Code to search for</ToolTipText>
   <MessageText>Beginning characters of the Product-Code to search for</MessageText>
   <MinimumLength>2</MinimumLength>
     are also defined at <ElementName>txt_ProductCodeSearch</ElementName>,
     these values will overwrite the values from <ElementName>txt_ProductCode</ElementText> in the <CommonElements>.
  Furthermore <Mandatory></Mandatory> is set, which means that the entry to the field is mandatory.

• Idea - shown at the example:
  Some of the attribute values (i.e. <MaximumLength>20</MaximumLength> or <ElementText>Product-Code<ElementText> in the example) are suitable for all elements dealing with 'Product-Code'.
  For the entry field at the 'Search' frame,
  the <MinimumLength> is reduced, as it is needed to enter just fragments of the 'Product-Code',
  the <ToolTipText> and <MessageText>
  are changed to reflect that this field is for a search-value and not for a complete 'Product-Code'.

top.

Structure used in the tutorial-project:

• Content of the file 'DisplayStrings.xml' - for easy 'cut and paste' ;-):
  <!-- 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>
        <ElementText>Maintain 'Projects'</ElementText>
        <ToolTipText>Click this button to open the frame to maintain Project-codes</ToolTipText>
      </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>

top.

Related Documents:Related Documents: