com.codename1.ui

Class Toolbar

java.lang.Object

com.codename1.ui.Component

com.codename1.ui.Container

com.codename1.ui.Toolbar

All Implemented Interfaces:

Animation, Editable, StyleListener, Iterable<Component>

public class Toolbar
extends Container

Toolbar replaces the default title area with a powerful abstraction that allows functionality ranging from side menus (hamburger) to title animations and any arbitrary component type. Toolbar allows customizing the Form title with different commands on the title area, within the side menu or the overflow menu.

The Toolbar allows placing components in one of 4 positions as illustrated by the sample below:

Toolbar supports a search mode that implicitly replaces the title with a search field/magnifying glass effect. The code below demonstrates searching thru the contacts using this API:

The following code also demonstrates search with a more custom UX where the title area was replaced dynamically. This code predated the builtin search support above. Notice that the TextField and its hint are styled to look like the title.

This sample code show off title animations that allow a title to change (and potentially shrink) as the user scrolls down the UI. The 3 frames below show a step by step process in the change.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Toolbar.BackCommandPolicy The behavior of the back command in the title

Field Summary

Fields inherited from class com.codename1.ui.Component

BASELINE, BOTTOM, BRB_CENTER_OFFSET, BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_OTHER, CENTER, CROSSHAIR_CURSOR, DEFAULT_CURSOR, DRAG_REGION_IMMEDIATELY_DRAG_X, DRAG_REGION_IMMEDIATELY_DRAG_XY, DRAG_REGION_IMMEDIATELY_DRAG_Y, DRAG_REGION_LIKELY_DRAG_X, DRAG_REGION_LIKELY_DRAG_XY, DRAG_REGION_LIKELY_DRAG_Y, DRAG_REGION_NOT_DRAGGABLE, DRAG_REGION_POSSIBLE_DRAG_X, DRAG_REGION_POSSIBLE_DRAG_XY, DRAG_REGION_POSSIBLE_DRAG_Y, E_RESIZE_CURSOR, HAND_CURSOR, LEFT, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NW_RESIZE_CURSOR, RIGHT, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, TOP, W_RESIZE_CURSOR, WAIT_CURSOR

Constructor Summary

Constructors

Constructor and Description
Toolbar() Empty Constructor
Toolbar(boolean layered) This constructor places the Toolbar on a different layer on top of the Content Pane.

Method Summary

