Description of the com.com.jFormTK JFormField Run-Time Functions…

Table of Contents...
About 'JFormField' Focus Events...
Pre / Post Processor Description …
More run-time Capability …
1. Run-time Address Book Methods...
2. Run-time Assignment Statement Processing…
3. Run-time pre / post ‘IF’ Statement Processing…
Using the ‘com.com.jFormTK’ Common DATA BASE in Assignments...
Unexpected Forward Referencing…
Developer Caution…
Restrictions...

About 'JFormField' Focus Events...

Each Field [JFormField] of  an Applications Form [JFormForm SubClass] may contain a "Pre Process" OR "Post Processor" operation when a Pre / Post Process Focus Event occurs. A "Focus Events" occurs in accordance with the following rules:

'JFormField' Pre Processor Focus Events:
1.    TAB or ENTER key from the previous 'JFormField'.
2.    Mouse Selection of a 'JFormField'.
3.    Programmatic branch to the 'JFormField':
        -    Current OR First 'JFormField' when a 'Form is loaded into the ShowPanel
        -    Branch to a Form.Field from a Pre / Post Processing operation.

'JFormField' Post Processor Focus Events:
1.    TAB or ENTER key from the current 'JFormField'.
2.    Mouse Selection of a different 'JFormField'

NOTE:
A Post Processor Event DOES NOT occur when the 'com.jFormTK' Application End User selects a TAB. The current Form is saved and the currently Focused 'JFormField' shall receive the Focus when the Form is reloaded. At that time the above 'JFormField' Post Processor Focus Event rules are applied.

Pre / Post Processor Description …

The com.jFormTK Package has the capability to invoke ‘pre Processor’ and ‘post Processor’ Methods designed to make run-time adjustments to a specific ‘JFormField. This process works as follows:

1) The following ‘JFormField’ Methods are designed to activate and control the ‘pre’ Process functions:

public void setPreProcess()
public void setPreProcessFlag(boolean flag)
public void setPreProcessObject(Object variant)
public void setPreProcess(boolean flag, Object variant)

Also, there are a set of the same Methods for the ‘postProcess’ capability…

2) The above methods are designed for use in your Application Form ‘JFormForm’ Sub-Class. They flag the ‘com.jFormTK’ system routines to invoke a ‘JFormForm’ ‘preProcessor’ [or ‘postProcessor] "Override" Method before the associated ‘JFormField’ gains focus [pre Processor] OR when a ‘JFormField’ losses Focus [post Processor]. The ‘preProcessor’ [or ‘postProcessor] "Override" Method is passed a "Reference" to the current ‘JFormField’. If more than one ‘JFormField’ is to be processed, then the ‘preProcessor’ [or ‘postProcessor] "Override" Method shall perform a ‘DO CASE’ [Java ‘switch’ statement] designed to perform a unique set of run-time Java code for each specific ‘JFormField’.

The ‘com.jFormTK’ Application developer can pass information to the ‘pre / post’ Processor Methods by employing the ‘Object variant’ field when setting up the ‘pre/post Processor’ processing in the ‘JFormForm’ Sub-Class. If an ‘Object variant’ parameter is used, then the following Methods are designed to fetch the variant for the run-time processing:

public Object getPreProcessObject()
public Object getPostProcessObject()

3) If the ‘JFormForm’ Sub-Class pre/postProcessor Override method is not found, then the ‘preProcessor’ OR ‘postProcessor’ Methods from the ‘JFormForm’ Parent-Class is used and an error window is presented to the ‘com.jFormTK’ developer.

Top Return to com.jFormTK Overview

More run-time Capability …

The above ‘preProcessor’ OR ‘postProcessor’ ability should be sufficient to accomplish any run-time processing you may need. However, in an effort to make the development of run-time processing requirements as easy to use as possible, the following additional ‘com.jFormTK’ run-time functions are available:

  1. Run-time Address Book ‘Add’ and ‘Update’ Methods…
  2. Run-time pre / post Assignment Statement Processing…
  3. Run-time pre / post ‘IF’ Statement Processing…

