Form (universAAL Support Javadoc for Application Development 3.4.0 API)

java.lang.Object
- org.universAAL.middleware.rdf.Resource
- - org.universAAL.middleware.rdf.FinalizedResource
  - - org.universAAL.middleware.ui.rdf.FormElement
    - - org.universAAL.middleware.ui.rdf.Form

```
public class Form
extends FormElement
```
Forms can be used to describe dialogs in a modality- & layout-neutral way. A Form is a container of a set of FormControls that specify the structure of the dialog as it should be presented to human users. This implementation organizes the FormControls in three standard Groups:

The submits group

"buttons" that finish the whole dialog should be added to this group.

The ioControls group

all other form controls, no matter if input or output controls, or subgroups or even submits that trigger a sub-dialog should be added to this group.

The stdButton group

this group is reserved for a dialog management solution that has access to all dialogs and may be willing to add standard buttons beyond the application logic to reflect a system-wide behavior.

Forms support four dialog types:

Message

The simplest dialog type that can be used to specify a text message to be presented as a notification. No standard buttons in the above sense are allowed. The text message will be used to construct a SimpleOutput object that is added as the single child to the ioControls group. The submits group will be constructed automatically with two buttons based on the constants ACK_MESSAGE_DELET resp. ACK_MESSAGE_KEEP and LABEL_MESSAGE_DELET resp. LABEL_MESSAGE_KEEP. These two buttons can be used by a user to state either "ok, I got it, you can delete the message" or "please preserve the message for later check", respectively. Normally, applications do not need to subscribe for user decision in this regard, but if they want, then they must use the value returned by the method getDialogID() of the created form object, for subscribing to the UI bus.

System Menu

Reserved for a dialog management solution to present the system main menu. No submits group is allowed in this type of dialog.

Subdialog

A dialog related to a running dialog that must be "popped up" when the user presses a button in the originally running dialog without ending that running dialog. No standard buttons in the above sense are allowed. Applications must use instances of SubdialogTrigger for placing buttons that pop up a subdialog, instead of instances of Submit that should be used only for finishing the whole dialog. Submit instances must be added to the group returned by Form.getSubmits(), whereas SubdialogTrigger instances should be added to appropriate subgroups of the group returned by Form.getIOControls(). Subdialogs may affect the data to be used within the main dialog and hence the main dialog must be frozen until the application requests to continue with it. For this purpose, applications must call the method UICaller.resumeDialog(String,org.universAAL.middleware.rdf.Resource) of their output publisher after the subdialog finishes and they have processed its data and updated the form data of the main dialog. UI handlers may decide to render instances of SubdialogTrigger and Submit differently. Additionally, they may differentiate between events from these two types of buttons (and e.g. keep the parent dialog open until the subdialog loop is closed) or not. In any case, the middleware will re-dispatch the main dialog by calling UIHandler.handleUICall(org.universAAL.middleware.ui.UIRequest) of the output subscriber of the selected UI handler, as soon as the application requests to resume the dialog. In this way, the freezing and re-activating the main dialog is forced by the middleware even if the UI handler does not differentiate between events from instances of SubdialogTrigger and Submit.

Standard Dialog

All other forms must be constructed with this dialog type. All the three standard groups will be created automatically. Applications can get the standard groups "ioControls" and "submits" by calling the getIOControls() and getSubmits() methods respectively and construct their dialogs using these two groups as parent for their real form controls.

Author:

mtazari, Carsten Stockloew