Modifier and Type	Method and Description
void	addCommandToLeftBar(Command cmd) Adds a Command to the TitleArea on the left side.
Command	addCommandToLeftBar(String name, Image icon, ActionListener ev) Adds a Command to the TitleArea on the left side.
void	addCommandToLeftSideMenu(Command cmd) Adds a Command to the left side navigation menu
Command	addCommandToLeftSideMenu(String name, Image icon, ActionListener ev) Adds a Command to the left side navigation menu
void	addCommandToOverflowMenu(Command cmd) Adds a Command to the overflow menu
Command	addCommandToOverflowMenu(String name, Image icon, ActionListener ev) Adds a Command to the overflow menu
void	addCommandToRightBar(Command cmd) Adds a Command to the TitleArea on the right side.
Command	addCommandToRightBar(String name, Image icon, ActionListener ev) Adds a Command to the TitleArea on the right side.
void	addCommandToRightSideMenu(Command cmd) Adds a Command to the right side navigation menu (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing).
Command	addCommandToRightSideMenu(String name, Image icon, ActionListener ev) Adds a Command to the right side navigation menu (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing)
void	addCommandToSideMenu(Command cmd) Adds a Command to the left or right side navigation menu according to the state of RTL.
Command	addCommandToSideMenu(String name, Image icon, ActionListener ev) Adds a Command to the left or right side navigation menu according to the state of RTL.
void	addComponentToLeftSideMenu(Component cmp) Adds a Component to the left side navigation menu.
void	addComponentToLeftSideMenu(Component cmp, Command cmd) Adds a Component to the left side navigation menu.
protected void	addComponentToLeftSideMenu(Container menu, Component cmp) This method responsible to add a Component to the left side navigation panel.
void	addComponentToRightSideMenu(Component cmp) Adds a Component to the right side navigation menu (it requires a permanent sidemenu or an onTop sidemenu, otherwise it does nothing).
void	addComponentToRightSideMenu(Component cmp, Command cmd) Adds a Component to the right side navigation menu (it requires a permanent sidemenu or an onTop sidemenu, otherwise it does nothing).
protected void	addComponentToRightSideMenu(Container menu, Component cmp) This method responsible to add a Component to the right side navigation panel.
void	addComponentToSideMenu(Component cmp) Adds a Component to the left or right side navigation menu, according to the state of RTL.
void	addComponentToSideMenu(Component cmp, Command cmd) Adds a Component to the left or right side navigation menu, according to the state of RTL.
protected void	addComponentToSideMenu(Container menu, Component cmp) This method is responsible to add a Component to the left or right side navigation panel according to the state of RTL.
Command	addMaterialCommandToLeftBar(String name, char icon, ActionListener ev) Adds a Command to the TitleArea on the left side with a material design icon reference FontImage.
Command	addMaterialCommandToLeftBar(String name, char icon, float size, ActionListener ev) Adds a Command to the TitleArea on the left side with a material design icon reference FontImage.
Command	addMaterialCommandToLeftSideMenu(String name, char icon, ActionListener ev) Adds a Command to the left side navigation menu with a material design icon reference FontImage.
Command	addMaterialCommandToLeftSideMenu(String name, char icon, float size, ActionListener ev) Adds a Command to the left side navigation menu with a material design icon reference FontImage.
Command	addMaterialCommandToOverflowMenu(String name, char icon, ActionListener ev) Adds a Command to the overflow menu with a material design icon reference FontImage.
Command	addMaterialCommandToOverflowMenu(String name, char icon, float size, ActionListener ev) Adds a Command to the overflow menu with a material design icon reference FontImage.
Command	addMaterialCommandToRightBar(String name, char icon, ActionListener ev) Adds a Command to the TitleArea on the right side with a material design icon reference FontImage.
Command	addMaterialCommandToRightBar(String name, char icon, float size, ActionListener ev) Adds a Command to the TitleArea on the right side with a material design icon reference FontImage.
Command	addMaterialCommandToRightSideMenu(String name, char icon, ActionListener ev) Adds a Command to the right side navigation menu with a material design icon reference FontImage (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing).
Command	addMaterialCommandToRightSideMenu(String name, char icon, float size, ActionListener ev) Adds a Command to the right side navigation menu with a material design icon reference FontImage (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing).
Command	addMaterialCommandToSideMenu(String name, char icon, ActionListener ev) Adds a Command to the left or right side navigation menu (according to the state of RTL) with a material design icon reference FontImage.
Command	addMaterialCommandToSideMenu(String name, char icon, float size, ActionListener ev) Adds a Command to the left or right side navigation menu (according to the state of RTL) with a material design icon reference FontImage.
void	addSearchCommand(ActionListener callback) This method add a search Command on the right bar of the Toolbar.
void	addSearchCommand(ActionListener callback, float iconSize) This method add a search Command on the right bar of the Toolbar.
boolean	animate() Allows the animation to reduce "repaint" calls when it returns false.
void	closeLeftSideMenu() Closes the left side menu
void	closeRightSideMenu() Closes the right side menu
void	closeSideMenu() Closes the current side menu
protected Container	constructRightSideNavigationComponent() Creates an empty right side navigation panel.
protected Container	constructSideNavigationComponent() Creates an empty left side navigation panel.
protected List	createOverflowCommandList(Vector commands) Creates the list component containing the commands within the given vector used for showing the menu dialog
protected Container	createSideNavigationComponent(Vector commands, String placement) Creates the side navigation component with the Commands.
Button	findCommandComponent(Command c) Find the command component instance if such an instance exists
Iterable<Command>	getLeftBarCommands() Returns the commands within the left bar section which can be useful for things like unit testing.
Button	getLeftSideMenuButton() Allows runtime manipulation of the side menu button, notice this will only work after the menu was created
MenuBar	getMenuBar() Returns the associated SideMenuBar object of this Toolbar.
Button	getOverflowButton() Allows runtime manipulation of the overflow button, notice this will only work after the menu was created
Iterable<Command>	getOverflowCommands() Returns the commands within the overflow menu which can be useful for things like unit testing.
Iterable<Command>	getRightBarCommands() Returns the commands within the right bar section which can be useful for things like unit testing.
Button	getRightSideMenuButton() Allows runtime manipulation of the side menu button, notice this will only work after the menu was created
Iterable<Command>	getRightSideMenuCommands() Returns the commands within the right side menu which can be useful for things like unit testing.
Iterable<Command>	getSideMenuCommands() Returns the commands within the left side menu which can be useful for things like unit testing.
Component	getTitleComponent() Returns the Toolbar title Component.
void	hideToolbar() Hide the Toolbar if it is currently showing
protected void	initTitleBarStatus() Adds a status bar space to the north of the Component, subclasses can override this default behavior.
static boolean	isCenteredDefault() Indicates whether the toolbar should be properly centered by default
static boolean	isEnableSideMenuSwipe() Enables/Disables the side menu bar swipe, defaults to true
static boolean	isGlobalToolbar() Enables/disables the Toolbar for all the forms in the application.
static boolean	isOnTopSideMenu() Indicates if the side menu is in "on-top" mode
static boolean	isPermanentSideMenu() Creates a static side menu that doesn't fold instead of the standard sidemenu.
boolean	isSideMenuShowing() Returns true if the left or right side menu is open which is useful for walk through tours etc.
boolean	isTitleCentered() Returns true if the title is centered via the layout
void	openRightSideMenu() This is a convenience method to open the right side menu bar.
void	openSideMenu() This is a convenience method to open the left side menu bar.
void	removeCommand(Command cmd) Removes a Command from the MenuBar
void	removeOverflowCommand(Command cmd) Removes the given overflow menu command, notice that this has no effect on the menu that is currently showing (if it is currently showing) only on the upcoming iterations.
void	removeSearchCommand() Removes a previously installed search command
void	setBackCommand(Command cmd) Sets the back command in the title bar to an arrow type and maps the back command hardware key if applicable.
void	setBackCommand(Command cmd, Toolbar.BackCommandPolicy policy) Sets the back command in the title bar and in the form, back command behaves based on the given policy type
void	setBackCommand(Command cmd, Toolbar.BackCommandPolicy policy, float iconSize) Sets the back command in the title bar and in the form, back command behaves based on the given policy type
Command	setBackCommand(String title, ActionListener<ActionEvent> listener) Sets the back command in the title bar to an arrow type and maps the back command hardware key if applicable.
Command	setBackCommand(String title, Toolbar.BackCommandPolicy policy, ActionListener<ActionEvent> listener) Sets the back command in the title bar and in the form, back command behaves based on the given policy type
static void	setCenteredDefault(boolean aCenteredDefault) Indicates whether the toolbar should be properly centered by default
void	setComponentToRightSideMenuSouth(Component sidemenuSouthComponent) Places a component in the south portion (bottom) of the right side menu.
void	setComponentToSideMenuSouth(Component sidemenuSouthComponent) Places a component in the south portion (bottom) of the left side menu.
static void	setEnableSideMenuSwipe(boolean aEnableSideMenuSwipe) Enables/Disables the side menu bar swipe, defaults to true
static void	setGlobalToolbar(boolean gt) Enables/disables the Toolbar for all the forms in the application.
static void	setOnTopSideMenu(boolean aOnTopSideMenu) Sets the side menu to "on-top" mode
static void	setPermanentSideMenu(boolean p) Creates a static side menu that doesn't fold instead of the standard sidemenu.
void	setRightSideMenuCmdsAlignedToLeft(boolean toLeft) Normally on a right side menu the alignment should be "mirrored" in comparision with the left side menu, also for non-RTL languages: this method allows to change this default behaviour for non-RTL languages, forcing the alignment of the Commands of the right side menu to left.
void	setScrollOffUponContentPane(boolean scrollOff) Sets the Toolbar to scroll off the screen upon content scroll.
void	setTitle(String title) Sets the title of the Toolbar.
void	setTitleCentered(boolean cent) Makes the title align to the center accurately by doing it at the layout level which also takes into account right/left commands
void	setTitleComponent(Component titleCmp) Sets the Toolbar title component.
protected Command	showOverflowMenu(Dialog menu)
void	showSearchBar(ActionListener callback) Shows the search bar manually which is useful for use cases of popping up search from code
void	showToolbar() Show the Toolbar if it is currently not showing

