org.eclipse.nebula.widgets.collapsiblebuttons

Class CollapsibleButtons

java.lang.Object

org.eclipse.swt.widgets.Widget

org.eclipse.swt.widgets.Control

org.eclipse.swt.widgets.Scrollable

org.eclipse.swt.widgets.Composite

org.eclipse.nebula.widgets.collapsiblebuttons.CollapsibleButtons

All Implemented Interfaces:

java.util.EventListener, org.eclipse.swt.events.MouseListener, org.eclipse.swt.events.MouseMoveListener, org.eclipse.swt.events.MouseTrackListener, org.eclipse.swt.graphics.Drawable, org.eclipse.swt.internal.SWTEventListener

public class CollapsibleButtons
extends org.eclipse.swt.widgets.Composite
implements org.eclipse.swt.events.MouseListener, org.eclipse.swt.events.MouseMoveListener, org.eclipse.swt.events.MouseTrackListener

CollapsibleButtonsWidget - SWT/JFace Widget - 2005-2007. Version 1.0. © Emil Crumhorn - emil.crumhorn@gmail.com.

Website
If you want more info or more documentation, please visit: http://www.hexapixel.com

Description
ButtonComposite is a Widget that displays a vertical row of buttons similar to the way that Microsoft® shows buttons in the bottom left of the Microsoft Outlook 2005, and 2007 editions. The button bar is a collapsible bar that contains an image, text, and an associated toolbar at the very bottom where buttons that are currently "collapsed" are shown. There is also a menu which is activated by clicking a small arrow icon on the toolbar that will allow you to do actions that are similar to the actions you can do with the mouse.

The bar is resized by dragging the handle-bar which is at the very top. When the mouse is clicked on the handlebar and dragged either up or down, buttons will be shown and hidden accordingly. The button bar also has a feature where - if there's no space to show the actively shown buttons due to progam window size, buttons will automatically collapse to conserve space, and then automatically expand back to the original number of visible buttons when the program window is returned to a size where they can be shown.

Where to put it
It is important to point out that due to the nature of the ButtonComposite, it is important to put it inside a layout that will allow it to expand/collapse with the widgets that are around it - as whenever a button is shown/hidden, the actual physical size of the widget changes, which should cause surrounding widgets to take up either more or less space. I personally recommend putting the ButtonBar inside either a ViewForm, SashForm.

If you still wish to put it on a plain composite, I suggest doing it the following way:

// outer layer wrapper
Composite bcWrapper = new Composite(parentComposite, SWT.None);
GridLayout gl = new GridLayout(1, true);
gl.marginBottom = 0;
gl.marginHeight = 0;
gl.marginWidth = 0;
gl.marginHeight = 0;
inner.setLayout(gl);

CollapsibleButtons cButtons = new CollapsibleButtons(bcWrapper, SWT.NONE);
// will ensure the composite takes up the appropriate amount of space and gets aligned correctly, we align it at the end as that is where it should live
cButtons.setLayoutData(new GridData(GridData.GRAB_VERTICAL | GridData.FILL_HORIZONTAL | GridData.VERTICAL_ALIGN_END));
cButtons.addButton(...);


Customizing
As many people wish to customize the widget beyond the capabilities it already has, there are a few ways you may basically take control over as much or little as you please. First, there are three interfaces that are of importance (apart from the IButtonListener), one is the IButtonPainter, the IColorManager and the ISettings. Let's start with the IColorManager.

IColorManager
If you don't specify a color manager, the DefaultColorManager will be used. The color manager's job is to return colors to the method that is painting the button when the button is drawn, when you move over a button, when you select a button, and when you hover over a selected button. The colors that are returned from the ColorManager will determine everything as far as looks go.

IButtonPainter
Then there's the IButtonPainter. The IButtonPainter lets you take over 3 methods, which are how A. The background colors of the button are painted. B. How the text is drawn, and C. How the image is painted. As this is basically 100% of how a button is drawn, you can control every aspect of the button look and feel. By default, if no IButtonPainter is assigned, the DefaultButtonPainter will be used. The IButtonPainter's paintBackground(...) method is also used to draw all aspects of the tool bar. That way, the toolbar automatically gets the same colors etc like the normal buttons.