See Also:
ftp://ftp.igd.fraunhofer.de/outgoing/mtazari/persona/dialogPackage.jpg

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ACK_MESSAGE_DELET` The submission ID if a user acknowledges that a dialog of type Message can be deleted.
`static String`	`ACK_MESSAGE_KEEP` The submission ID if a user acknowledges that a dialog of type Message must be preserved for later check.
`static Label`	`LABEL_MESSAGE_DELET` The label of a button associated with `ACK_MESSAGE_DELET` as submission ID that is automatically added to dialogs of type Message.
`static Label`	`LABEL_MESSAGE_KEEP` The label of a button associated with `ACK_MESSAGE_KEEP` as submission ID that is automatically added to dialogs of type Message.
`static String`	`MY_URI`
`static String`	`PROP_DIALOG_CREATED_BY` An optional property of form objects that can be associated with a string representing the name of the component that created the form.
`static String`	`PROP_DIALOG_CREATION_TIME` The point of time in which a form object is instantiated.
`static String`	`PROP_DIALOG_CURRENT_FOCUSED_CONTROL` An optional property of form objects to indicate which form control should receive the focus when UI handlers start to present the dialog.
`static String`	`PROP_DIALOG_DATA_ROOT` The `Resource` containing the form data.
`static String`	`PROP_DIALOG_TYPE` The type of the dialog represented by a form object as an instance of `DialogType`.
`static String`	`PROP_PARENT_DIALOG_URI` Applications must set this property for those form objects representing a dialog of type Subdialog using the value returned by `getDialogID()` on the parent form from which the subdialog was triggered.
`protected static String`	`PROP_ROOT_GROUP`
`static String`	`uAAL_DIALOG_NAMESPACE`

Fields inherited from class org.universAAL.middleware.ui.rdf.FormElement
PROP_APPEARANCE

Fields inherited from class org.universAAL.middleware.rdf.Resource
ANON_URI_PREFIX, blockAddingTypes, isXMLLiteral, ns_delim_index, PROP_RDF_FIRST, PROP_RDF_REST, PROP_RDF_TYPE, PROP_RDFS_COMMENT, PROP_RDFS_LABEL, PROP_SERIALIZATION_FULL, PROP_SERIALIZATION_OPTIONAL, PROP_SERIALIZATION_REDUCED, PROP_SERIALIZATION_UNDEFINED, PROP_uAAL_INVOLVED_HUMAN_USER, props, RDF_EMPTY_LIST, RDF_NAMESPACE, RDFS_NAMESPACE, TYPE_RDF_LIST, TYPE_RDFS_CLASS, uAAL_NAMESPACE_PREFIX, uAAL_SERVICE_NAMESPACE, uAAL_VOCABULARY_NAMESPACE, uri

Constructor Summary

Constructors
Modifier Constructor and Description

Form(String uri)
For usage by de-serializers only.

protected Form(String uriPrefix, int numProps)

Constructors
Modifier	Constructor and Description
	`Form(String uri)` For usage by de-serializers only.
`protected`	`Form(String uriPrefix, int numProps)`

Method Summary

Methods
Modifier and Type	Method and Description
`XMLGregorianCalendar`	`getCreationTime()` Returns the time at which the first time the form was created by an application.
`FormControl`	`getCurrentFocusedControl()`
`Resource`	`getData()`
`String`	`getDialogCreator()`
`String`	`getDialogID()` Returns the URI of this form object as its global unique ID.
`DialogType`	`getDialogType()`
`Group`	`getIOControls()` Returns the standard group for UI controls in this form.
`String`	`getMessageContent()` Returns the text message originally set if this form was created by `newMessage(String, String)`.
`Resource`	`getParentDialogResource()` Returns the parent dialog as an empty resource with `PROP_PARENT_DIALOG_URI` as its URI.
`String`	`getParentDialogURI()`
`Output[]`	`getSharedOutputs()` Returns all the `Output` controls contained in the ioControls group (see the above documentation of this class concerning the standard groups within forms) that are likely to be relevant for human users in order to decide what to do with this dialog.
`Group`	`getStandardButtons()` Returns the pre-defined group of standard buttons in this form.
`String`	`getStandardButtonsDialogID()` Reserved for use by a dialog management solution that has access to all dialogs and adds standard buttons beyond the application logic to reflect a system-wide behavior.
`Group`	`getSubmits()` Returns the standard group for submit buttons in this form.
`String`	`getTitle()` Returns the form title reflecting the intent of this dialog and originally set when constructing this form object.
`boolean`	`isMessage()` Answers if this form object is created by `newMessage(String, String)`.
`boolean`	`isStandardDialog()` Answers if this form object is created by `newDialog(String, Resource)`.
`boolean`	`isSubdialog()` Answers if this form object is created by `newSubdialog(String, String)`.
`boolean`	`isSystemMenu()` Answers if this form object is created by `newSystemMenu(String)`.
`static Form`	`newDialog(String formTitle, Resource dataRoot)` Constructs and returns a new form object representing an empty dialog of type `Standard Dialog` with proper initial configuration.
`static Form`	`newDialog(String formTitle, String dataRootType)` An alternative for `newDialog(String, Resource)` to be used if no specific data root is going to be specified but only the URI of its type.
`static Form`	`newMessage(String formTitle, String message)` Constructs and returns a new form object representing a `Message` dialog that is ready to publish within an `UIRequest`.
`static Form`	`newSubdialog(String formTitle, String parentDialogURI)` Constructs and returns a new form object representing an empty dialog of type `Subdialog` with proper initial configuration.
`static Form`	`newSystemMenu(String formTitle)`
`FormControl`	`searchFormControl(String formControlURI)` look for a FormControl within the form with the given URI.
`void`	`setCurrentFocusedControl(FormControl fc)`
`void`	`setDialogCreator(String creator)`
`void`	`substituteData(Resource pr)` Reserved for usage by the middleware.

Methods inherited from class org.universAAL.middleware.ui.rdf.FormElement
addAppearanceRecommendation, getAppearanceRecommendations

Methods inherited from class org.universAAL.middleware.rdf.FinalizedResource
addType, getLocalName, getNamespace, getProperty, getPropertyURIs, getType, getTypes, getURI, hasQualifiedName, isAnon, numberOfProperties

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - uAAL_DIALOG_NAMESPACE
```
public static final String uAAL_DIALOG_NAMESPACE
```
    See Also:
    Constant Field Values
  - MY_URI
```
public static final String MY_URI
```
    See Also:
    Constant Field Values
  - ACK_MESSAGE_DELET
```
public static final String ACK_MESSAGE_DELET
```
    The submission ID if a user acknowledges that a dialog of type Message can be deleted.
    
    See Also:
    Constant Field Values
  - ACK_MESSAGE_KEEP
```
public static final String ACK_MESSAGE_KEEP
```
    The submission ID if a user acknowledges that a dialog of type Message must be preserved for later check.
    
    See Also:
    Constant Field Values
  - LABEL_MESSAGE_DELET
```
public static final Label LABEL_MESSAGE_DELET
```
    The label of a button associated with ACK_MESSAGE_DELET as submission ID that is automatically added to dialogs of type Message.
  - LABEL_MESSAGE_KEEP
```
public static final Label LABEL_MESSAGE_KEEP
```
    The label of a button associated with ACK_MESSAGE_KEEP as submission ID that is automatically added to dialogs of type Message.
  - PROP_DIALOG_CREATED_BY
```
public static final String PROP_DIALOG_CREATED_BY
```
    An optional property of form objects that can be associated with a string representing the name of the component that created the form.
    
    See Also:
    Constant Field Values
  - PROP_DIALOG_CREATION_TIME
```
public static final String PROP_DIALOG_CREATION_TIME
```
    The point of time in which a form object is instantiated. This property is set automatically with the value returned by TypeMapper.getCurrentDateTime().
    
    See Also:
    Constant Field Values
  - PROP_DIALOG_CURRENT_FOCUSED_CONTROL
```
public static final String PROP_DIALOG_CURRENT_FOCUSED_CONTROL
```
    An optional property of form objects to indicate which form control should receive the focus when UI handlers start to present the dialog. It will be set automatically by the middleware whenever a running dialog is cut so that a seamless resumption of the dialog at a later point in time is guaranteed. UI handlers should check if this property is set. If yes, then they must simulate their logic of presenting the form until they reach the form control given as value of this property. At this point they can prompt the user for the next data entry.
    
    See Also:
    Constant Field Values
  - PROP_DIALOG_DATA_ROOT
```
public static final String PROP_DIALOG_DATA_ROOT
```
    The Resource containing the form data. Form data can be accessed using property paths; UI handlers, however, do not need to explicitly access this data normally, because they normally deal only with data associated with form controls that can be retrieved by calling FormControl.getValue() or set by calling Input.storeUserInput(Object). Applications may create an instance of Resource and set both their hidden data and initial data associated with the form controls using Resource.setPropertyPath(String[], Object) . They can retrieve the form data from ui responses by calling UIResponse.getUserInput(String[]) . Note: initial data to be associated with form controls can be set through their constructors, as well.
    
    See Also:
    Constant Field Values
  - PROP_DIALOG_TYPE
```
public static final String PROP_DIALOG_TYPE
```
    The type of the dialog represented by a form object as an instance of DialogType. See the above documentation of this class regarding the types of dialogs supported.
    
    See Also:
    Constant Field Values
  - PROP_PARENT_DIALOG_URI
```
public static final String PROP_PARENT_DIALOG_URI
```
    Applications must set this property for those form objects representing a dialog of type Subdialog using the value returned by getDialogID() on the parent form from which the subdialog was triggered.
    
    See Also:
    Constant Field Values
  - PROP_ROOT_GROUP
```
protected static final String PROP_ROOT_GROUP
```
    See Also:
    Constant Field Values
- Constructor Detail
  - Form
```
public Form(String uri)
```
    For usage by de-serializers only.
  - Form
```
protected Form(String uriPrefix,
    int numProps)
