How to create a collapsible panel in Bindows
Johan Lund posted in Developing in Bindows on October 20th, 2010
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
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.
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.
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.
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.
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.
<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.