ISettings
To control a lot of the features, such as, whether to show the toolbar or not, whether you want certain size buttons, painted borders, and so on, you can create a class that implements ISettings and set it as the Settings manager when you create a ButtonComposite. If you don't specify one, DefaultSettings will be used.

Each button is esentially a composite inside a custom layout, and the toolbar is a composite by itself.

If a toolbar is not wanted, you may control its visibility by implementing ISettings

Double Buffering
It is also important to note that the widget uses custom double buffering as neither Windows XP's or SWT's DOUBLE_BUFFER flag do the job well enough. To do a proper double buffer, the widget is first drawn into a cached Graphics object that is then copied onto the actual graphics object. This reduces flickering and other odd widget behavior. If you intend to run the widget on either Linux or Macintosh (which both know how to double buffer in the OS), you may turn it off.

Version:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	CollapsibleButtons.VerticalLayout

Field Summary

Fields inherited from class org.eclipse.swt.widgets.Control

handle

Constructor Summary

Constructors

Constructor and Description
CollapsibleButtons(org.eclipse.swt.widgets.Composite parent, int style) Creates a new ButtonComposite.
CollapsibleButtons(org.eclipse.swt.widgets.Composite parent, int style, IColorManager colorManager) Creates a new ButtonComposite.
CollapsibleButtons(org.eclipse.swt.widgets.Composite parent, int style, ILanguageSettings language) Creates a new ButtonComposite with a given language manager.
CollapsibleButtons(org.eclipse.swt.widgets.Composite parent, int style, int theme) Creates a new ButtonComposite.
CollapsibleButtons(org.eclipse.swt.widgets.Composite parent, int style, int theme, IColorManager colorManager) Creates a new ButtonComposite.
CollapsibleButtons(org.eclipse.swt.widgets.Composite parent, int style, int theme, IColorManager colorManager, ISettings settings, ILanguageSettings language) Creates a new ButtonComposite.
CollapsibleButtons(org.eclipse.swt.widgets.Composite parent, int style, ISettings settings, ILanguageSettings language) Creates a new ButtonComposite with a given settings and language manager.

Method Summary

Modifier and Type	Method and Description
CustomButton	addButton(java.lang.String name, java.lang.String toolTip, org.eclipse.swt.graphics.Image bigImage, org.eclipse.swt.graphics.Image toolbarImage) Adds a button to the composite.
void	addButtonListener(IButtonListener listener) Adds a new IButtonListener listener that will report clicks and other events.
void	addMenuListener(IMenuListener listener) Adds a menu listener that is notified before and after the menu popup is shown.
void	deselectAll() Deselects all buttons
void	forceLayoutUpdate() Should you ever need to force a re-layout of the composite, this is the method to call.
IColorManager	getColorManager() Returns the active color manager.
java.util.List<CustomButton>	getItems() Returns the list of all buttons.
ILanguageSettings	getLanguageSettings() Returns the current Language settings manager.
(package private) java.util.List<IMenuListener>	getMenuListeners()
int	getNumVisibleButtons() Returns the number of currently visible buttons.
CustomButton	getSelection() Returns the current selection, or null if none.
ISettings	getSettings() Returns the current Settings manager.
org.eclipse.swt.graphics.Point	getSize()
ToolbarComposite	getToolbarComposite() Returns the toolbar composite.
void	hideButton(CustomButton button) Hides the given button (and adds it to the toolbar).
void	hideNextButton() Hides the next button furthest down in the list.
boolean	isVisible(CustomButton button) If a button is permanently hidden or permanently shown.
int	itemCount() Returns the number of buttons in the list.
void	mouseDoubleClick(org.eclipse.swt.events.MouseEvent event)
void	mouseDown(org.eclipse.swt.events.MouseEvent event)
void	mouseEnter(org.eclipse.swt.events.MouseEvent event)
void	mouseExit(org.eclipse.swt.events.MouseEvent event)
void	mouseHover(org.eclipse.swt.events.MouseEvent event)
void	mouseMove(org.eclipse.swt.events.MouseEvent event)
void	mouseUp(org.eclipse.swt.events.MouseEvent event)
void	permanentlyHideButton(CustomButton button) Hides the button from the list and the toolbar.
void	permanentlyShowButton(CustomButton button) Un-hides a button that has been hidden from toolbar and ButtonComposite view.
(package private) void	remove(CustomButton cb, boolean callDispose)
void	removeAllButtons() Removes all buttons.
void	removeButton(CustomButton cb) Same method that is called when CustomButton.dispose() is called.
void	removeButtonListener(IButtonListener listener) Removes an IButtonListener
void	removeMenuListener(IMenuListener listener) Removes a menu listener.
void	selectItem(CustomButton button) Selects a specific CustomButton.
void	selectItemAndLoad(CustomButton button) Flags a button as selected and pretends it got clicked.
void	showButton(CustomButton button) Shows the given button (and removes it from the toolbar).
void	showNextButton() Shows the next button from the list of buttons that are currently hidden.