Methods inherited from class com.codename1.ui.Container

add, add, add, add, add, add, addAll, addComponent, addComponent, addComponent, addComponent, animateHierarchy, animateHierarchyAndWait, animateHierarchyFade, animateHierarchyFadeAndWait, animateLayout, animateLayoutAndWait, animateLayoutFade, animateLayoutFadeAndWait, animateUnlayout, animateUnlayoutAndWait, applyRTL, calcPreferredSize, cancelRepaints, clearClientProperties, constrainHeightWhenScrollable, constrainWidthWhenScrollable, contains, createAnimateHierarchy, createAnimateHierarchyFade, createAnimateLayout, createAnimateLayoutFade, createAnimateLayoutFadeAndWait, createAnimateMotion, createAnimateUnlayout, createReplaceTransition, dragInitiated, drop, encloseIn, encloseIn, findDropTargetAt, findFirstFocusable, fireClicked, flushReplace, forceRevalidate, getBottomGap, getChildrenAsList, getClosestComponentTo, getComponentAt, getComponentAt, getComponentCount, getComponentIndex, getGridPosX, getGridPosY, getLayout, getLayoutHeight, getLayoutWidth, getLeadComponent, getLeadParent, getResponderAt, getSafeAreaRoot, getScrollIncrement, getSideGap, getUIManager, initLaf, invalidate, isEnabled, isSafeArea, isSafeAreaRoot, isScrollableX, isScrollableY, isSelectableInteraction, isSurface, iterator, iterator, keyPressed, keyReleased, layoutContainer, morph, morphAndWait, paint, paintBackground, paintBorderBackground, paintComponentBackground, paintGlass, paramString, pointerPressed, refreshTheme, removeAll, removeComponent, replace, replace, replaceAndWait, replaceAndWait, replaceAndWait, revalidate, revalidateLater, revalidateWithAnimationSafety, scrollComponentToVisible, setCellRenderer, setEnabled, setLayout, setLeadComponent, setSafeArea, setSafeAreaRoot, setScrollable, setScrollableX, setScrollableY, setScrollIncrement, setShouldCalcPreferredSize, setShouldLayout, setUIManager, updateTabIndices

Methods inherited from class com.codename1.ui.Component

