Tutorial 4 Basic UI controls - Text, Buttons, Image

What you will learn in this Tutorial

TEXT control

Button controls

IMAGE control

Download Source Code - Tutorials - Source for this tutorial is in appemble-tutorial-buttons-imgs
Learn more FAQ
Good Read XMADL, appearance
Reference Actions, Data Sourcing

Introduction

In this tutorial you are going to learn about how to create basic UI controls that are the most frequently used while developing an application. There are 3 basic controls.

  • TEXT control

  • Button controls

    • PUSHBUTTON
    • IMAGEBUTTON
  • IMAGE control

Android

../_images/text-control1.png ../_images/buttons.png ../_images/image_control1.png

iOS

../_images/iOS_text_small.png ../_images/iOS_button_small.png ../_images/iOS_image_small1.png

Fig 1

TEXT control

TEXT control is one of the most common control and it displays any text value. The text value can be just any string or it can be fetched from a local data source or from remote data source. The display properties of the TEXT control can be defined using an appearance. An appearance defines font style, size, bold, italics, shadow, emboss, underline, background color, gradient, alpha value for setting background transparency, alignment within the control namely LEFT, CENTER, RIGHT. You can set border and define its width, color and radius through an appearance.

General uses of TEXT control

  1. Any string for example “Hello World!”, a label in a form for example “First Name”

    <control type="TEXT" x=”10” y=”30” width=”80” height=”25”

    appearance_name=”black” word_wrap=”1” data_type=”VARCHAR” default_value="Hello World!"/>

    default_value attribute is used to display static strings.

  2. Display data from local device database

    <control type="TEXT" x=”35” y=”2” width=”50” height=”7”

    appearance_name=”black” data_type=”VARCHAR” field_name=”val1” local_data_source="select val1 from shopping_list"/>

  3. Display data from remote server

    <control type="TEXT" x=”35” y=”2” width=”50” height=”7”

    appearance_name=”black” data_type=”VARCHAR” field_name=”meet_class” remote_data_source="http://swimdash.com/swimdash/index/index/category/3/format/json"/>

To learn more about the properties of TEXT control, create text.xml

<screens>
    <screen name="text_screen" screen_type="SCREEN" menuOrder="0"
        menuName="Text"
        initial_layout="PORTRAIT" allowed_layouts="BOTH"
        width="100" height="100" tab_group_name="ui_tab" scroll="VERTICAL">

        <controls>
            <control type="TEXT" x="2" y="2" width="96" height="8"
                appearance_name="black_bold" word_wrap="1"
                data_type="VARCHAR"
                default_value="Welcome to Appearance properties for TEXT
                control"/>
             <control type="TEXT" x="10" y="15" width="80" height="35"
                   appearance_name="blue_bkgrnd_border" word_wrap="1"
                   data_type="VARCHAR" default_value=""/>
             <control type="TEXT" x="11" y="16" width="78" height="7"
                 appearance_name="blue_bkgrnd" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Font Styles"/>
              <control type="TEXT" x="13" y="25" width="20" height="5"
                 appearance_name="white_bold" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Bold"/>
              <control type="TEXT" x="13" y="31" width="20" height="5"
                 appearance_name="white_ita" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Italics"/>
              <control type="TEXT" x="13" y="37" width="20" height="5"
                 appearance_name="red" word_wrap="1" data_type="VARCHAR"
                 default_value="Color"/>
             <control type="TEXT" x="13" y="43" width="20" height="5"
                 appearance_name="white_emboss" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Emboss"/>
             <control type="TEXT" x="54" y="25" width="30" height="5"
                 appearance_name="white_shadow" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Shadow"/>
             <control type="TEXT" x="54" y="31" width="30" height="5"
                 appearance_name="white_underline" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Underline"/>
             <control type="TEXT" x="54" y="37" width="30" height="10"
                 appearance_name="white_right" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Align (left, center, right)"/>
             <control type="TEXT" x="18" y="55" width="60" height="5"
                 appearance_name="blue_bkgrnd" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Opaque background"/>
             <control type="TEXT" x="18" y="60" width="60" height="5"
                 appearance_name="blue_bkgrnd_tr" word_wrap="1"
                 data_type="VARCHAR"
                 default_value="Semi transparent"/>
             <control type="TEXT" x="18" y="65" width="60" height="5"
                 appearance_name="blue_bkgrnd_tr_border" word_wrap="1"
                 data_type="VARCHAR" default_value="Red border"/>
             <control type="TEXT" x="2" y="98" width="96" height="10"
                 appearance_name="black_bold" word_wrap="1"
                 data_type="VARCHAR"
                 default_value=""/>
           </controls>
        </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. For this tutorial the following, appearance.xml has been used.