Methods inherited from class org.eclipse.swt.widgets.Composite

changed, checkSubclass, drawBackground, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayout, setLayoutDeferred, setTabList

Methods inherited from class org.eclipse.swt.widgets.Scrollable

computeTrim, getClientArea, getHorizontalBar, getScrollbarsMode, getVerticalBar

Methods inherited from class org.eclipse.swt.widgets.Control

addControlListener, addDragDetectListener, addFocusListener, addGestureListener, addHelpListener, addKeyListener, addMenuDetectListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, addTouchListener, addTraverseListener, computeSize, computeSize, dragDetect, dragDetect, forceFocus, getAccessible, getBackground, getBackgroundImage, getBorderWidth, getBounds, getCursor, getDragDetect, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getOrientation, getParent, getRegion, getShell, getTextDirection, getToolTipText, getTouchEnabled, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, print, redraw, redraw, removeControlListener, removeDragDetectListener, removeFocusListener, removeGestureListener, removeHelpListener, removeKeyListener, removeMenuDetectListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removeMouseWheelListener, removePaintListener, removeTouchListener, removeTraverseListener, requestLayout, setBackground, setBackgroundImage, setBounds, setBounds, setCapture, setCursor, setDragDetect, setEnabled, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setOrientation, setParent, setRedraw, setRegion, setSize, setSize, setTextDirection, setToolTipText, setTouchEnabled, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, traverse, traverse, update

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getListeners, getStyle, isAutoDirection, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, reskin, setData, setData, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.eclipse.swt.events.MouseListener

mouseDoubleClickAdapter, mouseDownAdapter, mouseUpAdapter

Methods inherited from interface org.eclipse.swt.events.MouseTrackListener

mouseEnterAdapter, mouseExitAdapter, mouseHoverAdapter

Methods inherited from interface org.eclipse.swt.graphics.Drawable

isAutoScalable

Constructor Detail

CollapsibleButtons

public CollapsibleButtons(org.eclipse.swt.widgets.Composite parent,
                          int style)

Creates a new ButtonComposite. Add buttons using the addButton(...) method call.

Parameters:

parent - Parent composite

style - Composite style, SWT.NO_BACKGROUND will be appended to the style.

CollapsibleButtons

public CollapsibleButtons(org.eclipse.swt.widgets.Composite parent,
                          int style,
                          ILanguageSettings language)

Creates a new ButtonComposite with a given language manager.

Parameters:

parent - Parent composite

style - style

language - Language manager

CollapsibleButtons

public CollapsibleButtons(org.eclipse.swt.widgets.Composite parent,
                          int style,
                          ISettings settings,
                          ILanguageSettings language)

Creates a new ButtonComposite with a given settings and language manager.

Parameters:

parent - Parent composite

style - style

settings - Settings manager

language - Language manager

CollapsibleButtons

public CollapsibleButtons(org.eclipse.swt.widgets.Composite parent,
                          int style,
                          int theme)