```
    Parameters:
    uriPrefix -
    numProps -
- Method Detail
  - newDialog
```
public static Form newDialog(String formTitle,
             Resource dataRoot)
```
    Constructs and returns a new form object representing an empty dialog of type Standard Dialog with proper initial configuration. See also the discussion of dialog types in the above documentation of this class.
    
    Parameters:
    formTitle - The form title giving the intent of the dialog.
    dataRoot - The Resource containing the form data. It can be null, if no hidden data was prepared by the application and any initial value to be associated with form controls is going to be set through their constructors. See also PROP_DIALOG_DATA_ROOT.
    
    Returns:
    A newly constructed form object representing an empty dialog of type Standard Dialog with proper initial configuration.
  - newDialog
```
public static Form newDialog(String formTitle,
             String dataRootType)
```
    An alternative for newDialog(String, Resource) to be used if no specific data root is going to be specified but only the URI of its type.
  - newMessage
```
public static Form newMessage(String formTitle,
              String message)
```
    Constructs and returns a new form object representing a Message dialog that is ready to publish within an UIRequest. See also the discussion of dialog types in the above documentation of this class.
    
    Parameters:
    formTitle - The form title giving the intent of the dialog.
    message - The text of the message.
    
    Returns:
    A newly constructed form object representing a Message dialog that is ready to publish within an UIRequest.
  - newSubdialog
```
public static Form newSubdialog(String formTitle,
                String parentDialogURI)