addDragFinishedListener, addDragOverListener, addDropListener, addFocusListener, addLongPressListener, addPointerDraggedListener, addPointerPressedListener, addPointerReleasedListener, addPullToRefresh, addScrollListener, addStateChangeListener, bindProperty, blocksSideSwipe, calcScrollSize, contains, containsOrOwns, createStyleAnimation, deinitialize, deinitializeCustomStyle, dragEnter, dragExit, dragFinished, draggingOver, drawDraggedImage, focusGained, focusLost, getAbsoluteX, getAbsoluteY, getAllStyles, getAnimationManager, getBaseline, getBaselineResizeBehavior, getBindablePropertyNames, getBindablePropertyTypes, getBorder, getBoundPropertyValue, getBounds, getBounds, getClientProperty, getCloudBoundProperty, getCloudDestinationProperty, getComponentForm, getComponentState, getCursor, getDefaultDragTransparency, getDirtyRegion, getDisabledStyle, getDraggedx, getDraggedy, getDragImage, getDragRegionStatus, getDragSpeed, getDragTransparency, getEditingDelegate, getHeight, getInlineAllStyles, getInlineDisabledStyles, getInlinePressedStyles, getInlineSelectedStyles, getInlineStylesTheme, getInlineUnselectedStyles, getInnerHeight, getInnerPreferredH, getInnerPreferredW, getInnerWidth, getInnerX, getInnerY, getLabelForComponent, getName, getNativeOverlay, getNextFocusDown, getNextFocusLeft, getNextFocusRight, getNextFocusUp, getOuterHeight, getOuterPreferredH, getOuterPreferredW, getOuterWidth, getOuterX, getOuterY, getOwner, getParent, getPreferredH, getPreferredSize, getPreferredSizeStr, getPreferredTabIndex, getPreferredW, getPressedStyle, getPropertyNames, getPropertyTypeNames, getPropertyTypes, getPropertyValue, getSameHeight, getSameWidth, getScrollable, getScrollAnimationSpeed, getScrollDimension, getScrollOpacity, getScrollOpacityChangeSpeed, getScrollX, getScrollY, getSelectCommandText, getSelectedRect, getSelectedStyle, getStyle, getTabIndex, getTensileLength, getTextSelectionSupport, getTooltip, getUIID, getUnselectedStyle, getVisibleBounds, getVisibleBounds, getWidth, getX, getY, growShrink, handlesInput, hasFixedPreferredSize, hasFocus, hideNativeOverlay, initComponent, initCustomStyle, initDisabledStyle, initPressedStyle, initSelectedStyle, initUnselectedStyle, installDefaultPainter, isAlwaysTensile, isBlockLead, isCellRenderer, isChildOf, isDragActivated, isDragAndDropOperation, isDraggable, isDragRegion, isDropTarget, isEditable, isEditing, isFlatten, isFocusable, isGrabsPointerEvents, isHidden, isHidden, isHideInLandscape, isHideInPortrait, isIgnorePointerEvents, isInClippingRegion, isInitialized, isOpaque, isOwnedBy, isPinchBlocksDragAndDrop, isRippleEffect, isRTL, isScrollable, isScrollVisible, isSetCursorSupported, isSmoothScrolling, isSnapToGrid, isStickyDrag, isTactileTouch, isTactileTouch, isTensileDragEnabled, isTraversable, isVisible, keyRepeated, laidOut, longKeyPress, longPointerPress, onScrollX, onScrollY, paintBackgrounds, paintBorder, paintComponent, paintComponent, paintIntersectingComponentsAbove, paintLock, paintLockRelease, paintRippleOverlay, paintScrollbars, paintScrollbarX, paintScrollbarY, paintShadows, parsePreferredSize, pinch, pinch, pinchReleased, pointerDragged, pointerDragged, pointerHover, pointerHoverPressed, pointerHoverReleased, pointerPressed, pointerReleased, pointerReleased, putClientProperty, refreshTheme, refreshTheme, remove, removeDragFinishedListener, removeDragOverListener, removeDropListener, removeFocusListener, removeLongPressListener, removePointerDraggedListener, removePointerPressedListener, removePointerReleasedListener, removeScrollListener, removeStateChangeListener, repaint, repaint, requestFocus, resetFocusable, respondsToPointerEvents, scrollRectToVisible, scrollRectToVisible, setAlwaysTensile, setBlockLead, setBoundPropertyValue, setCloudBoundProperty, setCloudDestinationProperty, setComponentState, setCursor, setDefaultDragTransparency, setDirtyRegion, setDisabledStyle, setDraggable, setDragTransparency, setDropTarget, setEditingDelegate, setFlatten, setFocus, setFocusable, setGrabsPointerEvents, setHandlesInput, setHeight, setHidden, setHidden, setHideInLandscape, setHideInPortrait, setIgnorePointerEvents, setInitialized, setInlineAllStyles, setInlineDisabledStyles, setInlinePressedStyles, setInlineSelectedStyles, setInlineStylesTheme, setInlineUnselectedStyles, setIsScrollVisible, setLabelForComponent, setName, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setOpaque, setOwner, setPinchBlocksDragAndDrop, setPreferredH, setPreferredSize, setPreferredSizeStr, setPreferredTabIndex, setPreferredW, setPressedStyle, setPropertyValue, setRippleEffect, setRTL, setSameHeight, setSameSize, setSameWidth, setScrollAnimationSpeed, setScrollOpacityChangeSpeed, setScrollSize, setScrollVisible, setScrollX, setScrollY, setSelectCommandText, setSelectedStyle, setSize, setSmoothScrolling, setSnapToGrid, setTabIndex, setTactileTouch, setTensileDragEnabled, setTensileLength, setTooltip, setTraversable, setUIID, setUIID, setUnselectedStyle, setVisible, setWidth, setX, setY, shouldBlockSideSwipe, shouldBlockSideSwipeLeft, shouldBlockSideSwipeRight, shouldRenderComponentSelection, showNativeOverlay, startEditingAsync, stopEditing, stripMarginAndPadding, styleChanged, toImage, toString, unbindProperty, updateNativeOverlay, visibleBoundsContains

Methods inherited from class java.lang.Object

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

Constructor Detail

Toolbar

public Toolbar()

Empty Constructor

Toolbar

public Toolbar(boolean layered)

This constructor places the Toolbar on a different layer on top of the Content Pane.

Parameters:

layered - if true places the Toolbar on top of the Content Pane

Method Detail

isCenteredDefault

public static boolean isCenteredDefault()

Indicates whether the toolbar should be properly centered by default

Returns:

the centeredDefault

setCenteredDefault

public static void setCenteredDefault(boolean aCenteredDefault)

Indicates whether the toolbar should be properly centered by default

Parameters:

aCenteredDefault - the centeredDefault to set

isOnTopSideMenu

public static boolean isOnTopSideMenu()

Indicates if the side menu is in "on-top" mode

Returns:

the onTopSideMenu

setOnTopSideMenu

public static void setOnTopSideMenu(boolean aOnTopSideMenu)

Sets the side menu to "on-top" mode

Parameters:

aOnTopSideMenu - the onTopSideMenu to set

isEnableSideMenuSwipe

public static boolean isEnableSideMenuSwipe()

Enables/Disables the side menu bar swipe, defaults to true

Returns:

the enableSideMenuSwipe

setEnableSideMenuSwipe

public static void setEnableSideMenuSwipe(boolean aEnableSideMenuSwipe)

Enables/Disables the side menu bar swipe, defaults to true

Parameters:

aEnableSideMenuSwipe - the enableSideMenuSwipe to set

setGlobalToolbar

public static void setGlobalToolbar(boolean gt)

