Package 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 Description
    (package private) class  CollapsibleButtons.VerticalLayout  

  • Field Summary

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

    handle

  • Constructor Summary

    Constructors 
    Constructor Description
    CollapsibleButtons​(org.eclipse.swt.widgets.Composite parent, int style)
    Creates a new ButtonComposite.
    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, 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, ISettings settings, ILanguageSettings language)
    Creates a new ButtonComposite with a given settings and language manager.

  • Method Summary

    Modifier and Type Method 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, toString

    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

    Methods inherited from class java.lang.Object

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

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

    isAutoScalable

  • Constructor Details

    • 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 Details

    • 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()