Creates a new ButtonComposite. Add buttons using the addButton(...) method call. By default, unless you set a theme, the theme will be read from whatever the active color scheme is in Windows XP. If you are using a custom theme and the color scheme cannot be determined, the fall-back will be the Windows XP Blue theme. NOTE: If you want the Office 2007 theme, you have to set it manually as there is no way to guess if you have office 2007 installed or 2005.

Parameters:

parent - Parent composite

style - Composite style, SWT.NO_BACKGROUND will be appended to the style

theme - IColorManager.STYLE_

CollapsibleButtons

public CollapsibleButtons(org.eclipse.swt.widgets.Composite parent,
                          int style,
                          IColorManager colorManager)

Creates a new ButtonComposite. Add buttons using the addButton(...) method call.

Parameters:

parent - Parent composite

style - Composite style, SWT.NO_BACKGROUND will be appended to the style

colorManager - IColorManager implementation. Set to null to use the default

CollapsibleButtons

public CollapsibleButtons(org.eclipse.swt.widgets.Composite parent,
                          int style,
                          int theme,
                          IColorManager colorManager)

Creates a new ButtonComposite. Add buttons using the addButton(...) method call. By default, unless you set a theme, the theme will be read from whatever the active color scheme is in Windows XP. If you are using a custom theme and the color scheme cannot be determined, the fall-back will be the Windows XP Blue theme. NOTE: If you want the Office 2007 theme, you have to set it manually as there is no way to guess if you have office 2007 installed or 2005.

Parameters:

parent - Parent composite

style - Composite style, SWT.NO_BACKGROUND will be appended to the style

theme - IColorManager.STYLE_

colorManager - IColorManager implementation. Set to null to use the default

CollapsibleButtons

public CollapsibleButtons(org.eclipse.swt.widgets.Composite parent,
                          int style,
                          int theme,
                          IColorManager colorManager,
                          ISettings settings,
                          ILanguageSettings language)

Creates a new ButtonComposite. Add buttons using the addButton(...) method call. By default, unless you set a theme, the theme will be read from whatever the active color scheme is in Windows XP. If you are using a custom theme and the color scheme cannot be determined, the fall-back will be the Windows XP Blue theme. NOTE: If you want the Office 2007 theme, you have to set it manually as there is no way to guess if you have office 2007 installed or 2005.

Parameters:

parent - Parent composite

style - Composite style, SWT.NO_BACKGROUND will be appended to the style

theme - IColorManager.STYLE_

colorManager - IColorManager implementation. Set to null to use the default

settings - ISettings implementation. Set to null to use the default

language - ILanguage implementations. Set to null to use the default.

Method Detail

addButtonListener

public void addButtonListener(IButtonListener listener)

Adds a new IButtonListener listener that will report clicks and other events.

Parameters:

listener - IButtonListener

removeButtonListener

public void removeButtonListener(IButtonListener listener)

Removes an IButtonListener

Parameters:

listener - IButtonListener

mouseMove

public void mouseMove(org.eclipse.swt.events.MouseEvent event)

Specified by:

mouseMove in interface org.eclipse.swt.events.MouseMoveListener

getNumVisibleButtons

public int getNumVisibleButtons()

Returns the number of currently visible buttons.

Returns:

Number of visible buttons

permanentlyHideButton

public void permanentlyHideButton(CustomButton button)

Hides the button from the list and the toolbar.

Parameters:

button - Button to hide

permanentlyShowButton

public void permanentlyShowButton(CustomButton button)

Un-hides a button that has been hidden from toolbar and ButtonComposite view.

Parameters:

button - Button to show

hideButton

public void hideButton(CustomButton button)

Hides the given button (and adds it to the toolbar).

Parameters:

button - Button to hide

showButton

public void showButton(CustomButton button)

Shows the given button (and removes it from the toolbar).

Parameters:

button - Button to show

isVisible

public boolean isVisible(CustomButton button)

If a button is permanently hidden or permanently shown.

Parameters:

button - CustomButton to check

Returns:

true or false

hideNextButton

public void hideNextButton()

