Tutorial 1 How to Create a Simple Screen

What you will learn in this Tutorial

How to Create New Screen

How to set Screen UI Properties - Background, Title Bar, Orientation, Scroll

Download Source Code - Tutorials - Source for this tutorial is in appemble-tutorial-screen
Learn more FAQ
Good Read How to create your own android app , XMADL

Screen basics

Every page that you see on the device is a screen. Each screen is defined in an xml file. Screen is defined by <screen> </screen> tags. Every screen must have a name. Screen has many properties like background, title bar, orientation, scrolling, data sources which are defined by attributes of <screen>. Learn more about the screen attributes. Screen is composed of controls for example TEXT, EDIT, BUTTONS etc. Events and actions can be attached to a screen and its controls.

Create New Screen

Create a screen called myhome. To do that, in your project’s app-def folder copy home.xml to myhome.xml. It will define the user interface of the screen called myhome.

In this screen, display the text Home - Hello World!. For this create a TEXT control, define its position, dimensions, font properties and its value.

<screens>
    <screen name="myhome" screen_type="SCREEN" >
        <control type="TEXT" x="10" y="30" width="80" height="25"
                appearance_name="black" default_value="Hello World!"/>
    </screen>
</screens>

The display properties of the text are determined by appearance_name. To define different appearances, create a new file or edit a file called “appearance.xml” in the app-def folder:

In appearance.xml, create a new appearance. This appearance name can be reused for any control in the app.

<appearances>
    <appearance name="black" font_family="Sans-Serif" font_name="Helvetica"
            font_size="5" font_color="#000000" background_color="" alpha="0"
            justify="CENTER"  font_style_bold="1" font_style_emboss="1"/>
</appearances>

Your first screen is complete! Now declare that myhome screen is the first screen to be displayed. This is declared in a file in your app-def folder called application.xml

<screen_deck name="appemble-tutorial-1" version="1.0"
    short_description="Appemble
    Tutorial App" long_description="Appemble tutorial app" size="1024"
    publisher_name="Appemble" publish_date="2012-05-31"
    starting_screen_name="myhome"/>

Note

  • xml file name for a screen can be any name.
    • Starting_screen_name looks for screen name = “myhome”.

Now your app is ready for launch.

Android - Right click on the project and click on Run as Android application.

iOS - Click on Product -> Run.

../_images/helloworld_nobackground.png

Screen UI Properties - Background, Title Bar, Orientation, Scroll

../_images/screen.png

Screen background

UI Properties are User Interface properties which define the look and feel or theme of the screen. Right now myhome screen has plain background. Add a background image.

Android - Copy the image file to yourproject/assets folder.

iOS - Copy the image file to yourproject/Project/Resources/images folder

<screens>
    <screen name="myhome" screen_type="SCREEN" background="tu_background.png">
        <control type="TEXT" x="10" y="30" width="80" height="25"
            appearance_name="black" default_value="Hello World!"/>
    </screen>
</screens>

Run the app.

Android - Right click on the project and click on Run as Android application.

iOS - Click on Product -> Run.

You will see the screen with background.In the sample code above, screen background is an image “tu_background.png” background property can also take hex color code for example background=”#DDDDDD”

../_images/helloworld_background.png

To learn the difference between <screens> and <screen> tags read here

Title bar background

Add titlebar background for the screen.

  • Step 1: Define a new attribute title_background="tu_titlebar.png"

  • Step 2: Define <title_controls/>

  • Step 3: Android - Copy the image file to yourproject/assets folder

    iOS - Copy the image file to yourproject/Project/Resources/images folder

Note

titlebar_background can also take hex color codes.

<screens>
    <screen name="myhome" screen_type="SCREEN" background="tu_background.png"
            title_background="tu_titlebar.png">
        <title_controls>
            <control type="TEXT" x="0" y="2" width="100" height="7" default_value="Home"
                    appearance_name="white" data_type="VARCHAR"/>
        </title_controls>

        <controls>
            <control type="TEXT" x="10" y="30" width="80" height="25"
                    appearance_name="black" default_value="Hello World!"/>
        </controls>
    </screen>
</screens>

Run the app. Now myhome screen has titlebar added. On the title bar there is a text control with value=”Home”.

../_images/helloworld_titlebar.png

Orientation

Set initial orientation for a screen. For example if initial_orientation = "PORTRAIT", then this screen will open in PORTRAIT mode.

