The Prosciutto Project

a small footprint mobile application engine and browser - and open source!

Links:

Suscribe to The Prosciutto Project

Email address:

Check it out
The Prosciutto Project at Assembla
SVN
Trac

Are you a java developer and want to dive into java code? Find everything you need to build and compile Prosciutto HERE

If you don't know nothing about java or mobile programming, don't worry! You won't need it after all :).
This is all you need only in case you want to run on your computer the example applications given in this tutorial:
1) Prerequisites: download and install
1.1)JDK 1.6+
1.2)WTK 2.5.2 or newer

If you have a mobile phone, you don't even need to install these tools on your computer. Just point your phone's wap browser to the jad file URLs we are giving in this tutorial.

Continue reading!

Quick start guide for writing Prosciutto-based applications:

In this brief tutorial you will learn how to take an already prepared application (namely the demo application HelloProsciutto) and modify or even completely change the model.xml file embedded in it to make you own application.
All applications written in Prosciutto are defined by an XML file which is included in the final .jar file called "model.xml". What this means is, that the model.xml file is all you need in order to write an application in Prosciutto.

A simple Hello World can be written like this:

    
        <?xml version="1.0" encoding="UTF-8"?>
        <application steps="2">
            <form uid="11000">
                <buttons>
                    <button uid="11004">
                        <appearance>
                            <text>Hello World!</text> 
                        </appearance>
                    </button>
                </buttons>
            </form>
        </application>

All model.xml files start with the xml version declaration as in:


    <?xml version="1.0" encoding="UTF-8"?>

Furthermore, all model.xml files MUST include the following tag:


<application steps="2">
</application>

This tag indicates that whatever is between the "application" start and end tags is a definition of Prosciutto tags. The "steps" attribute is optional, and it indicates how many Prosciutto UI elements we are about to define in this model.xml. This is useful for indicating the user the progress of initialization while Prosciutto reads the model.xml file upon start. If you don't indicate the steps, or set the steps to zero, Prosciutto will loop from 0 to 100% on each step, starting again from zero when it reaches 100%.

Following is a list of possible elements as definable in Prosciutto, which might serve as a reference guide for you to build your own apps:

config: this indicates initialization parameters for Prosciutto. Optional, but good for optimization and testing.
form: the main UI object. A form is a container of other UI elements.
button: the base for all other UI objects.
template: a collection of buttons with a specified anchor (bottom, top). A template can be shared (used in) by many forms.
color: a definition of color behavior. This is where we describe how a given UI object will look like when focused, unfocused, etc.
timer: a timer will start at some given event and expire at some given time. The goal of a timer is to trigger some defined action upon expiration.
scrollbar: if a form contains several UI objects (i.e. buttons) and those cannot fit the device screen, you can always define the form to have a scrollbar which will
indicate the user if the form has more elements going down or up.
zagag url: this indicates the URL for Prosciutto to fo getch any object which is not found in the initial XML file.
default_form: this indicates Prosciutto which is the form to show first upon finishing initialization. If not defined, Prosciutto will try and show the
first defined form as found in the model.xml file
font: a font can be defined as per the native J2ME fonts.
image_array: an image array is a set of images that are shown/printed on screen from background to foreground in the Z axis. Each image
can have its own alignment and anchor, and it is always drawn regarding the context in which the image array is in. For example, if
a button has an background image array indicated, Prosciutto will draw this background image array inside the limits of the button itself.
Image arrays can be used in forms, buttons or templates.
onerror: the onerror tag indicates which action (other than default) should Prosciutto take in case a form
is not available to be visible and is required to be visible.

Let's start by taking the demo application HelloProsciutto and explaining what's in there.

Writing Prosciutto-based applications:

As stated before, all applications written in Prosciutto are defined by an XML file that is included in the jar file called "model.xml". If you are completely new to java applications, java microedition apps are also called MIDlets, and these are usually composed of two files: the JAD (Java Archive Descriptor) file, which extension is namely ".jad", and the JAR file (Java ARchive), which extension is ".jar".
The jad is a rather small file that contains some attribute:value pairs that are useful for describing the actual application.
Let's take a look at the HelloProsciutto.jad file (right-click and save as, then edit in your favorite text editor):


        MIDlet-Jar-URL: HelloProsciutto.jar
        MIDlet-Jar-Size: 81064
        MIDlet-Name: HelloProsciutto
        MIDlet-Vendor: The Prosciutto Project
        MIDlet-Version: 1.0
        MIDlet-1: HelloProsciutto, /icon.png, HelloProsciutto
        MIDlet-Description: HelloProsciutto
        MicroEdition-Configuration: CLDC-1.0
        MicroEdition-Profile: MIDP-1.0

For a reference of what each attribute means, you can check this link.
For now, you'll only need to know that the first two need to be accurate: the name of the jar file and the exact size of the jar file, expressed in bytes.

Now, let's take a look at the jar file (you can download it here, right-click and pick "save as").
The jar file is nothing but a compressed file, so you can open it with, for instance - and if you are using Windows - WinRar or WinZip.
This is how it looks at my computer:

inside the jar file

As you can see, the jar file contains the model.xml file. If you drag and drop it in any location you want, and open with your favorite text editor, you will see this is the exact model.xml that is shown above in this page.


            <?xml version="1.0" encoding="UTF-8"?>
            <application steps="2">
                <form uid="11000">
                    <buttons>
                        <button uid="11004">
                            <appearance>
                                <text>Hello World!</text> 
                            </appearance>
                        </button>
                    </buttons>
                </form>
            </application>

Ok now, if you run this application (double-click your jad file if you installed WTK, or download to your phone), it will look something like this:

Editing the model.xml file:

You can edit the model.xml and include, modify or delete anything you'd like, by following the instructions and refrence guide to each object described above.
Let's add one more button, and let's set the action for the FIRE key to be "exitapp" when the user selects it:


            <?xml version="1.0" encoding="UTF-8"?>
            <application steps="2">
                <default_form uid="11000"/>
                <form uid="11000">
                    <behavior>
                        <default_focus>11004</default_focus>
                    </behavior>
                    <buttons>
                        <button uid="11004">
                            <appearance>
                                <text>Hello World!</text> 
                            </appearance>
                        </button>
                        <button uid="11005">
                            <appearance>
                                <text>Exit the app</text> 
                            </appearance>
                            <behavior>
                                <action_fire fire_param="null">exitapp</action_fire>
                            </behavior>
                        </button>
                    </buttons>
                </form>
            </application>

If you noticed, what we added here is another button of id 11005, we've given the default appearance to it, only indicating that the button's text should be "Exit the app", and we have also overriden the default action for the FIRE key by setting it to actually exit the MIDlet when the button is pressed.
Moreover, we have added a "behavior" tag to the form, where we indicate which button should have the default focus. This way, as soon as the form is shown on the screen, the button that has the focus is button 11004, as stated in the model.xml file. Simple, right?

Note that, whenever you edit the xml file, you will need to include the new model.xml file into your HelloProsciutto.jar file. You can do this just by saving the model.xml, selecting it and drag and drop it into your Winzip window. With that, the HelloProsciutto.jar will change its size. What you need to do now is change the MIDlet-Jar-Size attribute in the HelloProsciutto.jad file to indicate the exact amount of bytes it now weights.


        MIDlet-Jar-Size: 81147

That's it! you can double-click your .jad file now and watch Prosciutto follow your guidelines as stated in your modified model.xml file.