<appearances>
    <appearance name="black_bold" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#000000" background_color="#FFFFFF" alpha="0"
        justify="LEFT" font_style_bold="1"/>
    <appearance name="black" font_family="Sans-Serif" font_name="Helvetica"
        font_size="3 font_color="#000000" background_color="#FFFFFF"
        alpha="0" justify="LEFT" />
    <appearance name="white_bold" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#FFFFFF" alpha="0"
        justify="LEFT" font_style_bold="1"/>
    <appearance name="white_ita" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#FFFFFF" alpha="0"
        justify="LEFT" font_style_italic="1"/>
    <appearance name="red" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FF0000" background_color="#8B0000" alpha="0"
        justify="LEFT"/>
    <appearance name="white_size2" font_family="Sans-Serif"
        font_name="Helvetica" font_size="2"
        font_color="#FFFFFF" background_color="#8B0000" alpha="0"
        justify="LEFT"/>
    <appearance name="white_emboss" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#8B0000" alpha="0"
        justify="LEFT" font_style_emboss="1"/>
    <appearance name="white_shadow" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#8B0000" alpha="0"
        justify="RIGHT" font_style_shadow="1"/>
    <appearance name="white_underline" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#8B0000" alpha="0"
        justify="RIGHT" font_style_underline="1"/>
    <appearance name="blue_bkgrnd_border" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#50A6C2" alpha="255"
        justify="LEFT" font_style_bold="1" font_style_emboss="1"
        border_color="#FFFFFF" border_width="3" border_radius="4"
        padding="0"/>
    <appearance name="white" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#000000" alpha="0"
        justify="CENTER" font_style_bold="1"
        font_style_emboss="1"/>
    <appearance name="white_right" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#000000" alpha="0"
        justify="RIGHT" font_style_emboss="1"/>
    <appearance name="blue_bkgrnd" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#3A5894" alpha="255"
        justify="CENTER" font_style_bold="1"
        font_style_emboss="1"/>
    <appearance name="blue_bkgrnd_tr" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#3A5894" alpha="120"
        justify="CENTER" font_style_emboss="1"/>
    <appearance name="blue_bkgrnd_tr_border" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#50A6C2" alpha="200"
        justify="CENTER" border_color="#FF0000" border_width="2"
        border_radius="2" padding="0"/>
    <appearance name="lightblue_bkgrnd" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#7EC0EE" alpha="255"
        justify="CENTER" />
    <appearance name="lightblue_bkgrnd_border" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#7EC0EE" alpha="255"
        justify="CENTER"
        border_color="#FFFFFF" border_width="2" border_radius="3"
        padding="0"/>
    <appearance name="white_bkgrnd" font_family="Sans-Serif"
        font_name="Helvetica" font_size="2.5"
        font_color="#000000" background_color="#FFFFFF" alpha="255"
        justify="CENTER" />
    <appearance name="grey_border" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#7EC0EE" alpha="0"
        justify="CENTER"
        border_color="#DDDDDD" border_width="3" border_radius="0"
        padding="0"/>
    <appearance name="button_gradient" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#449def,#2f6699" alpha="255"
        justify="CENTER" font_style_bold="1" font_style_shadow="1"
        border_color="#000000" border_width="3" border_radius="5" padding="0"/>
    <appearance name="button_gradient_on_pressed" font_family="Sans-Serif"
        font_name="Helvetica" font_size="3"
        font_color="#FFFFFF" background_color="#2f6699,#449def" alpha="255"
        justify="CENTER" font_style_bold="1" font_style_shadow="1"
        border_color="#000000" border_width="3" border_radius="5" padding="0"/>
</appearances>

Your text_screen is complete! Now declare that text_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="tutorialbuttonsimagesapp" version="Appemble-Sample-1.0"
   short_description="Tutorial buttons images app"
   long_description="Tutorial buttons images app" size="1024"
   publisher_name="Appemble"
   background="tu_background.png" publish_date="2012-09-27"
   starting_screen_name="text_screen"/>

Now your app is ready for launch. Test text_screen.

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

iOS - Click on Product -> Run.

Button controls

There are different types of Button controls.