You can also set allowed orientation for the screen. For example allowed_orientation can have values PORTRAIT or LANDSCAPE or BOTH. The screen will repaint itself according to the orientation of the device. If the value is either PORTRAIT or LANDSCAPE then the screen will remain in that mode and will not adapt to the orientation of the phone.

<screens>
    <screen name="myhome" screen_type="SCREEN" background="tu_background.png"
            title_background="titlebar.png" initial_layout="PORTRAIT"
            allowed_layouts="BOTH">
        <control type="TEXT" x="10" y="30" width="80" height="25"
                appearance_name="black" default_value="Hello World!"/>
    </screen>
</screens>

Scroll bar

You can set VERTICAL or HORIZONTAL or SCROLL_BOTH_WAYS scroll bars in the screen.

<screens>
    <screen name="myhome" screen_type="SCREEN" background="tu_background.png"
            title_background="tu_titlebar.png" initial_layout="PORTRAIT"
            allowed_layouts="BOTH" scroll="VERTICAL">
        <control type="TEXT" x="10" y="30" width="80" height="25"
                appearance_name="black" default_value="Hello World!"/>
    </screen>
</screens>

Note

  • You will not see the VERTICAL scroll bar unless the screen content is more than the height of the device screen.
  • You will not see the HORIZONTAL scroll bar unless the screen content is more than the width of the device screen.
  • For BOTH bars to show, the content has to more than the device screen width and height.

Global App UI properties

Global screen background

If you want to set the background for all the screens in the app, then edit application level UI properties in application.xml in app-def folder.

<screen_deck name="appemble-tutorial" version="1.0"
     short_description="Appemble Tutorial  App"
     long_description="Appemble tutorial app"
     size="1024" publisher_name="Appemble" publish_date="2012-05-31"
     starting_screen_name="myhome" background="tu_background.png"/>

Once this property is set, you do not need to set the background for every screen. But you can override it by defining a different background for a particular screen. background property can take hex color code as its value.

Global Title bar background

To set the title bar for the entire app, you can declare the title_bar in application.xml

<screen_deck name="appemble-tutorial" version="1.0"
    short_description="Appemble Tutorial  App"
    long_description="Appemble tutorial app"
    publisher_name="Appemble" publish_date="2012-05-31"
    starting_screen_name="myhome" background="tu_background.png"
    title_background="tu_titlebar.png"/>

Once this property is set, you do not need to set title bar background for every screen. But you can override it by defining a different title bar for a particular screen. title_background property can take hex color code as its value for example #000000 (for black) To learn about hex color code, click here.

Download and Run Tutorials

This chapter uses source code from appemble-tutorial-screen. If you have not downloaded tutorial source code, click on Download Source Code - Tutorials

Android - Right click on appemble-tutorial-screen and click on Run as Android application.

iOS - Select scheme appemble-tutorial-screen and iPhone x.x simulator. Click on Product -> Run.

FAQ

Even if I have set the background for the entire app, is it possible to override background for a particular screen?

Yes. In the app-def file that defines the <screen> add an attribute called “background”. For ex. <screen background=”image file name.png”. Make sure the file exists in the asset folder.


Where should I put my image files, so that they can be read locally from the device?

All images for the app go in the assets folder of the project. The framework will look for an image in the assets folder. If you want to create a sub-folder under assets, that is also allowed.


Can I download the background image from the internet?

Yes. Just give background=”<url>” where <url> can be http://www.example.com/background.jpg. Note: Though the framework allows it, it is generally not recommended as it slows down the painting the screen.


What kind of controls can go on Title Bar? Is there a limit to the number of controls that can go on the title bar?

There is no limit to the number of controls in the title bar. But based on UI design best practices, the title bar should not be clustered. If you are designing a cross platform app then, it is important to keep in mind that iOS uses the left corner for default navigation. If a button is placed in the left corner, then the default navigation back button will not be displayed in iOS.


Is orientation enabled by default?

Yes, by default, the screen will respond to the accelerometer built into the device. The accelerometer senses the orientation of the device and informs the application.


Can I set orientation as PORTRAIT only for a screen?

Yes. Just set the orientation=”PORTRAIT” and the screen will be always displayed in the PORTRAIT mode only.


I have set the scroll property but I do not see scroll bar. What should I do?

You will not see the VERTICAL scroll bar unless the screen content is more than the height of the device screen. You will not see the HORIZONTAL scroll bar unless the screen content is more than the width of the device screen. For BOTH bars to show, the content has to more than the device screen width and height.