```
    Constructs and returns a new form object representing an empty dialog of type Subdialog with proper initial configuration. See also the discussion of dialog types in the above documentation of this class. To set hidden form data, you must first get the data root using getData() and then add your data calling its method Resource.setPropertyPath(String[], Object) .
    
    Parameters:
    formTitle - The form title giving the intent of the dialog.
    parentDialogURI - The ID of the parent dialog. See also PROP_PARENT_DIALOG_URI.
    
    Returns:
    A newly constructed form object representing an empty dialog of type Subdialog with proper initial configuration.
  - newSystemMenu
```
public static Form newSystemMenu(String formTitle)
```
  - getCreationTime
```
public XMLGregorianCalendar getCreationTime()
```
    Returns the time at which the first time the form was created by an application.
    
    See Also:
    PROP_DIALOG_CREATION_TIME
  - getCurrentFocusedControl
```
public FormControl getCurrentFocusedControl()
```
    See Also:
    PROP_DIALOG_CURRENT_FOCUSED_CONTROL
  - getData
```
public Resource getData()
```
    See Also:
    PROP_DIALOG_DATA_ROOT
  - getDialogCreator
```
public String getDialogCreator()
```
    See Also:
    PROP_DIALOG_CREATED_BY
  - getDialogID
```
public String getDialogID()
```
    Returns the URI of this form object as its global unique ID.
  - getDialogType
```
public DialogType getDialogType()
```
    See Also:
    PROP_DIALOG_TYPE
  - getIOControls
```
public Group getIOControls()
```
    Returns the standard group for UI controls in this form. See also the above documentation of this class concerning the standard groups within forms.
  - getMessageContent
```
public String getMessageContent()
```
    Returns the text message originally set if this form was created by newMessage(String, String). Otherwise, it returns null.
  - getParentDialogResource
```
public Resource getParentDialogResource()
```
    Returns the parent dialog as an empty resource with PROP_PARENT_DIALOG_URI as its URI.
  - getParentDialogURI
```
public String getParentDialogURI()
```
    See Also:
    PROP_PARENT_DIALOG_URI
  - getSharedOutputs
```
public Output[] getSharedOutputs()
```
    Returns all the Output controls contained in the ioControls group (see the above documentation of this class concerning the standard groups within forms) that are likely to be relevant for human users in order to decide what to do with this dialog. The assumption is that there may be other Output controls specific to certain submissions possible within this dialog, which will be ignored by this method as they do not represent shared info.
  - getStandardButtons
```
public Group getStandardButtons()
```
    Returns the pre-defined group of standard buttons in this form. See also the above documentation of this class concerning the standard groups within forms.
  - getStandardButtonsDialogID
```
public String getStandardButtonsDialogID()
```
    Reserved for use by a dialog management solution that has access to all dialogs and adds standard buttons beyond the application logic to reflect a system-wide behavior.
  - getSubmits
```
public Group getSubmits()
```
    Returns the standard group for submit buttons in this form. See also the above documentation of this class concerning the standard groups within forms.
  - getTitle
```
public String getTitle()
```
    Returns the form title reflecting the intent of this dialog and originally set when constructing this form object.
  - isStandardDialog
```
public boolean isStandardDialog()
```
    Answers if this form object is created by newDialog(String, Resource).
    
    See Also:
    PROP_DIALOG_TYPE
  - isMessage
```
public boolean isMessage()
```
    Answers if this form object is created by newMessage(String, String).
    
    See Also:
    PROP_DIALOG_TYPE
  - isSubdialog
```
public boolean isSubdialog()
```
    Answers if this form object is created by newSubdialog(String, String).
    
    See Also:
    PROP_DIALOG_TYPE
  - isSystemMenu
```
public boolean isSystemMenu()
```
    Answers if this form object is created by newSystemMenu(String).
    
    See Also:
    PROP_DIALOG_TYPE
  - setCurrentFocusedControl
```
public void setCurrentFocusedControl(FormControl fc)
```
    See Also:
    PROP_DIALOG_CURRENT_FOCUSED_CONTROL
  - setDialogCreator
```
public void setDialogCreator(String creator)
```
    See Also:
    PROP_DIALOG_CREATED_BY
  - substituteData
```
public void substituteData(Resource pr)
```
    Reserved for usage by the middleware.
  - searchFormControl
```
public FormControl searchFormControl(String formControlURI)
```
    look for a FormControl within the form with the given URI.
    
    Parameters:
    formControlURI -
    
    Returns:
    the FormControl or null if not found.

Class Form

Field Summary

Fields inherited from class org.universAAL.middleware.ui.rdf.FormElement

Fields inherited from class org.universAAL.middleware.rdf.Resource

Constructor Summary

Method Summary

Methods inherited from class org.universAAL.middleware.ui.rdf.FormElement

Methods inherited from class org.universAAL.middleware.rdf.FinalizedResource

Methods inherited from class org.universAAL.middleware.rdf.Resource

Methods inherited from class java.lang.Object

Field Detail

uAAL_DIALOG_NAMESPACE

MY_URI

ACK_MESSAGE_DELET

ACK_MESSAGE_KEEP

LABEL_MESSAGE_DELET

LABEL_MESSAGE_KEEP

PROP_DIALOG_CREATED_BY

PROP_DIALOG_CREATION_TIME

PROP_DIALOG_CURRENT_FOCUSED_CONTROL

PROP_DIALOG_DATA_ROOT

PROP_DIALOG_TYPE

PROP_PARENT_DIALOG_URI

PROP_ROOT_GROUP

Constructor Detail

Form

Form

Method Detail

newDialog

newDialog

newMessage

newSubdialog

newSystemMenu

getCreationTime

getCurrentFocusedControl

getData

getDialogCreator

getDialogID

getDialogType

getIOControls

getMessageContent

getParentDialogResource

getParentDialogURI

getSharedOutputs

getStandardButtons

getStandardButtonsDialogID

getSubmits

getTitle

isStandardDialog

isMessage

isSubdialog

isSystemMenu

setCurrentFocusedControl

setDialogCreator

substituteData

searchFormControl