Note: In order to understand the following ‘run-time’ features, the reader should have an understanding of how the ‘com.jFormTK’ System references "specific" ‘JFormField’ instances. See the "com.jFormTK Referencing" document for a detailed description of the ‘JFormField’ ID implementation.

The following sections describe each of the above run-time capabilities:

  1. Run-time Address Book ‘Add’ and ‘Update’ Methods…

    NOTE:
    See the Address Book documentation for a description of the com.jFormTK Address Book usage.
    AddressBook.html

    At times, you will be required to enter an individual specified by a specific ‘JFormField’ into your com.jFormTK Application Address Book. Because this is a very common operation, the 'com.jFormTK' Kernel provides dynamic run-time capability to add names to the Application's JAddressBook.

    Another 'com.jFormTK' feature is the ability to make dynamic run-time updates to existing element of the Application JAddressBook.

    See AddressBook. Run Time Processing for detailed description of these 'com.jFormTK,JAddressBook' features.
  2. Return to com.jFormTK Overview

2. Run-time pre / post Assignment Statement Processing…

Quite often there is a need for a ‘pre / post Processor’ Method to perform a simple Java "Assignment" statement, e.g. A = B + C. Again, as a ‘com.jFormTK’ Developer simplification, the following Methods are designed to perform "basic" Java Assignments either as a preProcessor OR a postProcessor operation.

public void setPreAssignment("Assignment String")
public void setPostAssignment("Assignment String")

– where the "Assignment String" is constructed as follows:

  • ‘A’ ID
  • ‘Assignment Operator’
    Accepted Values are "
    =", "+=", "-=", "*=", "/="…
  • ‘B’ ID
  • ‘Computation Operator’
    Accepted Values are "+", "-", "*", "/"…
  • ‘C’ ID
    where ID represents a ‘JFormField’ unique ID String

   Example 1: "Form1.test2 = Form1.test1"
    - Set the Form ‘test2’ field to the Text Value of the Form1 test1 field.

    Example 2: "test2 = test1"
    - Same as Example 1 if the associated object is on the Form1 Form,   i.e. the ‘Form’ Fields in the ID are not required for fields that are  hosted by the same ‘com.jFormTK’ Application Form.

    Example 3: "test3 = test1 – test2"
    - Set the ‘test3’ field to the difference between the ‘test1’ and  ‘test2’ JFormField of the same ‘com.jFormTK’ Application Form.

    Example 4: "Form2.fieldA’ = test1 + test2"
    - Set the ‘fieldA’ field of the ‘Form2’ Form to the sum of the Host Form’s ‘test1’ and ‘test2’ text values.

Comment: These dynamic run-time operations are generally performed on "Numeric" fields. However, if the ‘B’ and ‘C’ fields are "Text" fields, then the "+" operator will perform a concatenation of the two [‘B’ and ‘C’] objects…

Note that using "this" in a JFormField Assignment String commands the ‘com.jFormTK’ to use the ID for the current ‘JFormField’ instance. For example: field1.setPostAssignment("this = this + <c>10") will increment the Field1 field value by 10. Also note that the following Assignment Statement will also increment the Field1 object by 10: Field1.setPostAssignment("this += <c>10")

There are two additional control properties to the run-time Assignment implementation.

  1. Recurrence:

    Generally a ‘com.jFormTK’ pre / post Processor operation is required once. Therefore, once the requested operation [e.g. Assignment] is preformed, the operation is removed, i.e. the Assignment Statement is cleared. However, if you require that the operation be performed each time the specific ‘JFormField’ is ‘pre’ or ‘post’ processed, you may set the "Recurrence" to ‘true’. The following JFormField Methods are used to control the "Recurrence" property:

    setPreAssignmentRecurrence(boolean flag);
    setPostAssignmentRecurrence(boolean flag);
  2. Overwrite:

    By default, the ‘com.jFormTK’ run-time Assignment will not change [Overwrite] the value of the ‘A’ assignment JFormField if the ‘A’ field currently has a "non Null" value. This is done to ensure that once the ‘com.jFormTK’ Application end user has entered a value, it is not changed later by a run-time pre / post Processor operation.

    However, for completeness, the ‘com.jFormTK’  kernel has implemented the Overwrite" control as follows:

    Overwrite = false [default]: Never modify an ‘A’ field if the current value is not Null.
    Overwrite = true: Ignore the current ‘A’ value and replace [Overwrite] it with the given run-time Assignment formula.

    The following JFormField Method is used to control the "Overwrite" property:

    setOverwrite(boolean flag);

    NOTE: When the assignment String is set via a JFormField method,
                 e.g. 'setPostAssignment(assignmentString)', the overwrite flag is set to false.

    Generally, a ‘com.jFormTK’ Application designer would not use these flags. By default, a run-time Assignment shall be performed only when the field is first processed. However, here are some illustrations as to what will occur for combinations of the above flags:

Table of Recurrence / Overwrite Usage:
Recurrence Overwrite Effect...
False False DEFAULT, a run-time Assignment shall be performed only as the field is 1st focused and the 'A' field is null. Once the assignment is preformed, the assignment statement is cleared..
True True Every time the JFormField get focus, the assignment is processed.
True False Every time the JFormField get focus and the 'A' field is a 'null' the assignment is processed.
False True Assignment is performed only once regardless of the current value in the 'A' JFormField.

 

Top Return to com.jFormTK Overview

3. Run-time pre / post ‘IF’ Statement Processing…

On occasion there will be a need to perform run-time assignments "conditionally".

The following Methods are designed to perform "basic" Java Assignments either as a preProcessor OR a postProcessor operation.

public void setPreIf(‘Condition String’, ‘If Assignment String’, ‘Else Assignment String’)
public void setPreIf(‘Condition String’, ‘If Assignment String)
public void setPostIf(‘Condition String’, ‘If Assignment String’, ‘Else Assignment String’)
public void setPostIf(‘Condition String’, ‘If Assignment String)
     where the ‘Condition String’ is of the following format:

   Example 1: "Form1.test2 == Form1.test1", "If Assignment…", "Else Assignment…"
   - If the Form1 ‘test2’ JFormField Text Value is equal to the Form1 ‘test1’ JFormField Text Value,
     Then perform the Assignment described in the "If Assignment" String
     else perform the Assignment detailed by the "Else Assignment" String.

    Example 2: "Form1.test2 == Form1.test1", "If Assignment…"
    - Same as Example 1 except no ‘Else’ operation is given or required.

Conditional ‘If’ Recurrence / Overwrite Functions:

When executing a ‘Conditional’ if run-time ‘Assignment’ operation the "Recurrence" and "Overwrite" processing is the same as described above for the ‘com.jFormTK’ run-time ‘Assignment’ feature. The following ‘JFormField’ Methods are used to control the "Recurrence" and "Overwrite" processing:

    setPreIfRecurrence(boolean flag)
    setPreElseRecurrence(boolean flag)
    setPreIfOverwrite(boolean flag)
    setPreElseOverwrite(boolean flag)
    setPreIf(boolean Recurrence, boolean Overwrite)
    setPreIf(boolean flag)

Similar Methods exist for the run-time ‘Post’ Processor operations by substituting ‘pre’ with ‘post’ in the above method signatures.

Note: the 'then' and 'else' operations are "Mutually Exclusive, i. e. you can control the 'Recurrence / Overwrite' capabilities of each operation individually.

Top Return to com.jFormTK Overview

Using the ‘com.jFormTK’ Common DATA BASE in Assignments.

Additional run-time Assignment capability can be achieved by using the elements of the ‘com.jFormTK’ Common data base [appCommonDB]. The following example uses the 'appDB.commonDB' as a place holder in a formula to compute a "Running Sum" of the product of two numbers entered by an Application End User.

The formula is as follows:

Result2 = Sum (NumberQ * NumberR)"

To accomplish this formula there must be two "Run-Time" Processors activated.

1) Use a 'post' Processor on 'NumberR' to compute the product of 'NumberQ' and 'NumberR'. This product will then be saved in the 'appDB.commonDB' in an element named "Sum".