Enables/disables the Toolbar for all the forms in the application. This flag can be flipped via the theme constant globalToobarBool. Notice that the name of this method might imply that one toolbar instance will be used for all forms which isn't the case, separate instances will be used for each form

Parameters:

gt - true to enable the toolbar globally

isGlobalToolbar

public static boolean isGlobalToolbar()

Enables/disables the Toolbar for all the forms in the application. This flag can be flipped via the theme constant globalToobarBool. Notice that the name of this method might imply that one toolbar instance will be used for all forms which isn't the case, separate instances will be used for each form

Returns:

true if the toolbar API is turned on by default

setTitle

public void setTitle(String title)

Sets the title of the Toolbar.

Parameters:

title - the Toolbar title

setTitleCentered

public void setTitleCentered(boolean cent)

Makes the title align to the center accurately by doing it at the layout level which also takes into account right/left commands

Parameters:

cent - whether the title should be centered

isTitleCentered

public boolean isTitleCentered()

Returns true if the title is centered via the layout

Returns:

true if the title is centered

setPermanentSideMenu

public static void setPermanentSideMenu(boolean p)

Creates a static side menu that doesn't fold instead of the standard sidemenu. This is common for tablet UI's where folding the side menu doesn't make as much sense.

Parameters:

p - true to have a permanent side menu

isPermanentSideMenu

public static boolean isPermanentSideMenu()

Creates a static side menu that doesn't fold instead of the standard sidemenu. This is common for tablet UI's where folding the side menu doesn't make as much sense.

Returns:

true if we will use a permanent sidemenu

openSideMenu

public void openSideMenu()

This is a convenience method to open the left side menu bar. It's useful for cases where we want to place the menu button in a "creative way" in which case we can bind the side menu to this

isSideMenuShowing

public boolean isSideMenuShowing()

Returns true if the left or right side menu is open which is useful for walk through tours etc.

openRightSideMenu

public void openRightSideMenu()

This is a convenience method to open the right side menu bar. It's useful for cases where we want to place the menu button in a "creative way" in which case we can bind the side menu to this

closeSideMenu

public void closeSideMenu()

Closes the current side menu

closeLeftSideMenu

public void closeLeftSideMenu()

Closes the left side menu

closeRightSideMenu

public void closeRightSideMenu()

Closes the right side menu

setTitleComponent

public void setTitleComponent(Component titleCmp)

Sets the Toolbar title component. This method allow placing any component in the Toolbar center instead of the regular Label. Can be used to place a TextField to perform search operations

Parameters:

titleCmp - Component to place in the Toolbar center.

getTitleComponent

public Component getTitleComponent()

Returns the Toolbar title Component.

Returns:

the Toolbar title component

addCommandToOverflowMenu

public Command addCommandToOverflowMenu(String name,
                                        Image icon,
                                        ActionListener ev)

Adds a Command to the overflow menu

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

setBackCommand

public Command setBackCommand(String title,
                              ActionListener<ActionEvent> listener)

Sets the back command in the title bar to an arrow type and maps the back command hardware key if applicable. This is functionally identical to setBackCommand(title, Toolbar.BackCommandPolicy.AS_ARROW, listener);

Parameters:

title - command title

listener - action event for the back command

Returns:

the created command

setBackCommand

public void setBackCommand(Command cmd)

Sets the back command in the title bar to an arrow type and maps the back command hardware key if applicable. This is functionally identical to setBackCommand(cmd, Toolbar.BackCommandPolicy.AS_ARROW);

Parameters:

cmd - the command

setBackCommand

public Command setBackCommand(String title,
                              Toolbar.BackCommandPolicy policy,
                              ActionListener<ActionEvent> listener)

Sets the back command in the title bar and in the form, back command behaves based on the given policy type

Parameters:

title - command title

policy - the behavior of the back command in the title

listener - action event for the back command

Returns:

the created command

setBackCommand

public void setBackCommand(Command cmd,
                           Toolbar.BackCommandPolicy policy,
                           float iconSize)

Sets the back command in the title bar and in the form, back command behaves based on the given policy type

Parameters:

cmd - the command

policy - the behavior of the back command in the title

iconSize - the size of the back command icon in millimeters

setBackCommand

public void setBackCommand(Command cmd,
                           Toolbar.BackCommandPolicy policy)

Sets the back command in the title bar and in the form, back command behaves based on the given policy type

Parameters:

cmd - the command

policy - the behavior of the back command in the title

addSearchCommand

public void addSearchCommand(ActionListener callback,
                             float iconSize)

This method add a search Command on the right bar of the Toolbar. When the search Command is invoked the current Toolbar is replaced with a search Toolbar to perform a search on the Current Form.

The callback ActionListener gets the search string and it's up to developer to do the actual filtering on the Form.

It is possible to customize the default look of the search Toolbar with the following uiid's: ToolbarSearch, TextFieldSearch & TextHintSearch.

 
Image duke = null;
try {
    duke = Image.createImage("/duke.png");
} catch(IOException err) {
    Log.e(err);
}
int fiveMM = Display.getInstance().convertToPixels(5);
final Image finalDuke = duke.scaledWidth(fiveMM);
Toolbar.setGlobalToolbar(true);
Form hi = new Form("Search", BoxLayout.y());
hi.add(new InfiniteProgress());
Display.getInstance().scheduleBackgroundTask(()-> {
    // this will take a while...
    Contact[] cnts = Display.getInstance().getAllContacts(true, true, true, true, false, false);
    Display.getInstance().callSerially(() -> {
        hi.removeAll();
        for(Contact c : cnts) {
            MultiButton m = new MultiButton();
            m.setTextLine1(c.getDisplayName());
            m.setTextLine2(c.getPrimaryPhoneNumber());
            Image pic = c.getPhoto();
            if(pic != null) {
                m.setIcon(fill(pic, finalDuke.getWidth(), finalDuke.getHeight()));
            } else {
                m.setIcon(finalDuke);
            }
            hi.add(m);
        }
        hi.revalidate();
    });
});

