FORMS:
A Form has 3 sections, including "appearance", "behavior" and "buttons". The appearance and behavior sections describe attributes that have to do
with the look and feel and the behavior defined for each form respectively, while the "buttons" section describes a collection of buttons that have
been defined and attached to this form.
None of this sections is mandatory, but of course it would be nonsense to have a form with no description of how to look like or how to behave. This
will be an empty container, of no use at all. You might want to use something like this in the case of connection-oriented applications, because buttons
and forms can have a hidden parameter that is sent to the server (but not shown to the user, of course). This might be come in handy in these situations,
and that's why it is allowed to have empty forms. Note that if you tell Prosciutto to "goto" such a form, it will show default values for its look and
feel, and it will look like a blank screen to the user. Also note that not defining any behavior attributes for this form will end up with the user
not being able to get out of this form, as Prosciutto will not know what to do with users button presses or keystrokes.
The only mandatory field is the "uid" attribute. Form UIDs in Prosciutto MUST always be multiples of 1000. For example 10000, 11000, 12000, 93000, etc.
<form uid="11000">
<appearance>
<template_id>-1</template_id> //if using template, template idx
<focusable>yes</focusable> //focusable object
<x_coord>-1</x_coord> //starting x coord //form x start coord (-1 or undefined means 0)
<y_coord>-1</y_coord> //starting y coord //form y start coord (-1 or undefined means 0)
<height>-1</height> //heigth of form //form height (-1 or undefined means full heigth)
<width>-1</width> //width of form //form width (-1 or undefined means full width)
<color_id>69020</color_id> //form color definition
<bkgimg_id>81001</bkgimg_id> //background image array id
<layout>vertical</layout> //elements layout (always vertical)
<distribution>even</distribution> //elements distribution (always even)
<pixels_in_between_elements>2</pixels_in_between_elements> //pixels between each element in form
<visualfx_onshow>none</visualfx_onshow> //visual effect to execute on show (fadein, fadeout)
<visualfx_onhide>fadeout</visualfx_onhide> //visual effect to execute on hide (fadein, fadeout)
<visualfx_smoothness>1</visualfx_smoothness> //visual effect smoothness: repetition speed or delay among changes in ms
</appearance>
<behavior>
<default_focus>11000</default_focus> //default focus. Prosciutto will place the focus on this element when the form shows up.
<action_fire fire_param="12000">goto</action_fire> //action when FIRE is hit and this form element has the focus.
<action_up up_param="null">default</action_up> //action if UP key pressed when focused
<action_down down_param="null">default</action_down> //action if DOWN key pressed when focused
<action_left left_param="null">default</action_left> //action if LEFT key pressed when focused
<action_right right_param="null">default</action_right> //action if RIGHT key pressed when focused
<timer_id startat="onshow">71001</timer_id> //TIMER id. This indicates if a certain event on this form should trigger a specific timer.
<save_session>no</save_session> //saves session, means any OFF FOCUS action on this form collects data from all hidden params.
//Possible values are:
//"erase": erases the current session string,
//"save_allform": saves all the hidden values in all buttons belonging to this form
//"save_only_me": erases the current session string and creates a new one conatining this form's hidden value
//"erase_allform": erases all session strings belonging to this form only (leaves the session string with whatever other values belong to other forms)
<hidden_param> </hidden_param> //hidden parameter, for server to get back and forth data
<allows_delete>yes</allows_delete> //tells if this form can be deleted or not in case Prosciutto needs memory
</behavior>
Here's a list of possible actions:
"null" null indicates that no action is to be taken. In Prosciutto this plays an alert sound only.
"goto" goto indicates that another form should be shown on screen and get the focus. A stack is kept so we can use "goback" actions in the destination form.
"goto_absolute" goto_absolute is the same as "goto", but it doesn't keep track of what is the form that called the destination.
"exit_app" exits the application.
"exitapp" exits the application.
"exit" exits the application.
"open_url" opens the native browser in the specified URL.
"goback" puts the caller of the actual form on screen and sets the focus on the previously focused element in such a form.
If the action parameter is set to some number "n", the goback action actually pulls n forms from the stack and shows such form.
For example:
<action_fire fire_param="2">goback</action_fire>
This will make the form that called the actual form visible (instead of just making this form's caller visible)
"change_button_state_and_show_its_form" this action changes the text and hidden values of a given button to be the same as the parameter of this action, and the form where this button belongs to is shown on the screen.
"change_form_state_and_show_form" similar to the above action, for form elements.
"set_attr" set a specific element's attribute to the given value. You should understand the internals of Prosciutto's attribute indexing.
"set_cookie" sets the cookie string to a given value. The cookie string is only valuable for connection-oriented applicaitons to send information back and forth from the server.
"goto_and_show_in_dropdown_mode" this action is useful for forms that do not occupy the whole device screen. This action reads the actual element's X and Y coordinates (upper left corner) and copies such
coordinates to the destination form, giving the feel of the destination form appearing as a drop down menu.
"rethink_heights" this action is useful only when new forms are fetched. All heights for all UI elements are recalculated in order to fit the device screen where Prosciutto is running on.
"delete" this action tells Prosciutto to delete a specific Prosciutto element from memory, as long as the element is declared to be deleteable.
"forced_delete" this action forces Prosciutto to delete a specific Prosciutto element from memory, no matter if the object has been declared to be non-deleteable.
"avoid_deletion" this action tells Prosciutto to avoid, if possible, the deletion of an element even if it was declared to be deleteable. Useful for short periods of time where you want to keep certain objects in memory.
"set_dflt_form" this action sets the default form to be that of the UID indicated in the action parameter.
"set_zajag_url" this action sets the ZAJAG URL. This is the URL where Prosciutto is going to ask for an element that cannot be found in memory.
"set_db_flag_on" Useful only if you are using the Persistence Framework. Switches the DB ON in the sense any data coming from the server will be saved in the DB for persistence.
"set_db_flag_off" Useful only if you are using the Persistence Framework. Switches the DB OFF, and no data coming from the server will be saved to the DB until a "switch ON" action is received.
"set_orientation" Sets the screen orientation. 0, 90, 180 and 270 degrees are the possible values. (try it out, it's nice!). Need to call set_orientation_repaint immediately after.
"set_orientation_repaint" Refreshes the screen with the new orientation set.
"switch_orientation_repaint" Switches the current orientation to (curr_orientation + 90) degrees. Loops, as in in 270+90 = 0.
"set_language" Sets the native language as per the specified value in the action parameter. Currently only English ("0"), Spanish ("1") and Portuguese ("2") are supported.
"set_encryption_key" Sets the encryption key. Only useful when using Bouncycastle DES or AES algorithms.
"set_focus_on_element" Sets the focus on a given element as per the ID indicated in the action parameter.
"get_location" Reads the current location (latitude, longitude) from the underlying platform LBS capabilities if available. The action parameter
may indicate a form ID where to go to, as soon as Prosciutto is finished fetching the current location. In such form, you could have a button's text
using @@latitude@@ and @@longitude@@ reserved keywords, so the real values would be replaced in such text and shown on screen.
"repaint" Performs a repaint of the current visible form. Not usually needed.
"trigger_timer" Loads and triggers the timer ID indicated in the action parameter.
"reset_debug_string" In the debug version, resets the debug string with the collected data.
"act_default" Default action. For keystrokes, lets Prosciutto handle what to do.
"act_dflt" Default action. For keystrokes, lets Prosciutto handle what to do.
"act_def" Default action. For keystrokes, lets Prosciutto handle what to do.
"circular_nav" Circular navigation. In the case of templates, the very top button or very bottom button in a template should have this action set for their "KEY_UP" and "KEY_DOWN" actions respectively.
"custom" Custom defined. The developer should tell Prosciutto what to do when a given action happens on the focused element. The functionality can be overriden by writing a callback in runActionExecute().
"cust" Same as above.
"play" This is for playing/pausing audio/video files with the MMAPI (one at a time). The action parameter takes the full path to the file and the file MIME type, separated by a half pipe. See the example below.
Audio
<action_fire fire_param="/test.mid|audio/midi">play</action_fire>
Video
Note that video also takes 4 optional parameters, which are, in order:
X coordinate to position the video player on the screen
Y coordinate to position the video player on the screen
Width of the player window
Height of the player window
In this example, we are placing the video window at x=28, y=116, and its size is 185x140.
<action_fire fire_param="http://www.prosciuttoproject.org/jonastest/jonas.3gp|video/3gpp|28|116|185|140">play</action_fire>
"stop" Stops the currently playing audio/video file.
"exec_hecl" Executes a Hecl script. There are two ways to indicate this: you can either specify the name of your hecl script file here, as in "/script.hcl" (note the beginning
slash is important) or, if your Hecl script is rather small, you can just write it as the value of the parameter attribute of this tag. In this latter case, the Hecl script must come in the action
parameter and always start with a "hecl:" prefix.
For example: <action_fire fire_param='hecl:puts "Hello, World"'>exec_hecl</action_fire>
Or, for a file: <action_fire fire_param='/script.hcl'>exec_hecl</action_fire>
"exec_hecl_blocking" Executes a Hecl script and holds on until the Hecl interpreter finishes execution.
"stop_hecl" Stops any Hecl script being executed and frees any resources taken by the Hecl interpreter.
Click here for a detailed description of available Prosciutto commands in Hecl