Hides the next button furthest down in the list. If there are no more buttons left to hide, nothing will happen.

forceLayoutUpdate

public void forceLayoutUpdate()

Should you ever need to force a re-layout of the composite, this is the method to call. It is not recommended to be used.

showNextButton

public void showNextButton()

Shows the next button from the list of buttons that are currently hidden. If there are no more buttons hiding, nothing will happen.

addButton

public CustomButton addButton(java.lang.String name,
                              java.lang.String toolTip,
                              org.eclipse.swt.graphics.Image bigImage,
                              org.eclipse.swt.graphics.Image toolbarImage)

Adds a button to the composite. Button will be added at the bottom of any previously existing buttons.

Parameters:

name - Text that should be displayed on button. May be null.

toolTip - Tooltip that is displayed when mouse moves over both button and tool bar icon. Recommended null.

bigImage - Image displayed on the button. Ideally 24x24 pixels transparent PNG image.

toolbarImage - Image displayed on the toolbar and on any menu items. Ideally 16x16 pixels transparent GIF image.

Returns:

CustomButton for further pre-launch modification.

mouseDoubleClick

public void mouseDoubleClick(org.eclipse.swt.events.MouseEvent event)

Specified by:

mouseDoubleClick in interface org.eclipse.swt.events.MouseListener

mouseDown

public void mouseDown(org.eclipse.swt.events.MouseEvent event)

Specified by:

mouseDown in interface org.eclipse.swt.events.MouseListener

mouseUp

public void mouseUp(org.eclipse.swt.events.MouseEvent event)

Specified by:

mouseUp in interface org.eclipse.swt.events.MouseListener

getSize

public org.eclipse.swt.graphics.Point getSize()

Overrides:

getSize in class org.eclipse.swt.widgets.Control

mouseEnter

public void mouseEnter(org.eclipse.swt.events.MouseEvent event)

Specified by:

mouseEnter in interface org.eclipse.swt.events.MouseTrackListener

mouseExit

public void mouseExit(org.eclipse.swt.events.MouseEvent event)

Specified by:

mouseExit in interface org.eclipse.swt.events.MouseTrackListener

mouseHover

public void mouseHover(org.eclipse.swt.events.MouseEvent event)

Specified by:

mouseHover in interface org.eclipse.swt.events.MouseTrackListener

selectItemAndLoad

public void selectItemAndLoad(CustomButton button)

Flags a button as selected and pretends it got clicked.

Parameters:

button - Button to select and click

selectItem

public void selectItem(CustomButton button)

Selects a specific CustomButton.

Parameters:

button - CustomButton to select

deselectAll

public void deselectAll()

Deselects all buttons

getItems

public java.util.List<CustomButton> getItems()

Returns the list of all buttons.

Returns:

List of buttons

getSelection

public CustomButton getSelection()

Returns the current selection, or null if none.

Returns:

Selected button.

itemCount

public int itemCount()

Returns the number of buttons in the list.

Returns:

Button count

getColorManager

public IColorManager getColorManager()

Returns the active color manager.

Returns:

IColorManager

getSettings

public ISettings getSettings()

Returns the current Settings manager.

Returns:

ISettings

getLanguageSettings

public ILanguageSettings getLanguageSettings()

Returns the current Language settings manager.

Returns:

ILanguageSettings

getToolbarComposite

public ToolbarComposite getToolbarComposite()

Returns the toolbar composite.

Returns:

ToolbarComposite

addMenuListener

public void addMenuListener(IMenuListener listener)

Adds a menu listener that is notified before and after the menu popup is shown.

Parameters:

listener - Listener to add

removeMenuListener

public void removeMenuListener(IMenuListener listener)

Removes a menu listener.

Parameters:

listener - Listener to remove

removeAllButtons

public void removeAllButtons()

Removes all buttons.

removeButton

public void removeButton(CustomButton cb)

Same method that is called when CustomButton.dispose() is called.

Parameters:

cb - CustomButton to remove

remove

void remove(CustomButton cb,
            boolean callDispose)

getMenuListeners

java.util.List<IMenuListener> getMenuListeners()