April 20th, 2014

How to create a 3-State Checkbox3

Our wonderful users requested us to develop a Three State Checkbox component, and we (of course) complied and added it into Bindows 4.1. The new UI component is called BiThreeStateCheckBox (3CB), and it looks like this:

Bindows BiThreeStateCheckBox

The 3CB (sometimes referred to as a tri-state checkbox) is basically a checkbox with an extra state. If you count the disabled state it actually has four states.

Two examples of situations where you might need such a control:

• To indicate that the user has not yet made a choice (undetermined state)
• To indicate a partial state. E.g. In a file tree, whether some, all, or no files have been selected in one of the subtrees.


A user can check and uncheck the 3CB just like a normal checkbox. In Bindows, we call the middle state the undetermined state. You can only get to this state by setting it programmatically from JavaScript. The 3CB inherits from the standard BiCheckBox class, which in turn inherits from BiComponent. This gives you a multitude of options.

The checkbox is pretty easy to setup and use. In the AppLauncher (http://www.bindows.net/bindows/samples/applauncher/) check out the 3CB sample application, called ThreeStateCheckBoxTest.xml.
The application is simple and looks like this.

Bindows 3CB Sample

The code for this sample is pretty straightforward:

3CB Code

Usability considerations

I have seen some implementations of 3CB’s that allow the user to toggle to the middle state. This is generally not a good idea. If, for example, the user can choose between three mutably exclusive colors, e.g. red, blue and green, then there are better controls for this. You have to remember that a three state checkbox does not visually present all the possible options that the user can choose from. Also keep in mind that if a user has to go from the first state to the third, he might have to pass through the second state which may or may not be natural. It might also not be immediately apparent that the checkbox has more than two states.

In most cases, checking a checkbox should not perform actions immediately. It could very well turn on a setting immediately but it shouldn’t, for example, delete a file. Users are used to being able to check/uncheck checkboxes safely then pressing a button that performs the action on the selected items.

Finally, here is a link to the API documentation for this component.

How to create a collapsible panel in Bindows1

In Bindows 3 we introduced animations and in Bindows 4 we included a component that draws power from those animations - BiCollapsiblePanel (BCP).

The collapsible panel is a graphical component that you can fill with any other BiComponent and that can be folded and unfolded with an animation. These types of components are becoming increasingly more popular as it allows the user to simply hide parts of the application that are not needed at a given time.

Anatomy of a collapsible panel

Anatomy of a collapsible panel

The caption can be customized so that when it is clicked it acts like a collapse button. Another useful feature is that using the code you can hide the background gradient, without having to hack the theme. All that is left is the title. This can be used (e.g.) for displaying a news headline, when the user clicks on it the text body unfolds. The caption is its own class ”BiCollapsiblePanelCaption”. The BCP delegates work to it but you can also gain direct access to this class and set properties on it. You could for example get hold of the BiLabel that is the caption label and change it to display nicely formatted html, or supply an icon to the BiLabel. Keep in mind that the height of the caption is limited to a single row.

The title can be aligned left, right or center. If you don’t want a title, simply supply it with an empty string.

Collapse button
The collapse button can be aligned left or right. It displays different images based on the current alignment and fold state of the BCP itself. It isn’t strictly needed since you can configure the panel to close on caption click so it can also be removed completely.

Content panel
This is where you put the components that you want inside the BCP. Although this is a sub component you can simply add components to the BCP itself and the ”add” method call will be delegated to the content panel automatically.

Alignment / Orientation

A BCP can be aligned left, right, top or bottom. These alignments (also referred to as ”orientations”) are named west, east, north and south. Technically you can put a BCP anywhere you want. The orientation setting simply specifies in which direction the panel will open and how the arrows on the collapse button will look. It’s up to you to tell it the way you want it to open.

Other options

The BCP can of course be collapsed and expanded programmatically. We call this ”fold” and ”unfold”. You can also control the animation object and tweak the speed and easing curve for how the panel animates. A convenience method, available in the BCP itself allows you to set the speed without getting into the animation object. There are also events that trigger before the panel is about to fold and unfold, or when the panel has completed folding and unfolding. This is useful if (for example) you want to populate the panel with a different UI right before it opens or be notified when a user has opened the panel.

Limitations, Gotchas

Perhaps the biggest limitation of the BCP right now is that you cannot put your own buttons in the caption bar.

If you place your BCP inside a layout manager such as BiBox (extremely useful) you might have to call ”pack” on the BCP to get it to recalculate its preferred size based on it’s children.

Since the BCP uses the Bindows animation framework, you need to include the ”Animation” package in the ”Resources” section of your ADF before you can use them. Just check the samples if you are unsure on how to do this.

XML Code

Although BCP’s can be created entirely from JavaScript code I’m going to briefly touch on what they look like in XML markup.

<CollapsiblePanel title="Click me" width="150" height="150" orientation="north"
top="0" left="200" backColor="#EBEBEB">
	<Label text="Hello World"/>

As you can see it’s pretty easy to understand. This panel unfolds from the top down. Note that the backColor can be set directly on the BCP and common properties like this one are delegated to the content panel automatically. Then it’s just a matter of nesting the UI that you want inside its tags.

If you want to see more code samples and take the BCP for a spin, Bindows comes with two sample applications that demonstrate many of the features and customizations of the BCP. These files are called CollapsiblePanelTest.xml and CollapsiblePanelTest2.xml and you can find them in the ”test” folder or in the AppLauncher (http://www.bindows.net/bindows/samples/applauncher/).

Also don’t forget to check out the API of both BiCollapsiblePanel: http://www.bindows.net/bindows/docs/api/BiCollapsiblePanel.html

and BiCollapsiblePanelCaption: http://www.bindows.net/bindows/docs/api/BiCollapsiblePanelCaption.html.



Imhotep theme designed by Chris Lin. Proudly powered by Wordpress.
XHTML | CSS | RSS | Comments RSS