hi.getToolbar().addSearchCommand(e -> {
    String text = (String)e.getSource();
    if(text == null || text.length() == 0) {
        // clear search
        for(Component cmp : hi.getContentPane()) {
            cmp.setHidden(false);
            cmp.setVisible(true);
        }
        hi.getContentPane().animateLayout(150);
    } else {
        text = text.toLowerCase();
        for(Component cmp : hi.getContentPane()) {
            MultiButton mb = (MultiButton)cmp;
            String line1 = mb.getTextLine1();
            String line2 = mb.getTextLine2();
            boolean show = line1 != null && line1.toLowerCase().indexOf(text) > -1 ||
                    line2 != null && line2.toLowerCase().indexOf(text) > -1;
            mb.setHidden(!show);
            mb.setVisible(show);
        }
        hi.getContentPane().animateLayout(150);
    }
}, 4);

hi.show();

Parameters:

callback - gets the search string callbacks

iconSize - indicates the size of the icons used in the search/back in millimeters

showSearchBar

public void showSearchBar(ActionListener callback)

Shows the search bar manually which is useful for use cases of popping up search from code

Parameters:

callback - gets the search string callbacks

removeSearchCommand

public void removeSearchCommand()

Removes a previously installed search command

addSearchCommand

public void addSearchCommand(ActionListener callback)

This method add a search Command on the right bar of the Toolbar. When the search Command is invoked the current Toolbar is replaced with a search Toolbar to perform a search on the Current Form.

The callback ActionListener gets the search string and it's up to developer to do the actual filtering on the Form.

It is possible to customize the default look of the search Toolbar with the following uiid's: ToolbarSearch, TextFieldSearch & TextHintSearch.

 
Image duke = null;
try {
    duke = Image.createImage("/duke.png");
} catch(IOException err) {
    Log.e(err);
}
int fiveMM = Display.getInstance().convertToPixels(5);
final Image finalDuke = duke.scaledWidth(fiveMM);
Toolbar.setGlobalToolbar(true);
Form hi = new Form("Search", BoxLayout.y());
hi.add(new InfiniteProgress());
Display.getInstance().scheduleBackgroundTask(()-> {
    // this will take a while...
    Contact[] cnts = Display.getInstance().getAllContacts(true, true, true, true, false, false);
    Display.getInstance().callSerially(() -> {
        hi.removeAll();
        for(Contact c : cnts) {
            MultiButton m = new MultiButton();
            m.setTextLine1(c.getDisplayName());
            m.setTextLine2(c.getPrimaryPhoneNumber());
            Image pic = c.getPhoto();
            if(pic != null) {
                m.setIcon(fill(pic, finalDuke.getWidth(), finalDuke.getHeight()));
            } else {
                m.setIcon(finalDuke);
            }
            hi.add(m);
        }
        hi.revalidate();
    });
});

hi.getToolbar().addSearchCommand(e -> {
    String text = (String)e.getSource();
    if(text == null || text.length() == 0) {
        // clear search
        for(Component cmp : hi.getContentPane()) {
            cmp.setHidden(false);
            cmp.setVisible(true);
        }
        hi.getContentPane().animateLayout(150);
    } else {
        text = text.toLowerCase();
        for(Component cmp : hi.getContentPane()) {
            MultiButton mb = (MultiButton)cmp;
            String line1 = mb.getTextLine1();
            String line2 = mb.getTextLine2();
            boolean show = line1 != null && line1.toLowerCase().indexOf(text) > -1 ||
                    line2 != null && line2.toLowerCase().indexOf(text) > -1;
            mb.setHidden(!show);
            mb.setVisible(show);
        }
        hi.getContentPane().animateLayout(150);
    }
}, 4);

hi.show();

Parameters:

callback - gets the search string callbacks

addCommandToOverflowMenu

public void addCommandToOverflowMenu(Command cmd)

Adds a Command to the overflow menu

Parameters:

cmd - a Command

getOverflowCommands

public Iterable<Command> getOverflowCommands()

Returns the commands within the overflow menu which can be useful for things like unit testing. Notice that you should not mutate the commands or the iteratable set in any way!

Returns:

the commands in the overflow menu

addCommandToSideMenu

public Command addCommandToSideMenu(String name,
                                    Image icon,
                                    ActionListener ev)

Adds a Command to the left or right side navigation menu according to the state of RTL.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addCommandToLeftSideMenu

public Command addCommandToLeftSideMenu(String name,
                                        Image icon,
                                        ActionListener ev)

Adds a Command to the left side navigation menu

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addCommandToRightSideMenu

public Command addCommandToRightSideMenu(String name,
                                         Image icon,
                                         ActionListener ev)

Adds a Command to the right side navigation menu (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing)

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addComponentToSideMenu

public void addComponentToSideMenu(Component cmp)

Adds a Component to the left or right side navigation menu, according to the state of RTL.

Parameters:

cmp - c Component to be added to the menu

addComponentToSideMenu

protected void addComponentToSideMenu(Container menu,
                                      Component cmp)

This method is responsible to add a Component to the left or right side navigation panel according to the state of RTL.

Parameters:

menu - the Menu Container that was created in the constructSideNavigationComponent() method

cmp - the Component to add to the side menu

addComponentToSideMenu

public void addComponentToSideMenu(Component cmp,
                                   Command cmd)

