org.sandev.basics.structs
Class UIFormInitializerStruct

java.lang.Object
  org.sandev.basics.structs.UIFormInitializerStruct

Direct Known Subclasses:

UIFormInitializer

public class UIFormInitializerStruct
extends java.lang.Object

Describes the initial state of a form when presented in a user interface.

Field Summary

protected int	action The action taken by the user.
protected java.lang.String	currClass Provides a workspace for storing the current class name, so that the appropriate interface form can be instantiated.
protected SandInstanceMessage	currInst Holds the current instance information for the class being edited.
protected SandCollectionMessage	findCollection The results of the current find action.
protected int	findCollIndex The index of the first element we are currently displaying.
protected int	findCollMaxDisplay Holds the number of collection items to display.
protected java.lang.String[]	findKeys Holds the unique keys from previous dataset pages to support backward traversal.
protected SandQueryMessage	findQuery Holds the query that generated the collection we are working with.
protected UIFormControlStruct	formControl Form control directives for the user interface.
protected int[]	modeStack The mode changes this form has gone through.
protected ErrorInfoStruct[]	outputText Text output to be displayed to the user.
protected java.lang.String[]	position The address of where we are in the overall message being edited.
protected SandInstanceMessage	rootMsg The root message we are working with.
protected UIFormQueryStruct	userQuery If specified, this query is displayed and processed while the form context information remains available.

Constructor Summary

UIFormInitializerStruct()

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

modeStack

protected int[] modeStack

The mode changes this form has gone through. There will always be at least one entry (the current mode) in this array, and there may be several levels depending on user actions.

enumerated constant values:

• UNDEFINED("UNKNOWN") = 0
  
• LISTING("LISTING") = 1
  
• UPDATING("UPDATING") = 2
  
• ADDING("ADDING") = 3
  
• FINDING("FINDING") = 4
  

stack accessor methods are generated for this field.

position

protected java.lang.String[] position

The address of where we are in the overall message being edited. A single message may actually be represented over several forms as the user traverses over contained elements. The position keeps track of the traversal path.

In print form, the position is represented as dot access notation from the root message, using array access indicators for access into array element references. So for example:

Configuration.initialData[0]

would indicate that we are currently viewing the first initialData element of the Configuration instance.

stack accessor methods are generated for this field.

currClass

protected java.lang.String currClass

Provides a workspace for storing the current class name, so that the appropriate interface form can be instantiated.

currInst

protected SandInstanceMessage currInst

Holds the current instance information for the class being edited. Having the new information here, and the original information in the msg variable, allows for appropriate implementation of cancel/add/edit behavior.

rootMsg

protected SandInstanceMessage rootMsg

The root message we are working with. Typically this is a collection resulting from a query, or a struct message we are editing directly. The rootMsg and the currInst are typically the same when the form is first displayed to the user.

findCollection

protected SandCollectionMessage findCollection

The results of the current find action.

findCollIndex

protected int findCollIndex

The index of the first element we are currently displaying. This is initially zero, and increases by the number of items to display per page. Used only for display of collection objects.

declared default value: 0

findCollMaxDisplay

protected int findCollMaxDisplay

Holds the number of collection items to display. The user pages forward or backward through the collection viewing (at most) findCollMaxDisplay object instances each time.

declared default value: 20
range match expression: > 1

findQuery

protected SandQueryMessage findQuery

Holds the query that generated the collection we are working with.

findKeys

protected java.lang.String[] findKeys

Holds the unique keys from previous dataset pages to support backward traversal.

stack accessor methods are generated for this field.

action

protected int action

The action taken by the user. If defined when the form is created, the associated action is set as the default (if possible). The defined values are consecutive to allow for mapping between the integer value and an array of text values in default action handling.

declared default value: UNDEFINED

enumerated constant values:

• UNDEFINED("undefined") = 0
  No action was taken.
• INIT("init") = 1
  Indicates that this context should be initialized.
• CUSTOM("custom") = 2
  Indicates a custom user action has been taken.
