Buttons

Buttons can be used pretty much anywhere. Creating a button starts by creating a <div> with the data-bb-type="button" attribute. By default a button will size itself to the text used for the caption. You can however use the data-bb-style="stretch" setting for a button to make it stretch to the total width of the container where it is embedded.

To add a click handler to the button simply add an "onclick" event to the <div>.

    <div data-bb-type="screen">
        <div data-bb-type="panel-header">Font</div>
            <div data-bb-type="label-control-horizontal-row">
                <div data-bb-type="label">Font Style:</div>
                <div data-bb-type="button" onclick="alert('click');" id="plain">Plain</div>
            </div>
        </div>
    </div>

BlackBerry 10 styled buttons support the ability to add an image by setting the data-bb-img attribute to the path to your image.

    <div data-bb-type="button" data-bb-img="images/foo.png">My Button</div>

A BlackBerry 10 styled button can be styled in one of the following ways:

• Text Only: (Text is centered)
• Image + Text: (Image & Text are left justified)
• Image Only: (Image is centered and button is shrunk to fit image)

BlackBerry 10 Button Image Sizes

• BlackBerry PlayBook - 29 x 29 pixels
• BlackBerry 10 - 71 x 71 pixels

JavaScript Interface

You can disable in your Button by adding the data-bb-disabled="true" attribute. When you want to dynamically change the state of your button you can call it's enable() and disable() functions.

	document.getElementById('plainBtn').enable();
	document.getElementById('plainBtn').disable();

The setCaption(value) function has been added to buttons to allow you to set their caption for all OS versions

    document.getElementById('plainBtn').setCaption('my caption');

The setImage(value) function has been added to buttons to allow you to set their image. This is only supported on BlackBerry 10 styling

    document.getElementById('plainBtn').setImage('images/foo.png');

Changes for v0.9.4

NOTE: The following changes are currently in the "next" branch and will be part of v0.9.4

Styling for BlackBerry PlayBook buttons that look like the built in Contacts, Calendar and Email on PlayBook 2.0 are now added. They support both dark and light themes and use the highlightColor to show their selection state.

PlayBook buttons also support the following and use the same size icons as the BlackBerry 10 styling:

• Text Only: (Text is centered)
• Image + Text: (Image & Text are left justified)
• Image Only: (Image is centered and button is shrunk to fit image)

JavaScript Interface

A button can be created dynamically to be inserted into a screen that is already in the live DOM (after the ondomready event has fired for the screen). This allows you to dynamically create buttons on the fly based on user interaction. It is accomplished by using the bb.button.style() function.

// Create the element just like you would in a normal screen declaration
var button = document.createElement('div');
button.setAttribute('data-bb-type','button');
button.setAttribute('data-bb-style', 'stretch');
button.innerHTML = 'Click Me To Remove';
button.onclick = function() {
		this.remove();
	};

// Apply our styling
bb.button.style(button);

// Insert it into the screen and update the scroller
document.getElementById('buttonContainer').appendChild(button);
bb.refresh();

When you want to dynamically show or hide your button you can call it's show() and hide() functions.

	document.getElementById('plainBtn').show();
	document.getElementById('plainBtn').hide();

As a convenience you can also remove your button from the screen by calling the remove() function.

	document.getElementById('plainBtn').remove();