Adds a Component to the left or right side navigation menu, according to the state of RTL. The Component is added to the navigation menu and the command gets the events once the Component is being pressed.

Parameters:

cmp - c Component to be added to the menu

cmd - a Command to handle the events

addMaterialCommandToLeftSideMenu

public Command addMaterialCommandToLeftSideMenu(String name,
                                                char icon,
                                                ActionListener ev)

Adds a Command to the left side navigation menu with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToRightSideMenu

public Command addMaterialCommandToRightSideMenu(String name,
                                                 char icon,
                                                 ActionListener ev)

Adds a Command to the right side navigation menu with a material design icon reference FontImage (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing).

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToSideMenu

public Command addMaterialCommandToSideMenu(String name,
                                            char icon,
                                            float size,
                                            ActionListener ev)

Adds a Command to the left or right side navigation menu (according to the state of RTL) with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

size - size in millimeters for the icon

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToSideMenu

public Command addMaterialCommandToSideMenu(String name,
                                            char icon,
                                            ActionListener ev)

Adds a Command to the left or right side navigation menu (according to the state of RTL) with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToLeftSideMenu

public Command addMaterialCommandToLeftSideMenu(String name,
                                                char icon,
                                                float size,
                                                ActionListener ev)

Adds a Command to the left side navigation menu with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

size - size in millimeters for the icon

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToRightSideMenu

public Command addMaterialCommandToRightSideMenu(String name,
                                                 char icon,
                                                 float size,
                                                 ActionListener ev)

Adds a Command to the right side navigation menu with a material design icon reference FontImage (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing).

Parameters:

name - the name/title of the command

icon - the icon for the command

size - size in millimeters for the icon

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToRightBar

public Command addMaterialCommandToRightBar(String name,
                                            char icon,
                                            ActionListener ev)

Adds a Command to the TitleArea on the right side with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToRightBar

public Command addMaterialCommandToRightBar(String name,
                                            char icon,
                                            float size,
                                            ActionListener ev)

Adds a Command to the TitleArea on the right side with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

size - size of the icon in millimeters

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToLeftBar

public Command addMaterialCommandToLeftBar(String name,
                                           char icon,
                                           ActionListener ev)

Adds a Command to the TitleArea on the left side with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToLeftBar

public Command addMaterialCommandToLeftBar(String name,
                                           char icon,
                                           float size,
                                           ActionListener ev)

Adds a Command to the TitleArea on the left side with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

size - size in millimeters for the icon

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToOverflowMenu

public Command addMaterialCommandToOverflowMenu(String name,
                                                char icon,
                                                ActionListener ev)

Adds a Command to the overflow menu with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addMaterialCommandToOverflowMenu

public Command addMaterialCommandToOverflowMenu(String name,
                                                char icon,
                                                float size,
                                                ActionListener ev)

Adds a Command to the overflow menu with a material design icon reference FontImage.

Parameters:

name - the name/title of the command

icon - the icon for the command

size - size in millimeters for the icon

ev - the even handler

Returns:

a newly created Command instance

addCommandToSideMenu

public void addCommandToSideMenu(Command cmd)

Adds a Command to the left or right side navigation menu according to the state of RTL.

Parameters:

cmd - a Command

addCommandToLeftSideMenu

public void addCommandToLeftSideMenu(Command cmd)

Adds a Command to the left side navigation menu

Parameters:

cmd - a Command

addCommandToRightSideMenu

public void addCommandToRightSideMenu(Command cmd)

Adds a Command to the right side navigation menu (it requires a permanent sidemenu or an onTop mode sidemenu, otherwise it does nothing).

Parameters:

cmd - a Command

getLeftSideMenuButton

public Button getLeftSideMenuButton()

Allows runtime manipulation of the side menu button, notice this will only work after the menu was created

Returns:

a button or null if the menu isn't there yet

getRightSideMenuButton

public Button getRightSideMenuButton()

Allows runtime manipulation of the side menu button, notice this will only work after the menu was created

Returns:

a button or null if the menu isn't there yet

getOverflowButton

public Button getOverflowButton()

Allows runtime manipulation of the overflow button, notice this will only work after the menu was created

Returns:

a button or null if the menu isn't there yet

setComponentToSideMenuSouth

public void setComponentToSideMenuSouth(Component sidemenuSouthComponent)

Places a component in the south portion (bottom) of the left side menu. Notice this only works with on-top side menu and the permanent side menu. Setting this value to null will remove the existing component. Only one component can be placed in the south but it can be a container that includes many components

Parameters:

sidemenuSouthComponent - the new component to place in the south or null to remove the current component

setComponentToRightSideMenuSouth

public void setComponentToRightSideMenuSouth(Component sidemenuSouthComponent)

Places a component in the south portion (bottom) of the right side menu. Notice this only works with on-top side menu and the permanent side menu. Setting this value to null will remove the existing component. Only one component can be placed in the south but it can be a container that includes many components

Parameters:

sidemenuSouthComponent - the new component to place in the south or null to remove the current component

addComponentToLeftSideMenu

public void addComponentToLeftSideMenu(Component cmp,
                                       Command cmd)

Adds a Component to the left side navigation menu. The Component is added to the navigation menu and the command gets the events once the Component is being pressed.

Parameters:

cmp - c Component to be added to the menu

cmd - a Command to handle the events

addComponentToRightSideMenu

public void addComponentToRightSideMenu(Component cmp,
                                        Command cmd)

Adds a Component to the right side navigation menu (it requires a permanent sidemenu or an onTop sidemenu, otherwise it does nothing). The Component is added to the navigation menu and the command gets the events once the Component is being pressed.

Parameters:

cmp - c Component to be added to the menu

cmd - a Command to handle the events

addComponentToLeftSideMenu

public void addComponentToLeftSideMenu(Component cmp)

Adds a Component to the left side navigation menu.

Parameters:

cmp - c Component to be added to the menu

addComponentToRightSideMenu

public void addComponentToRightSideMenu(Component cmp)

Adds a Component to the right side navigation menu (it requires a permanent sidemenu or an onTop sidemenu, otherwise it does nothing).

Parameters:

cmp - c Component to be added to the menu

findCommandComponent

public Button findCommandComponent(Command c)

Find the command component instance if such an instance exists

Parameters:

c - the command instance

Returns:

the button instance

addCommandToRightBar

public Command addCommandToRightBar(String name,
                                    Image icon,
                                    ActionListener ev)

Adds a Command to the TitleArea on the right side.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

removeCommand

public void removeCommand(Command cmd)

Removes a Command from the MenuBar

Parameters:

cmd - Command to remove

addCommandToRightBar

public void addCommandToRightBar(Command cmd)

Adds a Command to the TitleArea on the right side.

Parameters:

cmd - a Command

addCommandToLeftBar

public Command addCommandToLeftBar(String name,
                                   Image icon,
                                   ActionListener ev)

Adds a Command to the TitleArea on the left side.

Parameters:

name - the name/title of the command

icon - the icon for the command

ev - the even handler

Returns:

a newly created Command instance

addCommandToLeftBar

public void addCommandToLeftBar(Command cmd)

Adds a Command to the TitleArea on the left side.

Parameters:

cmd - a Command

getRightBarCommands

public Iterable<Command> getRightBarCommands()

Returns the commands within the right bar section which can be useful for things like unit testing. Notice that you should not mutate the commands or the iteratable set in any way!

Returns:

the commands in the overflow menu

getLeftBarCommands

public Iterable<Command> getLeftBarCommands()

Returns the commands within the left bar section which can be useful for things like unit testing. Notice that you should not mutate the commands or the iteratable set in any way!

Returns:

the commands in the overflow menu

getMenuBar

public MenuBar getMenuBar()

Returns the associated SideMenuBar object of this Toolbar.

Returns:

the associated SideMenuBar object

showOverflowMenu

protected Command showOverflowMenu(Dialog menu)

createOverflowCommandList

protected List createOverflowCommandList(Vector commands)

Creates the list component containing the commands within the given vector used for showing the menu dialog

Parameters:

commands - list of command objects

Returns:

List object

initTitleBarStatus

protected void initTitleBarStatus()

Adds a status bar space to the north of the Component, subclasses can override this default behavior.

setScrollOffUponContentPane

public void setScrollOffUponContentPane(boolean scrollOff)

Sets the Toolbar to scroll off the screen upon content scroll. This feature can only work if the Form contentPane is scrollableY

Parameters:

scrollOff - if true the Toolbar needs to scroll off the screen when the Form ContentPane is scrolled

hideToolbar

public void hideToolbar()

Hide the Toolbar if it is currently showing

showToolbar

public void showToolbar()

Show the Toolbar if it is currently not showing

animate

public boolean animate()

Description copied from class: Component

Allows the animation to reduce "repaint" calls when it returns false. It is called once for every frame. Frames are defined by the Display class.

Specified by:

animate in interface Animation

Overrides:

animate in class Component

Returns:

true if a repaint is desired or false if no repaint is necessary

createSideNavigationComponent

protected Container createSideNavigationComponent(Vector commands,
                                                  String placement)

Creates the side navigation component with the Commands.

Parameters:

commands - the Command objects

Returns:

the Component to display on the side navigation

constructSideNavigationComponent

protected Container constructSideNavigationComponent()

Creates an empty left side navigation panel.

constructRightSideNavigationComponent

protected Container constructRightSideNavigationComponent()

Creates an empty right side navigation panel.

addComponentToLeftSideMenu

protected void addComponentToLeftSideMenu(Container menu,
                                          Component cmp)

This method responsible to add a Component to the left side navigation panel.

Parameters:

menu - the Menu Container that was created in the constructSideNavigationComponent() method

cmp - the Component to add to the side menu

addComponentToRightSideMenu

protected void addComponentToRightSideMenu(Container menu,
                                           Component cmp)

This method responsible to add a Component to the right side navigation panel.

Parameters:

menu - the Menu Container that was created in the constructSideNavigationComponent() method

cmp - the Component to add to the side menu

getSideMenuCommands

public Iterable<Command> getSideMenuCommands()

Returns the commands within the left side menu which can be useful for things like unit testing. Notice that you should not mutate the commands or the iteratable set in any way!

Returns:

the commands in the left side menu

getRightSideMenuCommands

public Iterable<Command> getRightSideMenuCommands()

Returns the commands within the right side menu which can be useful for things like unit testing. Notice that you should not mutate the commands or the iteratable set in any way!

Returns:

the commands in the right side menu

removeOverflowCommand

public void removeOverflowCommand(Command cmd)

Removes the given overflow menu command, notice that this has no effect on the menu that is currently showing (if it is currently showing) only on the upcoming iterations.

Parameters:

cmd - the command to remove from the overflow

setRightSideMenuCmdsAlignedToLeft

public void setRightSideMenuCmdsAlignedToLeft(boolean toLeft)

Normally on a right side menu the alignment should be "mirrored" in comparision with the left side menu, also for non-RTL languages: this method allows to change this default behaviour for non-RTL languages, forcing the alignment of the Commands of the right side menu to left. Note that for RTL languages this method does nothing. This method should be called before adding commands to the right side menu.

Parameters:

toLeft - false is the default, true changes the alignment.