Code snippet:"
// Establish and initialize the Sum 'appDB.commonDB' Element...
   appDB.appCommonDB.addItem("Sum", "0");
// Set the 'post' Processor to compute the "Product"...
   NumberR.setPostAssignment("<c>Sum *= NumberQ * NumberR");

2) Use a 'pre' Processor on 'Result2' to display the current "Running Sum".

Code snippet:"
// Set a 'pre' Processor to display the current Running Sum in the 'Result2' Field...
   Result2.setPreAssignment("this = <c>Sum");

Additionally, the running sum of the two products can be accomplished using the target field, i.e. not using an element of the 'appDB.commonDB'.

Code snippet:"
// Compute the running sum and display the current value within the ‘Result2’ JFormField…
   Result2.setText("0");
   Result2.setPreAssignment("this += NumberQ * NumberR");
   Result2.setPreAssignment(true);

Top Return to com.jFormTK Overview

Unexpected Forward Referencing…

The ‘com.jFormTK’ System is designed to assist the end user to process each Application Form in a specific order. Ideally, the Application Forms will be processed in the order that they are added to the ‘com.jFormTK’ appForm Class in the Application main program class [i.e. the Class that extends the com.jFormTK basejFormTK class].

This "Form order" processing is encouraged via the com.jFormTK Application’s "Forms Selection Tree" of the "Controls" TAB Panel and the "Next Form" button of each Forms "Button Panel".

However, the com.jFormTK Application end user may select any form they want via the Controls TAB’s Panel "Forms Selection Tree".

This presents a potential problem for the "Assignment" function of the Java Form Tool Kit in that an Assignment formula may reference a field [JFormField] that has not yet been assigned a value by the Application end user.

If this situation occurs, the com.jFormTK shall present an "Assignment Incongruity" user interface window [below] that illustrates the field that has not been set yet and the "Assignment" formula that is being processed. In this window, the end user has the ability to input a value for the missing field and to "Mark" the current field so that it can be re-visited at a later time by the com.jFormTK Application end user.

ForwardReference.gif (46638 bytes)

The given value for the unprocessed Application field [JFormField] will be used as the "one Time" default for the field when the Application end user proceeds to that form. The given default is applied just once to enable the end user to modify the field at any subsequent time.

If the "Mark" operation is requested, then the ‘Recurrence’ and ‘Overwrite’ flags are automatically set so that the "Assignment" shall always be re-executed when the end user returns to update the associated field.

Top Return to com.jFormTK Overview

Developer Caution…

All the above processing is mandatory for a truly "Dynamic run-time" system. These features are ideal for setting defaults and for displaying running sums of tabular data, etc..

However, a word of "Caution" should be applied when using the "Dynamic run-time" features of the ‘com.jFormTK’ System. Do not use these capabilities to compute values that will be directly used in your ‘com.jFormTK’ Analysis or Reports. Parameters that are used in the "Analysis" or "Reports" phase of your Application should be calculated at the time the "Analysis" is performed or the "Report" is generated.

Generally, the "Analysis" and "Reports" are performed after the Application end user has entered all the pertinent data via the Application Forms processing. Note that the ‘com.jFormTK’ has the "Required Fields" capability that is designed to allow your "Analysis" / "Reports" processing to recognize any fields that do not have the required values entered yet before commencing the "Analysis" / "Reports" processing.

Top Return to com.jFormTK Overview

Restrictions…

The ‘com.jFormTK’ Developer may apply the above "Address Book", "Assignment" and "If" features once per each JFormForm ‘JFormField. These ‘com.jFormTK’ features are "mutually exclusive", therefore the ‘com.jFormTK’ Developer may use all three capabilities on each unique JFormField.

Note that the run-time ‘pre / post Processor operations are implemented in the following order:

If the run-time restrictions described above prevent you from accomplishing an Application "Requirement", then you may use the "‘preProcessor’ / ‘postProcessor’ Method override" capability to include Java code to dynamically perform the specified run-time processing.

Top Return to com.jFormTK Overview