August 2nd, 2014

How to create a collapsible panel in Bindows

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

Caption
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.

Title
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"/>
</CollapsiblePanel>

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.

bicollapsiblepaneltest.png

bicollapsiblepaneltest2.png

One Response to 'How to create a collapsible panel in Bindows'

  1. 1Codebix.com
    October 1st, 2011 at 6:59 pm

    Codebix.com - Your post is on Codebix.com…

    This post has been featured on Codebix.com. The place to find latest articles on programming. Click on the url to reach your post’s page….


Leave a Response

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