PUSHBUTTON control - A button is generally used to take an action when it is pressed.It has an associated action which is executed when the event is triggered. For example, when a button “Next” is pressed, you go to the next screen. Look and feel for pushbuttons can be defined by defining an appearance in appearance.xml. If just the background color is given, the button effect is rendered AVM default for Android. The button looks best when transparency is set to opaque. This is set by alpha="255". You can customize the look and feel by adding border, radius, gradient. You can set on pressed appearance for a pushbutton as well.

Usage: <control type="PUSHBUTTON" .......default_value="Next">

IMAGEBUTTON control - If an image is to be displayed on a pushbutton, instead of text, then imagebutton should be used. You can give the image as default_value="IMAGE:imagename". Save your image in yourproject/assets folder. The image can be positioned by giving attribute scale_type. For example scale_type=”CENTER_INSIDE”

Usage: <control type="IMAGEBUTTON" .......default_value="IMAGE:next.png" scale_type="CENTER_INSIDE">

TOGGLEBUTTON control - It is a button with visual representation of ON and OFF. It can take only boolean values. You can set the display text by using attributes and text_off. You can specify which value needs to be a default value by defining default_value=”ON”

Usage: <control type="TOGGLEBUTTON" ......data_type="BOOLEAN" default_value="ON" text_on="ON" text_off="OFF"/>

Note

It is mandatory to attach an action to PUSHBUTTON and IMAGEBUTTON controls. You can learn how to attach an action to a button control in the sample code below.

Let’s create all types of buttons mentioned above in pushbutton.xml. The appearances for these buttons is already defined in appearance.xml above.

<screens>
    <screen name="button_screen" screen_type="SCREEN" menuOrder="1" menuName="Buttons"
            initial_layout="PORTRAIT" allowed_layouts="BOTH"
            width="100" height="100" tab_group_name="ui_tab" scroll="VERTICAL">

        <controls>
            <control type="TEXT" x="2" y="2" width="96" height="10"
                    appearance_name="black_bold" word_wrap="1" data_type="VARCHAR"
                    default_value="Button styles and types"/>
            <control type="SEPARATOR" x="5" y="8" width="90" height=".3"
                    appearance_name="blue_bkgrnd" word_wrap="1" data_type="VARCHAR"
                    default_value=""/>
            <control type="TEXT" x="2" y="14" width="35" height="10"
                    appearance_name="black" word_wrap="1" data_type="VARCHAR"
                    default_value="Pushbutton with no border"/>
            <control type="PUSHBUTTON" x="39" y="14" width="50" height="8"
                    appearance_name="lightblue_bkgrnd" data_type="VARCHAR"
                    default_value="Button 1">
                <actions>
                    <action event_list="TAP" action_name="SHOW_TAB"
                            target="button_screen"/> <!-- will display the same screen-->
                </actions>
            </control>
            <control type="TEXT" x="2" y="24" width="35" height="12"
                    appearance_name="black" word_wrap="1" data_type="VARCHAR"
                    default_value="Pushbutton with border and gradient"/>
            <control type="PUSHBUTTON" x="39" y="24" width="50" height="8"
                    appearance_name="button_gradient" data_type="VARCHAR"
                    on_pressed_appearance_name="button_gradient_on_pressed"
                    default_value="Button 2">
                <actions>
                    <action event_list="TAP" action_name="SHOW_TAB"
                            target="button_screen"/>
                </actions>
            </control>
            <control type="TEXT" x="2" y="39" width="35" height="8"
                    appearance_name="black" word_wrap="1" data_type="VARCHAR"
                    default_value="Togglebutton"/>
            <control type="TOGGLEBUTTON" x="39" y="39" width="20" height="9"
                    appearance_name="white_bkgrnd" data_type="BOOLEAN"
                    default_value="ON" text_on="ON" text_off="OFF"/>
            <control type="TEXT" x="2" y="54" width="30" height="8"
                    appearance_name="black" word_wrap="1" data_type="VARCHAR"
                    default_value="Imagebutton"/>
            <control type="IMAGEBUTTON" x="39" y="54" width="16" height="8"
                    appearance_name="lightblue_bkgrnd" data_type="VARCHAR"
                    default_value="IMAGE:home.png" scale_type="CENTER_INSIDE">
                <actions>
                    <action event_list="TAP" action_name="SHOW_TAB"
                            target="button_screen"/>
                </actions>
            </control>
        </controls>
    </screen>
