BUTTONS:
Buttons are always defined as part of the "buttons" section in a form. Note that they cannot exist outside of this section. This means that buttons are always defined in the context of a form
or what is the same, buttons are always attached to a specific form.
Button UIDs in Prosciutto MUST start with the same 2 digits as in the form that contains such buttons.
For example a button in the form 11000, can have any UID ranging from 11001 to 11999.
The UID field is NOT mandatory. If you do not specify a UID, Prosciutto will create and assign a UID for each button in the same order of appearance of each one. starting at FORM uid + 4.
Please note also that Prosciutto default cache memory is up to
60 buttons per form (and up to 10 forms in memory at a time only). This can be modified by placing the values you need in the za_UI_api.initialize()
call in the class of your own that extends the za_UI_api class.
<button uid="11004">
<appearance>
<focusable>no</focusable> //Possible values are "yes" or "no". Default value if not declared is "yes".
<anchor>null</anchor> //Possible values "top" or "bottom" or "null"--> "top".
<editable>no</editable> //"yes" or "no". Default to "no". Editable buttons mean the text is editable by the user by pressing FIRE onits focus.
<x_coord>10</x_coord> //The left coordinate. Any positive integer between 0 and the screen width. "-1", "undef" or "undefined" is the default and means the zero position at left.
<y_coord>100</y_coord> //The upper coordinate. Any positive integer between 0 and the screen height. "-1", "undef" or "undefined" is the default and means the zero position at left.
<color_id>69001</color_id> //The UID for the color definition element that describes this button color.
<bkgimg_id img_alignment="left">-1</bkgimg_id> //The background image array that will be displayed inside this button. "-1", "undef", or "undefined" for no images (default).
<height>-1</height> //Height of button. "undefined" is the default value and Prosciutto will calculate the height based on fonts, bkg images and text.
<width>-1</width> //Width of button. "undefined" is the default, Prosciutto will make the button as wide as possible as per the form width.
//Other possible values are:
//"fit_text", or "fit_to_text", or just "fit": any of these values will make the button width be as wide as needed to make the contained text fit.
<btn_alignment>absolute</btn_alignment> //Button alignment. Can be "absolute" only if x_coord and y_coord are specified. Otherwise, "undef", "left", "right".
<font_unfocused>91001</font_unfocused> //font definition to use when the button is unfocused.
<rgb_text_unfocused>0000ff</rgb_text_unfocused> //color in RGB (hex) to use for the text when the button is unfocused.
<font_focused>91002</font_focused> //font definition to use when the button is focused.
<rgb_text_focused>ffffff</rgb_text_focused> //color in RGB (hex) to use for the text when the button is focused.
<text txt_alignment="left" txt_fx="scroll">Wait 3 sec or hit FIRE</text> //actual text to be shown in this button.
//the txt_alignment attribute may contain any of these values:
//"after_icon". In case the button has a background image that is being used as an icon to the button, Prosciutto will start drawing the text next to the icon (to the right of it)
//Other values: "left", "right", "hcentered".
<img_onfocus_id img_onfocus_alignment="left" >83001</img_onfocus_id> //the image array to be shown when this button is focused. This image array is printed as the last thing. (first background, then text, then image on focus).
<visualfx_onshow>none</visualfx_onshow> //visual effect when this button gains focus. "fadein", "fadeout", "movesmooth".
<visualfx_onhide>none</visualfx_onhide> //visual effect when this button loses focus. "fadein", "fadeout", "movesmooth".
<visualfx_smoothness>1</visualfx_smoothness> //how fast should the visual effect display changes. Measures in milliseconds.
</appearance>
<behavior>
<action_fire fire_param="null">null</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
<validator_mask validator_param="-1">-1</validator_mask> //Only usable for editable buttons. Validator masks are good for checking passwords, entered text lengths, etc.
<save_session>no</save_session> //saves session, means any OFF FOCUS action on this form collects data from the hidden param of this button among others
<hidden_param> </hidden_param> //hidden parameter, for server to get back and forth data
</behavior>
</button>
A note on "text_fx" attribute of the "text" tag:
This is can be any of these:
- "nofx": no effect will be applied to the text
- "scroll": the text, if its length exceeds the width of the button, will be scrolled at 1 second intervals whenver the button is focused, so
the user can actually read the text.
- "wrap" or any value greater than 2. This is for wrapper buttons, and it makes the button have as many lines as indicated by this number.
The default is 2 which is equal to "wrap", but you can make it 10, 20, 23, etc. whatever you may like. If the amount of lines declared here
should exceed the device screen height, Prosciutto will do any proper calculations on runtime and set this wrapper button to be as high/tall as it
can be as per its given context as in what templates are drawn and which buttons are already in the form.
Here's an example of how a wrapper button looks like (check the blueish part of the screen, containing long text):
A note on Validator mask:
Here's a list of all possible validator masks as defined in Prosciutto 2.0 beta:
public static final String K_ZA_UI_ATTR_VALIDATOR_MIN_LENGTH = "0"; //check that the text is at least of N minimum in length
public static final String K_ZA_UI_ATTR_VALIDATOR_MAX_LENGTH = "1"; //check that the text is at max of N in length
public static final String K_ZA_UI_ATTR_VALIDATOR_NUMERIC = "2"; //check that the text is a numeric value
public static final String K_ZA_UI_ATTR_VALIDATOR_MONTH = "4"; //check that the text is a month (1 to 12)
public static final String K_ZA_UI_ATTR_VALIDATOR_DATE = "8"; //check that the text is a valid date
public static final String K_ZA_UI_ATTR_VALIDATOR_EMAIL = "16"; //check that the text is a valid email address
public static final String K_ZA_UI_ATTR_VALIDATOR_URL = "32"; //check that the text is a valid URL
public static final String K_ZA_UI_ATTR_VALIDATOR_PASSWORD = "64"; //check that the text is a valid URL
Ok as you can see these are all base 2 numbers. The idea is that when represented in binary form, all these numbers can be sumed up and form new numbers.
That's the principle of the concept of "mask". Let's say you want a button to have a max length of 40. You'd just set these attributes like this:
<validator_mask validator_param="40">1</validator_mask>
Ok now let's say you want this field to be a password container, and also you want it to have a minimum lenght of 8, maximum of 10:
<validator_mask validator_param="8|10">65</validator_mask>
For a list of possible actions to define in the behavior section please check the form description.
Back to UI objects listing