Skip to content

bind action

Jump to bottom
Steve Hannah edited this page Jul 13, 2021 · 1 revision

<bind-action>

Synopsis

Binds an action to the parent XML tag’s component so that registered actions in the controller hierarchy that match the category of this <bind-action> tag will be notified when a specified event occurs. When the parent element is a <button>, <multiButton>, or subclass thereof (e.g. <checkBox>, <radioButton>, etc..) the action will also be bound to certain properties of the component such as its label, icon, enabled state, and visibility. This allows us to defer much of the stateful behaviour of the button into the controller.

Usage

The <bind-action> tag should be a child of another component, and the action is bound to that parent component. It must at least include a category attribute to specify an action category to use to lookup actions from the controller hierarchy.

It may optionally include Java code as its text content. This will be used as a default event handler and will only be run if the resulting action is not consumed.

<someComponent>
    <bind-action
        category="ACTION_CATEGORY"
        [on="EVENT_TYPE"]
        [inherit="true|false"]>
    <!-- Optional place Java code as text content and it will be run
        as a fallback if the triggered action is not consumed -->
    </bind-action>
</someComponent>

Attributes

category

An ActionNode.Category object, often defined by a <define-category> tag in the same view. This is the category that should be used to lookup actions from the controller hierarchy.

Note

If there are no registered actions in this category, then the parent component will not be rendered in the view at all.
on

An optional attribute specifying the name of the event type that should trigger this action. The parent element’s component class must include a method of the form add{event type}Listener(listener). The default value here is "action", meaning that it expects the parent element’s component to have a method named addActionListener() that will be used to listen to events.

inherit

Optional boolean attribute that specifies whether to crawl all the way up the controller hierarchy to find a matching action. If this is true (the default value), then it will look for matching action in all controllers in the hierarchy, all the way up to the ApplicationController. If set to false, then it will only check the view controller for the current view.

Examples

The following view defines the SAMPLE_ACTION category using the <define-category> tag. It then binds a button to this category using the <bind-action> tag.

<?xml version="1.0"?>
<y view-controller="com.codename1.rad.sampler.controllers.SampleViewController"
        xsi:noNamespaceSchemaLocation="CustomViewControllerSample.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <define-category name="SAMPLE_ACTION"/>
    <define-tag name="name" value="Person.name"/>

    <label>Enter name</label>
    <radTextField tag="name"/>
    <button>
        <bind-action category="SAMPLE_ACTION"/>
    </button>
</y>

Notice that this view also defined custom view controller using the view-controller attribute. This view controller registers an action in the SAMPLE_ACTION category so that it will be notified when the user clicks the button.

The source of this controller is:

package com.codename1.rad.sampler.controllers;

import com.codename1.rad.controllers.Controller;
import com.codename1.rad.controllers.ViewController;
import com.codename1.rad.nodes.ActionNode;
import com.codename1.rad.sampler.CustomViewControllerSample;
import com.codename1.rad.schemas.Person;
import com.codename1.ui.Dialog;

public class SampleViewController extends ViewController {
    /**
     * Creates a new ViewController with the given parent controller.
     *
     * @param parent
     */
    public SampleViewController(Controller parent) {
        super(parent);
    }


    @Override
    protected void initControllerActions() {
        super.initControllerActions();
        ActionNode.builder()
                .label("Submit")
                .addToController(this, CustomViewControllerSample.SAMPLE_ACTION, evt -> {
                    evt.consume();
                    Dialog.show("Received in "+getClass().getName(), "Name is "+evt.getEntity().getText(Person.name), "OK", null);
                });
    }
}
Clone this wiki locally