</screens>

Now your app is ready for launch. Test button_screen.

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

iOS - Click on Product -> Run.

IMAGE control

Image control is used to display images. Make sure to copy image files in yourproject/assets folder in Android and yourproject/Resources/images folder in iOS.

Usage: <control type="IMAGE" .......default_value="IMAGE:flower.png"

Create image_screen.

<screens>
    <screen name="image_screen" screen_type="SCREEN" menuOrder="2" menuName="Images"
            initial_layout="PORTRAIT" allowed_layouts="BOTH"
            width="100" height="100" tab_group_name="ui_tab" scroll="VERTICAL">

        <controls>
            <control type="TEXT" x="2" y="2" width="96" height="5"
                    appearance_name="black_bold" word_wrap="1" data_type="VARCHAR"
                    default_value="Display Images"/>
            <control type="IMAGE" x="16" y="8" width="20" height="30"
                    appearance_name="black_bold" data_type="VARCHAR"
                    default_value="IMAGE:icons_1.png"/>
            <control type="IMAGE" x="40" y="8" width="20" height="30"
                    appearance_name="black_bold" data_type="VARCHAR"
                    default_value="IMAGE:icons_5.png"/>
            <control type="IMAGE" x="64" y="8" width="20" height="30"
                    appearance_name="black_bold" data_type="VARCHAR"
                    default_value="IMAGE:icons_4.png"/>
            <control type="IMAGE" x="15" y="40" width="70" height="30"
                    appearance_name="black_bold" data_type="VARCHAR"
                    default_value="IMAGE:flower2.jpg"/>
        </controls>
    </screen>
</screens>

Now your app is ready for launch. Test image_screen.

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

iOS - Click on Product -> Run.

Download and Run Tutorials

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

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

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

FAQ

Can I place one text control on top of another one? Can I set an order which control is on top?

Yes you can place one control on top of another. You can simply copy one control above the other in the xml file OR there is an attribute called “zorder” using which you can define the stacking order of the controls. The larger the value of zorder, the higher they are in the stack.


How can I define labels in a form?

Use TEXT controls to define labels in a form. Set default_value="label name"


How can I display dynamic text value?

A dynamic text is a text that is fetched from a local data source or a remote data source before displaying it. A static text in contrast is one which never changes in the life of the application. In order to fetch dynamic data for a control, associate a field_name to the control and then use a SQL query (from local data source) or a remote URL (from remote data source). For ex. if the field name is “first_name”, the query “select first_name from profile” will fetch the data from local data source. To read more on data sourcing..


How can I set the color when the button is pressed?

You can give 2 appearances for the button. One in the default state and one in on pressed state.

For example

<control type=”PUSHBUTTON” x=”39” y=”24” width=”50” height=”8”
appearance_name="button_gradient" data_type=”VARCHAR” on_pressed_appearance_name="button_gradient_on_pressed" default_value=”Button 2”>

In appearance.xml the following appearances are defined

<appearance name="button_gradient" font_family=”Sans-Serif”
font_name=”Helvetica” font_size=”3” font_color=”#FFFFFF” background_color=”#449def,#2f6699” alpha=”255” justify=”CENTER” font_style_bold=”1” font_style_shadow=”1” border_color=”#000000” border_width=”3” border_radius=”5” padding=”0”/>
<appearance name="button_gradient_on_pressed" font_family=”Sans-Serif”
font_name=”Helvetica” font_size=”3” font_color=”#FFFFFF” background_color=”#2f6699,#449def” alpha=”255” justify=”CENTER” font_style_bold=”1” font_style_shadow=”1” border_color=”#000000” border_width=”3” border_radius=”5” padding=”0”/>

Can I set color when the button is active?

By default the appearance is that of an active button. Appearance for a button which is not active is not currently supported. However this is available in another control called SEGMENTED control which is a button group control.


When I define the size of an IMAGE control, will my image be re-sized or will it still display the image in its actual size?

This needs to be implemented, where image properties can be fixed size, scale to fit, maintain aspect ratio.


What happens to the image size, when the screen size changes? If the actual image is smaller will it scale up and become blurred?

It depends upon the properties set for the image. If the image has a property set to fixed_size then the image will not be resized. The scale_to_fit will not maintain the aspect ratio while resizing the image.


How can a get images from a local content table

You can get images by specifying the local data source.


Can I get images remotely?

Yes you can fetch the images remotely by specifying the URL in the remote data source.