• DRILLDOWN("drilldown") = 3
  A "drilldown" action is a movement from a listed object instance to one of it's contained objects. Calls pushPosition.
• PARENT("return") = 4
  The opposite of a "drilldown". Calls popPosition or lastPosition.
• DEREF("deref") = 5
  A "deref" action is similar to a "drilldown" except it is a shift to the referenced object. There is no corresponding "parent" action and the position is simply changed to the new object. Most UI implementations provide some form of independent "back" action to return to the previous display.
• SELECT("select") = 6
  A "select" action is used in LISTING mode if we are in the process of adding a reference to an existing object instance, and we are displaying a collection of possible objects as the result of a query. The user can select one of the displayed instances to add.
• EDIT("edit") = 7
  If authorized, the user may select to edit the displayed instance. This action pushes the UPDATING mode onto the mode stack.
• ADD("add") = 8
  If authorized, the user may create a new object instance. An "add" action is used both for standalone objects and contained objects and pushes the ADDING mode onto the mode stack.
  

  For contained objects where the new object is part of an array, the position is updated to indicate the index of the element the new object should be inserted in front of. If the index given is -1, then the new element should be appended to the end of the existing array.

  An "add" action is also used for single contained elements or references. In this case no index is specified in the position variable since it is not an array.

• FIND("find") = 9
  If supported, the user may select to find new instances of the current object type or a different object type. This action shifts the mode to FINDING.
• CANCEL("cancel") = 10
  A "cancel" action means that the user wishes to abort the processing they started and return to where they were before. So for example if they are currently editing data, those edits should be discarded and the user should return to where they were before.
• SAVE("save") = 11
  

  A "save" action means write all changes to disk. This includes data in the current form, and the containing form information (if any). There would typically be an update message sent to the DataManager, or a file write from this action.
  

  When a "save" action is taken while UPDATING, the action will typically involve a mode transition to LISTING to emphasize that the edited information was written.
  

• PREVIOUS("previous") = 12
  If a collection object is being listed, and there are elements before the first element shown (either actually in the collection, or because the collection does not start with the first element), then the user has an option to list the previous page of collection elements.
• NEXT("next") = 13
  If a collection object is being listed, and there are more elements to display (either actually in the collection, or because the collection is not complete and more items can be retrieved), then the user has an option to list the next page of collection elements.
• PAGETO("page to") = 14
  If a collection object is being listed with more than one page of values available, then the user has the option to jump to a specific result page.
• DELETE("delete") = 15
  Delete the contained object or contained array element. This action is also used for deletion of the object being edited, in which case it exits updating mode on success.
• REMOVE("remove") = 16
  Remove the reference or referenced array element. The referenced object is not deleted.
• NEW("new") = 17
  Create a new instance of the referenced object type, and set the current reference to the new instance.
• MOVEUP("move up") = 18
  Move the contained array element up one position.
• MOVEDOWN("move down") = 19
  Move the contained array element down one position.
• OK("ok") = 20
  An "ok" action means the user is done with the current form. It essentially keeps the edited data in context, but does not write it to permanent storage. The reason for this is that a user may want to edit several parts of a single object that aggregates other objects. If they had to write the information to disk each time, they might get stuck trying to save an invalid object structure.
• EXPAND("expand") = 21
  Expand the array display to show the elements in it.
• COLLAPSE("collapse") = 22
  Collapse the array display to hide the elements from view
• HELP("help") = 23
  A "help" action indicates that the user would like additional information about the form they are working with. This also indicates the highest defined ACTION* constant.

userQuery

protected UIFormQueryStruct userQuery

If specified, this query is displayed and processed while the form context information remains available. This field should only be set when clarification or other user interaction is necessary. Use the outputText mechanism for informational statements, warnings, or errors in form processing.

outputText

protected ErrorInfoStruct[] outputText

Text output to be displayed to the user. This typically consists of warnings or errors that occur during normal form processing, such as violations of business logic enforced by back-end nodes.

formControl

protected UIFormControlStruct formControl

Form control directives for the user interface.

Constructor Detail

UIFormInitializerStruct

public UIFormInitializerStruct()