This tutorial teaches you how to build & run your first PhoenixSDK app.

You’ll learn how to create a PhoenixSDK project and run a debuggable version of the app. We also demonstrate some fundamentals of PhoenixSDK design, including how to build a simple user interface and handle user input.

If you don't have PhoenixSDK setup yet, please see the Install PhoenixSDK tutorial.

1: Launch PhoenixSDK app from your Applications folder:

main_window

2: Create a new project:

Now you can create new project, specify project name and the folder where you would like project to be created. In this example "Hello world" used as a name for the project and Desktop folder as a destination.

new_project

3: Fill out project info:

Fill the project information and the icons at the project configuration window.

Every app on the device must have unique application id, otherwise the app install might fail - that's why the application Id usually corresponds to TLD (top level domain) + company name + product name, i.e. com.mycompany.myproduct
settings_window

4: Build & run your app

The project setup and this point is complete, now connect your android phone to the computer and press "Build & Run". Build process usually takes around 30 seconds, however in some cases it might take up to a minute. If it takes really longer then that try to unplug the device from the computer and then plug it back. Please also make sure that the device has developer mode turned on.

On most devices running Android 3.2 or older, you can find the option under:
Settings > Applications > Development
On Android 4.0 and newer, it's in Settings > Developer options.

On Android 4.2 and newer, Developer options is hidden by default. To make it available, go to:
Settings > About phone
and tap "Build number" seven times. Return to the previous screen to find Developer options.

building

After the build is complete, the app will look similar to the screenshot below.

The look might vary depending on the phone manufacturer and OS version
app1

The graphical user interface for a PhoenixSDK app is built using a hierarchy of View and Layout objects. View objects are usually UI widgets such as buttons or text fields and Layout objects are view containers that define how the child views are laid out, such as in a grid or a vertical list.

PhoenixSDK provides an XML vocabulary that corresponds to the subclasses of View (FPView) and Layout (FPLayout) so you can define your UI in XML using a hierarchy of UI elements.

layouts

PhoenixSDK automatically loads and executes main.xml and root.js files on application start. Below you can see main.xml used to create our new UI. It contains a label and a button laid into the vertical layout:

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

<!-- Main view -->
<FPLayout orientation="vertical" backgroundColor="#FFFFFF">
    <FPLabel size="match wrap" align="center" title="This is a hello world application" />
    <FPButton name="hello_world_button" size="match wrap" margin="20 0 20 0" title="Press me!" />
</FPLayout>

You might wonder why the size property is set to "match" and "wrap" instead of a real size in pixels. The reason is, with different screens and fonts it's not always easy to know the size of the control in advance. So you can specify a dynamic size, where "match" means take all available free space (match parent's size) and "wrap" means take as much space as required, but no more. So in the case of size="match wrap" it will size the widget to take all available space horizontally and only necessary space vertically.

app2

It looks good, however it could be better if the widgets were vertically centered. Thus let's add empty views on top and bottom to push our content towards the middle.

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

<!-- Main view -->
<FPLayout orientation="vertical" backgroundColor="#FFFFFF">
    <FPView />
    <FPLabel size="match wrap" align="center" title="This is a hello world application" />
    <FPButton name="hello_world_button" size="match wrap" margin="20 0 20 0" title="Press me!" />
    <FPView />
</FPLayout>

By default, if no size attribute specified, all views try to occupy all available space. If there is more than one view, Layout will divide available space between those views.

app3

OK, the app looks great! Let's add an action to our button now. You may have noticed that the name property was added to the button. That's for making it possible to instantiate it in our javascript code

include(["ui.js"], function() {
    var wnd = new FPWindow();
    wnd.setTitle("Hello world");

    var uilLoader = new FPUILoader();
    uilLoader.loadXML({
        files: ["main.xml"],
        success: function (views) {
            var mainLayout = views["main.xml"];
            var button = mainLayout.getViewByName("hello_world_button");
            button.addEventListener({
                eventName: "onClick",
                callback: function() {
                    alert("Hello PhoenixSDK!!!");
                }
            });
            wnd.setLayout(mainLayout);
            wnd.presentAsRootWindow();
        }
    });
});

When UI loader finishes loading UI elements we can access all subviews by their names using the Layout's getViewByName method.

app4

That's it. Easy as it is.