Tutorial 3 : User Actions Handling

Requirement

Please read the Tutorial 2 first.

Manage users actions

Download this tutorial step.

Create a Frame object

An action can be associated with a focusable widget (menu item, button, etc.) or with a shortcut event. Kuix forwards user actions to the FrameHandler that maintains a frame stack used to process actions. It as actually a good practice to create one frame per screen because user actions are generally screen dependant.

So, let's create a HelloWorldFrame object which will implements the org.kalmeo.util.frame.Frame interface.

Push the HelloworldFrame into the FrameHandler:

The FrameHandler manages messages distribution to the frames. To add your actions handlers, simply register your frame with the FrameHandler. To do so, add the following lines to the initDesktopContent() on your midlet:

public void initDesktopContent(Desktop desktop) {
    // push the frame into the frameHandler
    Kuix.getFrameHandler().pushFrame(new HelloWorldFrame());
}  

Move the content of previous initDesktopContent() method to the HelloWorldFrame.onAdded() method.

public void onAdded() {
    // Load the content from the XML file with Kuix.loadScreen static method
    Screen screen = Kuix.loadScreen("helloworld.xml", null);

    // Set the application current screen
    screen.setCurrent();
}

Handle "about", "exitConfirm" and "exit" actions

Edit the HelloWorldFrame onMessage method:

You can also add the following code after the exit action:

public boolean onMessage(Object identifier, Object[] arguments) {
    if ("about".equals(identifier)) {
        // display a popup message
        Kuix.alert("This Helloworld is powered by Kuix", KuixConstants.ALERT_OK);
        return false;
    }
    if ("exitConfirm".equals(identifier)) {
        // display a popup message
        Kuix.alert("Are you sure you want to exit?", KuixConstants.ALERT_YES | KuixConstants.ALERT_NO, "exit", null);
        return false;
    }
    if ("exit".equals(identifier)) {
        // get the midlet instance to invoke the Destroy() method
        HelloWorld.getDefault().destroyImpl();
        //if the event has been processed, we return 'false' to avoid event forwarding to other frames
        return false;
    }

    // return "true" makes the FramHandler to forward the message to the next frame in the stack 
    return true;
} 

These first 2 actions, use an alert popup box to display some messages. See the Kuix Javadocs for more details.

Link menu items to actions

Once that actions implemented, we need to bind them to the widgets on the screen. Go back to the XML file and add the onAction attribute to the menu items:

<screenFirstMenu onAction="exit">Exit</screenFirstMenu>
<screenSecondmenu>
    more...
    <menuPopup>
        <menuItem onAction="about">
            About
        </menuItem>
        <menuItem onAction="exitConfirm">
            Exit
        </menuItem>
    </menuPopup>
</screenSecondmenu>

Customize the PopupMessage style

Once again, if you want your popups to display correctly, add several style information to override the default configuration:

popupBox {
    border: 1;
    border-color: #f19300;
    bg-color: #77787a;
    padding: 5;
    grayed-color: #444447;
}

 

Add buttons

We can add "about" and "exit" action on direct touch button. In this case edit the helloworld.xml to add the folowing lines into the container tag :

<button onAction="about">About</button>
<button onAction="exitConfirm">Exit</button>

You can optionnaly style the previous buttons in the CSS file:

button {
    border: 1;
    border-color: #838386;
    bg-image: url(title_gradient.png);
    padding: 1 6 1 6;
    margin: 2;
}
button:hover {
    border-color: #f19300;
}

Add "one key" shortcuts

For Kuix, a shortcut is a simple widget attribute. If you want to add a shortcut to any component, just set the shortcuts attribute in the XML file like in the following example:

<menuItem onAction="about" shortcuts="1">About</menuItem >


<menuItem onAction="exitConfirm" shortcuts="back|0">Exit</menuItem >

*note: you can add several shortcuts to a widget using a '|' separator between keys.

Because shortcuts are only available on visible widget, you need to put shortcuts on screen too :

<screen title="helloworld" shortcuts="1=about|back=exitConfirm|0=exitConfirm">

Start the midlet

Your menu should now be fully operationnal. You can try to run the midlet.

---

Go forward, internationalize your application : Tutorial 4.