Thursday, July 21, 2011

Toggle Buttons & Grouping Them Together

Historically LWUIT never had toggle buttons mostly because we just never got around to implement them. This situation couldn't go on for long and a while back we added toggle buttons although not quite in the way we thought we would.

A toggle button is a button that is pressed and then stays pressed, when pressed again its released. Hence the button has a selected state to indicate if its pressed or not. Just like the radio button & checkbox components in LWUIT. So LWUIT's new toggle buttons are really any button (checkbox & radio buttons derive from Button) that has the setToggle() method invoked with true. It thus paints itself with the toggle button style unless explicitly defined otherwise (note that the UIID will be implicitly changed to "ToggleButton").

The cool thing about this is that you can effectively take your knowledge about checkboxes & radio buttons and apply it to toggle buttons.

That's half the story though, to get the full effect of some cool toggle button UI's we would like to assign the buttons on the edges with a rounded feel like some platforms choose to do... That's pretty easy, you can just assign a different UIID to the first/last buttons and be over with it.

But what if you want your code to be generic? After all you might add/remove a button in runtime based on application state and you would like it to have the right style.

To solve this we introduced the ComponentGroup.

The ComponentGroup is a special container that can be either horizontal or vertical (Box X or Y respectively), it also does nothing else. You need to explicitly activate it in the theme by setting a theme property to true (by default you need to set ComponentGroupBool to true).

When ComponentGroupBool is set to true the component group will modify the styles of all components placed within it to match the element UIID given to it (by default GroupElement) with special caveats to the first/last/only elements. E.g.
1. If I have one element within a component group it will have the UIID: GroupElementOnly
2. If I have two elements within a component group they will have the UIID's GroupElementFirst, GroupElementLast
3. If I have three elements within a component group they will have the UIID's GroupElementFirst, GroupElement, GroupElementLast
4. If I have four elements within a component group they will have the UIID's GroupElementFirst, GroupElement, GroupElement, GroupElementLast

You get the picture... This allows you to define special styles for the sides (don't forget to use the derive attribute to generalize your theme) and provide toggle buttons that include special effects simply by placing them into this group.
You can customize the UIID set by the component group by calling setElementUIID in the component group e.g. setElementUIID("ToggleButton") for the picture above will result in:
ToggleButtonFirst, ToggleButton, ToggleButtonLast

There is a sample of this in the SVN version of the LWUITDemo within the fonts demo. This is a short snippet from there:

2: ComponentGroup buttons = new ComponentGroup();
3: buttons.setElementUIID("ToggleButton");
4: buttons.setHorizontal(true);
5: RadioButton plain = new RadioButton("Plain");
6: RadioButton underline = new RadioButton("Underline");
7: RadioButton strikeout = new RadioButton("Strikethru");
8: ButtonGroup bg = new ButtonGroup();
9: initRb(bg, buttons, listener, plain);
10: initRb(bg, buttons, listener, underline);
11: initRb(bg, buttons, listener, strikeout);
13: Container centerFlow = new Container(new FlowLayout(Component.CENTER));
14: f.addComponent(centerFlow);
15: centerFlow.addComponent(buttons);
17: private void initRb(ButtonGroup bg, Container buttons, ActionListener listener, RadioButton rb) {
18: bg.add(rb);
19: rb.setToggle(true);
20: buttons.addComponent(rb);
21: rb.addActionListener(listener);
22: }

1 comment: