Package com.smartgwt.client.widgets.menu

Class Menu

java.lang.Object
com.google.gwt.user.client.ui.UIObject
com.google.gwt.user.client.ui.Widget
com.smartgwt.client.widgets.BaseWidget
com.smartgwt.client.widgets.Canvas
com.smartgwt.client.widgets.layout.Layout
com.smartgwt.client.widgets.layout.VLayout
com.smartgwt.client.widgets.grid.ListGrid
com.smartgwt.client.widgets.menu.Menu
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsWidget, LogicalStructure, DataBoundComponent, HasClearHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragCompleteHandlers, HasDragMoveHandlers, HasDragRepositionMoveHandlers, HasDragRepositionStartHandlers, HasDragRepositionStopHandlers, HasDragResizeMoveHandlers, HasDragResizeStartHandlers, HasDragResizeStopHandlers, HasDragStartHandlers, HasDragStopHandlers, HasDropCompleteHandlers, HasDropHandlers, HasDropMoveHandlers, HasDropOutHandlers, HasDropOverHandlers, HasFetchDataHandlers, HasFocusChangedHandlers, HasFormulaUpdatedHandlers, HasHoverHandlers, HasHoverHiddenHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseStillDownHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasMovedHandlers, HasParentMovedHandlers, HasResizedHandlers, HasRightMouseDownHandlers, HasRuleContextChangedHandlers, HasScrolledHandlers, HasShowContextMenuHandlers, HasVisibilityChangedHandlers, HasBodyKeyPressHandlers, HasCellClickHandlers, HasCellContextClickHandlers, HasCellDoubleClickHandlers, HasCellErrorIconHoverHandlers, HasCellErrorIconOutHandlers, HasCellErrorIconOverHandlers, HasCellHoverHandlers, HasCellMouseDownHandlers, HasCellMouseUpHandlers, HasCellOutHandlers, HasCellOverHandlers, HasCellSavedHandlers, HasCellSelectionChangedHandlers, HasCellValueHoverHandlers, HasCriteriaChangedHandlers, HasDataArrivedHandlers, HasDataChangedHandlers, HasDrawAreaChangedHandlers, HasEditCompleteHandlers, HasEditFailedHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFieldStateChangedHandlers, HasFilterEditorSubmitHandlers, HasGroupByCompleteHandlers, HasGroupByHandlers, HasGroupStateChangedHandlers, HasGroupTreeChangedHandlers, HasHeaderClickHandlers, HasHeaderDoubleClickHandlers, HasHeaderHoverHandlers, HasHilitesChangedHandlers, HasRecordClickHandlers, HasRecordCollapseHandlers, HasRecordDoubleClickHandlers, HasRecordDropHandlers, HasRecordExpandHandlers, HasRegroupHandlers, HasRemoveRecordClickHandlers, HasRowContextClickHandlers, HasRowEditorEnterHandlers, HasRowEditorExitHandlers, HasRowHoverHandlers, HasRowMouseDownHandlers, HasRowMouseUpHandlers, HasRowOutHandlers, HasRowOverHandlers, HasSelectionChangedHandlers, HasSelectionUpdatedHandlers, HasSetSortHandlers, HasSortChangedHandlers, HasSorterClickHandlers, HasSorterContextClickHandlers, HasViewStateChangedHandlers, HasMembersChangedHandlers, HasItemClickHandlers
Direct Known Subclasses:
MenuPalette, SelectionTreeMenu
public class Menu extends ListGrid implements HasItemClickHandlers
The Menu widget class implements interactive menu widgets, with optional icons, submenus, and shortcut keys.

A Menu is initialized with a set of MenuItems specified as items, each of which represents one row in the menu's display and specifies the action to take when that menu item is selected.

Each MenuItem can have a title, icon, shortcut keys, optional MenuItem.submenu and various other settings. Alternatively, a MenuItem can contain an arbitrary widget via MenuItem.embeddedComponent.

To create a context menu for a component, provide a Menu instance for the Canvas.contextMenu property. Note that some components like ListGrid have more specific properties because they have distinct regions or because they have a default set of context menu actions available (for example: ListGrid.headerContextMenu and related APIs).

If you want a button that pops up a menu when clicked, or a bar of such buttons, see the MenuButton and MenuBar classes.

To create a pop-up panel interface that looks nothing like a Menu (but still dismisses automatically on an outside click), use Canvas.showClickMask() to arrange for automatic dismissal, and the Canvas.showNextTo() utility method to place the component near whatever triggered it, while automatically staying on-screen.

  • Field Details

  • Constructor Details

  • Method Details

    • getOrCreateRef

      public static Menu getOrCreateRef(JavaScriptObject jsObj)

    • getTestInstance

      protected Menu getTestInstance()
      Overrides:
      getTestInstance in class ListGrid

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • create

      protected JavaScriptObject create()
      Overrides:
      create in class ListGrid

    • setAlternateRecordStyles

      public Menu setAlternateRecordStyles(Boolean alternateRecordStyles)
      Explicitly disable alternateRecordStyles at the menu level by default so setting to true for all ListGrids will not impact menus' appearance.
      Overrides:
      setAlternateRecordStyles in class ListGrid
      Parameters:
      alternateRecordStyles - New alternateRecordStyles value. Default value is false
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getAlternateRecordStyles

      public Boolean getAlternateRecordStyles()
      Explicitly disable alternateRecordStyles at the menu level by default so setting to true for all ListGrids will not impact menus' appearance.
      Overrides:
      getAlternateRecordStyles in class ListGrid
      Returns:
      Current alternateRecordStyles value. Default value is false
      See Also:

    • setAutoDismiss

      public Menu setAutoDismiss(Boolean autoDismiss)
      When false, when a menu item is chosen (via mouse click or keyboard), the menu is not automatically hidden, staying in place for further interactivity
      Parameters:
      autoDismiss - New autoDismiss value. Default value is true
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getAutoDismiss

      public Boolean getAutoDismiss()
      When false, when a menu item is chosen (via mouse click or keyboard), the menu is not automatically hidden, staying in place for further interactivity
      Returns:
      Current autoDismiss value. Default value is true
      See Also:

    • setAutoDismissOnBlur

      public Menu setAutoDismissOnBlur(Boolean autoDismissOnBlur)
      When false, when a user clicks outside the menu, or hits the Escape key, this menu will not be automatically hidden, staying in place for further interactivity.
      Parameters:
      autoDismissOnBlur - New autoDismissOnBlur value. Default value is true
      Returns:
      Menu instance, for chaining setter calls

    • getAutoDismissOnBlur

      public Boolean getAutoDismissOnBlur()
      When false, when a user clicks outside the menu, or hits the Escape key, this menu will not be automatically hidden, staying in place for further interactivity.
      Returns:
      Current autoDismissOnBlur value. Default value is true

    • setAutoDraw

      public Menu setAutoDraw(Boolean autoDraw)
      Menus will not draw on initialization, until they're explicitly show()n

      Note : This is an advanced setting

      Parameters:
      autoDraw - New autoDraw value. Default value is false
      Returns:
      Menu instance, for chaining setter calls

    • getAutoDraw

      public Boolean getAutoDraw()
      Menus will not draw on initialization, until they're explicitly show()n
      Returns:
      Current autoDraw value. Default value is false

    • setBaseStyle

      public Menu setBaseStyle(String baseStyle)
      CSS style for a normal cell
      Overrides:
      setBaseStyle in class ListGrid
      Parameters:
      baseStyle - New baseStyle value. Default value is "menu"
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getBaseStyle

      public String getBaseStyle()
      CSS style for a normal cell
      Overrides:
      getBaseStyle in class ListGrid
      Returns:
      Current baseStyle value. Default value is "menu"
      See Also:

    • setBodyStyleName

      public Menu setBodyStyleName(String bodyStyleName)
      CSS style used for the body of this menu when there is no icon field. When there is an icon field, then iconBodyStyleName, if set, will override this setting.

      If applying a background-color to the body via a CSS style applied using this property, be sure to set bodyBackgroundColor to null.

      Overrides:
      setBodyStyleName in class ListGrid
      Parameters:
      bodyStyleName - New bodyStyleName value. Default value is "normal"
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getBodyStyleName

      public String getBodyStyleName()
      CSS style used for the body of this menu when there is no icon field. When there is an icon field, then iconBodyStyleName, if set, will override this setting.

      If applying a background-color to the body via a CSS style applied using this property, be sure to set bodyBackgroundColor to null.

      Overrides:
      getBodyStyleName in class ListGrid
      Returns:
      Current bodyStyleName value. Default value is "normal"
      See Also:

    • setCancelButtonTitle

      public Menu setCancelButtonTitle(String cancelButtonTitle) throws IllegalStateException
      Title for the "Done" button shown when the NavigationBar is present.
      Parameters:
      cancelButtonTitle - New cancelButtonTitle value. Default value is "Done"
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getCancelButtonTitle

      public String getCancelButtonTitle()
      Title for the "Done" button shown when the NavigationBar is present.
      Returns:
      Current cancelButtonTitle value. Default value is "Done"
      See Also:

    • setCanSaveSearches

      public Menu setCanSaveSearches(boolean canSaveSearches) throws IllegalStateException
      Option to save searches is disabled for menus

      Note : This is an advanced setting

      Overrides:
      setCanSaveSearches in class ListGrid
      Parameters:
      canSaveSearches - New canSaveSearches value. Default value is false
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getCanSaveSearches

      public boolean getCanSaveSearches()
      Option to save searches is disabled for menus
      Overrides:
      getCanSaveSearches in class ListGrid
      Returns:
      Current canSaveSearches value. Default value is false

    • setCanSelectParentItems

      public Menu setCanSelectParentItems(Boolean canSelectParentItems)
      If true, clicking or pressing Enter on a menu item that has a submenu will select that item (with standard behavior of hiding the menus, calling click handlers, etc) instead of showing the submenu.
      Parameters:
      canSelectParentItems - New canSelectParentItems value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getCanSelectParentItems

      public Boolean getCanSelectParentItems()
      If true, clicking or pressing Enter on a menu item that has a submenu will select that item (with standard behavior of hiding the menus, calling click handlers, etc) instead of showing the submenu.
      Returns:
      Current canSelectParentItems value. Default value is null
      See Also:

    • setCanShowFilterEditor

      public Menu setCanShowFilterEditor(boolean canShowFilterEditor) throws IllegalStateException
      Option to show filter editor is disabled for menus

      Note : This is an advanced setting

      Overrides:
      setCanShowFilterEditor in class ListGrid
      Parameters:
      canShowFilterEditor - New canShowFilterEditor value. Default value is false
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getCanShowFilterEditor

      public boolean getCanShowFilterEditor()
      Option to show filter editor is disabled for menus
      Overrides:
      getCanShowFilterEditor in class ListGrid
      Returns:
      Current canShowFilterEditor value. Default value is false
      See Also:

    • setCascadeAutoDismiss

      public Menu setCascadeAutoDismiss(Boolean cascadeAutoDismiss)
      When true any generated submenus will inherit autoDismiss from this menu.
      Parameters:
      cascadeAutoDismiss - New cascadeAutoDismiss value. Default value is true
      Returns:
      Menu instance, for chaining setter calls

    • getCascadeAutoDismiss

      public Boolean getCascadeAutoDismiss()
      When true any generated submenus will inherit autoDismiss from this menu.
      Returns:
      Current cascadeAutoDismiss value. Default value is true

    • setCellHeight

      public Menu setCellHeight(int cellHeight)
      The height of each item in the menu, in pixels.
      Overrides:
      setCellHeight in class ListGrid
      Parameters:
      cellHeight - New cellHeight value. Default value is 20
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getCellHeight

      public int getCellHeight()
      The height of each item in the menu, in pixels.
      Overrides:
      getCellHeight in class ListGrid
      Returns:
      Current cellHeight value. Default value is 20
      See Also:

    • setCheckmarkDisabledImage

      public Menu setCheckmarkDisabledImage(String checkmarkDisabledImage) throws IllegalStateException
      Default image to display for check-marked items when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Parameters:
      checkmarkDisabledImage - New checkmarkDisabledImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getCheckmarkDisabledImage

      public String getCheckmarkDisabledImage()
      Default image to display for check-marked items when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Returns:
      Current checkmarkDisabledImage value. Default value is {...}
      See Also:

    • setCheckmarkDisabledImage

      public Menu setCheckmarkDisabledImage(ImgHTMLProperties checkmarkDisabledImage) throws IllegalStateException
      Default image to display for check-marked items when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Parameters:
      checkmarkDisabledImage - New checkmarkDisabledImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getCheckmarkDisabledImageAsImgHTMLProperties

      public ImgHTMLProperties getCheckmarkDisabledImageAsImgHTMLProperties()
      Default image to display for check-marked items when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Returns:
      Current checkmarkDisabledImage value. Default value is {...}
      See Also:

    • setCheckmarkImage

      public Menu setCheckmarkImage(String checkmarkImage) throws IllegalStateException
      Default image to display for check-marked items. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Parameters:
      checkmarkImage - New checkmarkImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getCheckmarkImage

      public String getCheckmarkImage()
      Default image to display for check-marked items. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Returns:
      Current checkmarkImage value. Default value is {...}
      See Also:

    • setCheckmarkImage

      public Menu setCheckmarkImage(ImgHTMLProperties checkmarkImage) throws IllegalStateException
      Default image to display for check-marked items. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Parameters:
      checkmarkImage - New checkmarkImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getCheckmarkImageAsImgHTMLProperties

      public ImgHTMLProperties getCheckmarkImageAsImgHTMLProperties()
      Default image to display for check-marked items. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.
      Returns:
      Current checkmarkImage value. Default value is {...}
      See Also:

    • setData

      public Menu setData(MenuItem... data)
      An array of menuItem objects, specifying the menu items this menu should show.

      Data may also be set to a Tree in which case a hierarchy of menus and submenus will automatically be generated to match the tree structure. See also dataSource for dynamically fetching menuItems and submenus from a hierarchical DataSource.

      Note that items that are marked as hidden will be automatically filtered out of the data dispayed to the user. To retrieve the full set of items at runtime, including hidden items, use getAllItems().

      If this method is called after the component has been drawn/initialized: Change the set of items to display in this menu. Note that if filterHiddenItems is true and any items are hidden, data supplied as an Array will be converted to a FilteredList in order to filter out hidden items. To get the full specified data set as an array, including hidden items, use getAllItems().

      Parameters:
      data - new items for this menu. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • setData

      public Menu setData(Record[] data)
      An array of menuItem objects, specifying the menu items this menu should show.

      Data may also be set to a Tree in which case a hierarchy of menus and submenus will automatically be generated to match the tree structure. See also dataSource for dynamically fetching menuItems and submenus from a hierarchical DataSource.

      Note that items that are marked as hidden will be automatically filtered out of the data dispayed to the user. To retrieve the full set of items at runtime, including hidden items, use getAllItems().

      If this method is called after the component has been drawn/initialized: Change the set of items to display in this menu. Note that if filterHiddenItems is true and any items are hidden, data supplied as an Array will be converted to a FilteredList in order to filter out hidden items. To get the full specified data set as an array, including hidden items, use getAllItems().

      Overrides:
      setData in class ListGrid
      Parameters:
      data - new items for this menu. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • setData

      public Menu setData(Tree data)
      An array of menuItem objects, specifying the menu items this menu should show.

      Data may also be set to a Tree in which case a hierarchy of menus and submenus will automatically be generated to match the tree structure. See also dataSource for dynamically fetching menuItems and submenus from a hierarchical DataSource.

      Note that items that are marked as hidden will be automatically filtered out of the data dispayed to the user. To retrieve the full set of items at runtime, including hidden items, use getAllItems().

      If this method is called after the component has been drawn/initialized: Change the set of items to display in this menu. Note that if filterHiddenItems is true and any items are hidden, data supplied as an Array will be converted to a FilteredList in order to filter out hidden items. To get the full specified data set as an array, including hidden items, use getAllItems().

      Parameters:
      data - new items for this menu. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • setData

      public Menu setData(RecordList data)
      An array of menuItem objects, specifying the menu items this menu should show.

      Data may also be set to a Tree in which case a hierarchy of menus and submenus will automatically be generated to match the tree structure. See also dataSource for dynamically fetching menuItems and submenus from a hierarchical DataSource.

      Note that items that are marked as hidden will be automatically filtered out of the data dispayed to the user. To retrieve the full set of items at runtime, including hidden items, use getAllItems().

      If this method is called after the component has been drawn/initialized: Change the set of items to display in this menu. Note that if filterHiddenItems is true and any items are hidden, data supplied as an Array will be converted to a FilteredList in order to filter out hidden items. To get the full specified data set as an array, including hidden items, use getAllItems().

      Overrides:
      setData in class ListGrid
      Parameters:
      data - new items for this menu. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • setDataSource

      public Menu setDataSource(DataSource dataSource) throws IllegalStateException
      Optional DataSource to fetch menuItems and submenus from, instead of using items.

      Data is tree-based in menus, so the provided DataSource should be set up for hierarchical fetching - see the Tree Data Binding overview.

      Note that, although Menu is a subclass of ListGrid, some APIs, like setCriteria and autoFetchData are not supported in menus. If a dataSource is supplied, it is automatically fetched against as required, without the need for autoFetchData. To apply criteria to the fetches made in this way, see initialCriteria.
      Moreover, fetchData() is also an example of a ListGrid API that doesn't apply to menu, and, as was done for setCriteria() and other APIs like setCriteria().

      Specified by:
      setDataSource in interface DataBoundComponent
      Overrides:
      setDataSource in class ListGrid
      Parameters:
      dataSource - New dataSource value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getDataSource

      public DataSource getDataSource()
      Optional DataSource to fetch menuItems and submenus from, instead of using items.

      Data is tree-based in menus, so the provided DataSource should be set up for hierarchical fetching - see the Tree Data Binding overview.

      Note that, although Menu is a subclass of ListGrid, some APIs, like setCriteria and autoFetchData are not supported in menus. If a dataSource is supplied, it is automatically fetched against as required, without the need for autoFetchData. To apply criteria to the fetches made in this way, see initialCriteria.
      Moreover, fetchData() is also an example of a ListGrid API that doesn't apply to menu, and, as was done for setCriteria() and other APIs like setCriteria().

      Specified by:
      getDataSource in interface DataBoundComponent
      Overrides:
      getDataSource in class ListGrid
      Returns:
      Current dataSource value. Default value is null

    • setDefaultWidth

      public Menu setDefaultWidth(int defaultWidth)
      The default menu width.
      Overrides:
      setDefaultWidth in class Canvas
      Parameters:
      defaultWidth - New defaultWidth value. Default value is 150
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getDefaultWidth

      public int getDefaultWidth()
      The default menu width.
      Overrides:
      getDefaultWidth in class Canvas
      Returns:
      Current defaultWidth value. Default value is 150
      See Also:

    • setEditProxyConstructor

      public Menu setEditProxyConstructor(String editProxyConstructor) throws IllegalStateException
      Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
      Overrides:
      setEditProxyConstructor in class ListGrid
      Parameters:
      editProxyConstructor - New editProxyConstructor value. Default value is "MenuEditProxy"
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getEditProxyConstructor

      public String getEditProxyConstructor()
      Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
      Overrides:
      getEditProxyConstructor in class ListGrid
      Returns:
      Current editProxyConstructor value. Default value is "MenuEditProxy"
      See Also:

    • setEmptyMessage

      public Menu setEmptyMessage(String emptyMessage)
      Message to show when a menu is shown with no items.

      Note : This is an advanced setting

      Overrides:
      setEmptyMessage in class ListGrid
      Parameters:
      emptyMessage - New emptyMessage value. Default value is "[Empty menu]"
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getEmptyMessage

      public String getEmptyMessage()
      Message to show when a menu is shown with no items.
      Overrides:
      getEmptyMessage in class ListGrid
      Returns:
      Current emptyMessage value. Default value is "[Empty menu]"
      See Also:

    • setFetchSubmenus

      public Menu setFetchSubmenus(Boolean fetchSubmenus) throws IllegalStateException
      When using a Tree or hierarchical DataSource as the menu's data, submenus are automatically generated from child nodes. fetchSubmenus can be set to false to disable this for the whole menu, or can be set false on a per-item basis via MenuItem.fetchSubmenus.
      Parameters:
      fetchSubmenus - New fetchSubmenus value. Default value is true
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFetchSubmenus

      public Boolean getFetchSubmenus()
      When using a Tree or hierarchical DataSource as the menu's data, submenus are automatically generated from child nodes. fetchSubmenus can be set to false to disable this for the whole menu, or can be set false on a per-item basis via MenuItem.fetchSubmenus.
      Returns:
      Current fetchSubmenus value. Default value is true

    • setFillSpaceStyleName

      public Menu setFillSpaceStyleName(String fillSpaceStyleName) throws IllegalStateException
      If set, alternative body style for the menu used when there is no icon field and the placement settings indicate the menu will be filling a portion of the screen or a panel. Generally this alternative style should not have rounded or excessively large edges. If unset, then bodyStyleName is used instead.

      When there is an icon field, iconFillSpaceStyleName, if set, overrides this setting.

      Parameters:
      fillSpaceStyleName - New fillSpaceStyleName value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getFillSpaceStyleName

      public String getFillSpaceStyleName()
      If set, alternative body style for the menu used when there is no icon field and the placement settings indicate the menu will be filling a portion of the screen or a panel. Generally this alternative style should not have rounded or excessively large edges. If unset, then bodyStyleName is used instead.

      When there is an icon field, iconFillSpaceStyleName, if set, overrides this setting.

      Returns:
      Current fillSpaceStyleName value. Default value is null
      See Also:

    • setFilterHiddenItems

      public Menu setFilterHiddenItems(Boolean filterHiddenItems) throws IllegalStateException
      Does this hide menu items marked as hidden menu items by filtering them out of the data set?

      In order to support hiding items marked as hidden, if any items are hidden or marked with visibleWhen rules, Menus convert the specified array of items to a FilteredList with criteria set to filter out items marked with the itemHiddenProperty.

      Note that this means for filterHiddenItems:true menus, developers wishing to interact with the menu data set must use List APIs such as menu.getData().getLength() and menu.getData().get(index), rather than accessing simple array attributes such as menu.getData().length or menu.getData()[index]

      To get the full specified data set as an array, including hidden items, use getAllItems().

      Note : This is an advanced setting

      Parameters:
      filterHiddenItems - New filterHiddenItems value. Default value is true
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFilterHiddenItems

      public Boolean getFilterHiddenItems()
      Does this hide menu items marked as hidden menu items by filtering them out of the data set?

      In order to support hiding items marked as hidden, if any items are hidden or marked with visibleWhen rules, Menus convert the specified array of items to a FilteredList with criteria set to filter out items marked with the itemHiddenProperty.

      Note that this means for filterHiddenItems:true menus, developers wishing to interact with the menu data set must use List APIs such as menu.getData().getLength() and menu.getData().get(index), rather than accessing simple array attributes such as menu.getData().length or menu.getData()[index]

      To get the full specified data set as an array, including hidden items, use getAllItems().

      Returns:
      Current filterHiddenItems value. Default value is true

    • setIconBodyStyleName

      public Menu setIconBodyStyleName(String iconBodyStyleName) throws IllegalStateException
      If set, the CSS style used for the body of this menu when there is an icon field. In RTL mode, the iconBodyStyleName is suffixed with "RTL", which allows skins to apply different styles in LTR and RTL modes.

      Note: Any skin which uses iconBodyStyleName should add "RTL" styles as well, even if identical to LTR styles. Otherwise, menus may lose their styling in RTL mode.

      Parameters:
      iconBodyStyleName - New iconBodyStyleName value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getIconBodyStyleName

      public String getIconBodyStyleName()
      If set, the CSS style used for the body of this menu when there is an icon field. In RTL mode, the iconBodyStyleName is suffixed with "RTL", which allows skins to apply different styles in LTR and RTL modes.

      Note: Any skin which uses iconBodyStyleName should add "RTL" styles as well, even if identical to LTR styles. Otherwise, menus may lose their styling in RTL mode.

      Returns:
      Current iconBodyStyleName value. Default value is null
      See Also:

    • setIconFieldProperties

      public Menu setIconFieldProperties(ListGridField iconFieldProperties) throws IllegalStateException
      Custom properties for the automatically generated icon column.

      See showIcons for an overview of the icon column.

      Parameters:
      iconFieldProperties - New iconFieldProperties value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getIconFieldProperties

      public ListGridField getIconFieldProperties()
      Custom properties for the automatically generated icon column.

      See showIcons for an overview of the icon column.

      Returns:
      Current iconFieldProperties value. Default value is null

    • setIconFillSpaceStyleName

      public Menu setIconFillSpaceStyleName(String iconFillSpaceStyleName) throws IllegalStateException
      If set, alternative body style for the menu used when there is an icon field and the placement settings indicate the menu will be filling a portion of the screen or a panel. Generally this alternative style should not have rounded or excessively large edges. In RTL mode, the iconFillSpaceStyleName is suffixed with "RTL", which allows skins to apply different styles in LTR and RTL modes. If unset, then iconBodyStyleName is used instead.

      Note: Like iconBodyStyleName, any skin which uses iconFillSpaceStyleName should add "RTL" styles as well, even if identical to LTR styles. Otherwise, menus may lose their styling in RTL mode.

      Parameters:
      iconFillSpaceStyleName - New iconFillSpaceStyleName value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getIconFillSpaceStyleName

      public String getIconFillSpaceStyleName()
      If set, alternative body style for the menu used when there is an icon field and the placement settings indicate the menu will be filling a portion of the screen or a panel. Generally this alternative style should not have rounded or excessively large edges. In RTL mode, the iconFillSpaceStyleName is suffixed with "RTL", which allows skins to apply different styles in LTR and RTL modes. If unset, then iconBodyStyleName is used instead.

      Note: Like iconBodyStyleName, any skin which uses iconFillSpaceStyleName should add "RTL" styles as well, even if identical to LTR styles. Otherwise, menus may lose their styling in RTL mode.

      Returns:
      Current iconFillSpaceStyleName value. Default value is null
      See Also:

    • setIconHeight

      public Menu setIconHeight(int iconHeight)
      The default height applied to custom icons in this menu. This is used whenever item.iconHeight is not specified.
      Parameters:
      iconHeight - New iconHeight value. Default value is 16
      Returns:
      Menu instance, for chaining setter calls

    • getIconHeight

      public int getIconHeight()
      The default height applied to custom icons in this menu. This is used whenever item.iconHeight is not specified.
      Returns:
      Current iconHeight value. Default value is 16

    • setIconWidth

      public Menu setIconWidth(int iconWidth)
      The default width applied to custom icons in this menu. This is used whenever item.iconWidth is not specified.
      Parameters:
      iconWidth - New iconWidth value. Default value is 16
      Returns:
      Menu instance, for chaining setter calls

    • getIconWidth

      public int getIconWidth()
      The default width applied to custom icons in this menu. This is used whenever item.iconWidth is not specified.
      Returns:
      Current iconWidth value. Default value is 16

    • setInitialCriteria

      public Menu setInitialCriteria(Criteria initialCriteria) throws IllegalStateException
      Criteria to be used when fetching items for this Menu. Note that setCriteria is not supported in Menus.
      Specified by:
      setInitialCriteria in interface DataBoundComponent
      Overrides:
      setInitialCriteria in class ListGrid
      Parameters:
      initialCriteria - New initialCriteria value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getInitialCriteria

      public Criteria getInitialCriteria()
      Criteria to be used when fetching items for this Menu. Note that setCriteria is not supported in Menus.
      Specified by:
      getInitialCriteria in interface DataBoundComponent
      Overrides:
      getInitialCriteria in class ListGrid
      Returns:
      Current initialCriteria value. Default value is null
      See Also:

    • setItemHiddenProperty

      public Menu setItemHiddenProperty(String itemHiddenProperty)
      Items with this property set to true will be hidden within the menu.

      Note : This is an advanced setting

      Parameters:
      itemHiddenProperty - New itemHiddenProperty value. Default value is "hidden"
      Returns:
      Menu instance, for chaining setter calls
      See Also:

    • getItemHiddenProperty

      public String getItemHiddenProperty()
      Items with this property set to true will be hidden within the menu.
      Returns:
      Current itemHiddenProperty value. Default value is "hidden"
      See Also:

    • setItems

      public Menu setItems(MenuItem... items)
      Synonym for data

      If this method is called after the component has been drawn/initialized: Synonym for setData().
      Parameters:
      items - new items for this menu. Default value is null
      Returns:
      Menu instance, for chaining setter calls

    • setKeyFieldProperties

      public Menu setKeyFieldProperties(ListGridField keyFieldProperties) throws IllegalStateException
      Custom properties for the automatically generated key column.

      See showKeys for an overview of the key column.

      Parameters:
      keyFieldProperties - New keyFieldProperties value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getKeyFieldProperties

      public ListGridField getKeyFieldProperties()
      Custom properties for the automatically generated key column.

      See showKeys for an overview of the key column.

      Returns:
      Current keyFieldProperties value. Default value is null

    • setMenuButtonWidth

      public Menu setMenuButtonWidth(Integer menuButtonWidth) throws IllegalStateException
      For a menu that has a MenuButton generated for it automatically (for example when included in a MenuBar, the width that the MenuButton should have. If unset, the MenuButton will be as wide as menu.width.
      Parameters:
      menuButtonWidth - New menuButtonWidth value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMenuButtonWidth

      public Integer getMenuButtonWidth()
      For a menu that has a MenuButton generated for it automatically (for example when included in a MenuBar, the width that the MenuButton should have. If unset, the MenuButton will be as wide as menu.width.
      Returns:
      Current menuButtonWidth value. Default value is null

    • getNavigationBar

      public NavigationBar getNavigationBar() throws IllegalStateException
      Navigation bar shown when placement setting indicates that the menu should be shown filling a portion of the screen or a panel.

      This component is an AutoChild named "navigationBar". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current navigationBar value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • getNavStack

      public Canvas getNavStack() throws IllegalStateException
      When the placement setting indicates that the menu should be shown filling a portion of the screen or a panel, navStack is a container element created to hold the NavigationBar and any submenus that are shown by the menu.

      This component is an AutoChild named "navStack". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current navStack value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setPlacement

      public Menu setPlacement(PanelPlacement placement) throws IllegalStateException
      Where should the menu be placed on the screen?

      Default is to use PanelPlacement "fillScreen" if isHandset. In any non-handset device, placement is unset, so the menu defaults to normal placement (near the originating MenuButton, or the mouse for a context menu, or according to left/top/width/height for a manually created Menu).

      When using any placement setting that fills a portion of the screen or a panel, submenus are displayed by sliding them into place on top of the currently active menu, and a menu.navigationBar is used to manage navigation to the main menu (and provide dismissal, via a cancel button.

      Parameters:
      placement - New placement value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getPlacement

      public PanelPlacement getPlacement()
      Where should the menu be placed on the screen?

      Default is to use PanelPlacement "fillScreen" if isHandset. In any non-handset device, placement is unset, so the menu defaults to normal placement (near the originating MenuButton, or the mouse for a context menu, or according to left/top/width/height for a manually created Menu).

      When using any placement setting that fills a portion of the screen or a panel, submenus are displayed by sliding them into place on top of the currently active menu, and a menu.navigationBar is used to manage navigation to the main menu (and provide dismissal, via a cancel button.

      Returns:
      Current placement value. Default value is null

    • setShowAnimationEffect

      public Menu setShowAnimationEffect(String showAnimationEffect)
      When this menu is shown how should it animate into view? By default the menu will just show at the specified size/position. Options for animated show effects are "fade" to fade from transparent to visible, "slide" to slide the menu into view, or "wipe" to have the menu grow into view, revealing its content as it grows. Can be overridden by passing the 'animationEffect' parameter to 'menu.show()'

      Note : This is an advanced setting

      Parameters:
      showAnimationEffect - New showAnimationEffect value. Default value is null
      Returns:
      Menu instance, for chaining setter calls

    • getShowAnimationEffect

      public String getShowAnimationEffect()
      When this menu is shown how should it animate into view? By default the menu will just show at the specified size/position. Options for animated show effects are "fade" to fade from transparent to visible, "slide" to slide the menu into view, or "wipe" to have the menu grow into view, revealing its content as it grows. Can be overridden by passing the 'animationEffect' parameter to 'menu.show()'
      Returns:
      Current showAnimationEffect value. Default value is null

    • setShowEdges

      public Menu setShowEdges(Boolean showEdges) throws IllegalStateException
      showEdges dynamically defaults to false when the placement setting indicates the Menu will be filling a portion of the screen or a panel.
      Overrides:
      setShowEdges in class Canvas
      Parameters:
      showEdges - New showEdges value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getShowEdges

      public Boolean getShowEdges()
      showEdges dynamically defaults to false when the placement setting indicates the Menu will be filling a portion of the screen or a panel.
      Overrides:
      getShowEdges in class Canvas
      Returns:
      Current showEdges value. Default value is null
      See Also:

    • setShowIcons

      public Menu setShowIcons(Boolean showIcons)
      A boolean, indicating whether the checkmark/custom icon column should be displayed.

      If this method is called after the component has been drawn/initialized: Show or hide the checkmark/custom icon column at runtime.
      Parameters:
      showIcons - whether the icon column should be displayed. Default value is true
      Returns:
      Menu instance, for chaining setter calls

    • getShowIcons

      public Boolean getShowIcons()
      A boolean, indicating whether the checkmark/custom icon column should be displayed.
      Returns:
      Current showIcons value. Default value is true

    • setShowKeys

      public Menu setShowKeys(Boolean showKeys)
      A boolean, indicating whether the shortcut key column should be displayed. If showKeys is not set, the menu will show the key column only if one of its items specifies a keys property. If showKeys is false, the keys will not be displayed, but will still function.
      Parameters:
      showKeys - New showKeys value. Default value is true
      Returns:
      Menu instance, for chaining setter calls

    • getShowKeys

      public Boolean getShowKeys()
      A boolean, indicating whether the shortcut key column should be displayed. If showKeys is not set, the menu will show the key column only if one of its items specifies a keys property. If showKeys is false, the keys will not be displayed, but will still function.
      Returns:
      Current showKeys value. Default value is true

    • setShowShadow

      public Menu setShowShadow(Boolean showShadow) throws IllegalStateException
      Whether to show a drop shadow for this Canvas.

      Developers should be aware that the drop shadow is drawn outside the specified width and height of the widget meaning a widget with shadows takes up a little more space than it otherwise would. A full screen canvas with showShadow set to true as this would be likely to cause browser scrollbars to appear - developers can handle this by either setting this property to false on full-screen widgets, or by setting overflow to "hidden" on the <body> element browser-level scrolling is never intended to occur.

      showShadow dynamically defaults to false when the placement setting indicates the Menu will be filling a portion of the screen or a panel.

      Overrides:
      setShowShadow in class Canvas
      Parameters:
      showShadow - New showShadow value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getShowShadow

      public Boolean getShowShadow()
      Whether to show a drop shadow for this Canvas.

      Developers should be aware that the drop shadow is drawn outside the specified width and height of the widget meaning a widget with shadows takes up a little more space than it otherwise would. A full screen canvas with showShadow set to true as this would be likely to cause browser scrollbars to appear - developers can handle this by either setting this property to false on full-screen widgets, or by setting overflow to "hidden" on the <body> element browser-level scrolling is never intended to occur.

      showShadow dynamically defaults to false when the placement setting indicates the Menu will be filling a portion of the screen or a panel.

      Overrides:
      getShowShadow in class Canvas
      Returns:
      Current showShadow value. Default value is null
      See Also:

    • setShowSubmenus

      public Menu setShowSubmenus(Boolean showSubmenus)
      A boolean, indicating whether the submenu indicator column should be displayed. If showSubmenus is not set, the menu will show the indicator column only if one of its items specifies a submenu property. If showSubmenus is false, the submenu arrows will not be displayed, but submenus will still appear on rollover.

      If this method is called after the component has been drawn/initialized: Show or hide the submenu indicator column at runtime.
      Parameters:
      showSubmenus - whether the submenu indicator column should be displayed. Default value is true
      Returns:
      Menu instance, for chaining setter calls

    • getShowSubmenus

      public Boolean getShowSubmenus()
      A boolean, indicating whether the submenu indicator column should be displayed. If showSubmenus is not set, the menu will show the indicator column only if one of its items specifies a submenu property. If showSubmenus is false, the submenu arrows will not be displayed, but submenus will still appear on rollover.
      Returns:
      Current showSubmenus value. Default value is true

    • setSubmenuConstructor

      public Menu setSubmenuConstructor(String submenuConstructor) throws IllegalStateException
      When using a Tree or hierarchical DataSource as the menu's data, optional subclass of Menu that should be used when generating submenus.
      Parameters:
      submenuConstructor - New submenuConstructor value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getSubmenuConstructor

      public String getSubmenuConstructor()
      When using a Tree or hierarchical DataSource as the menu's data, optional subclass of Menu that should be used when generating submenus.
      Returns:
      Current submenuConstructor value. Default value is null
      See Also:

    • setSubmenuDirection

      public Menu setSubmenuDirection(String submenuDirection)
      Should submenus show up on our left or right. Can validly be set to "left" or "right". If unset, submenus show up on the right by default in Left-to-right text mode, or on the left in Right-to-left text mode (see Page.isRTL()).
      Parameters:
      submenuDirection - New submenuDirection value. Default value is null
      Returns:
      Menu instance, for chaining setter calls

    • getSubmenuDirection

      public String getSubmenuDirection()
      Should submenus show up on our left or right. Can validly be set to "left" or "right". If unset, submenus show up on the right by default in Left-to-right text mode, or on the left in Right-to-left text mode (see Page.isRTL()).
      Returns:
      Current submenuDirection value. Default value is null

    • setSubmenuDisabledImage

      public Menu setSubmenuDisabledImage(String submenuDisabledImage) throws IllegalStateException
      Default image to use for the submenu indicator when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Parameters:
      submenuDisabledImage - New submenuDisabledImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getSubmenuDisabledImage

      public String getSubmenuDisabledImage()
      Default image to use for the submenu indicator when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Returns:
      Current submenuDisabledImage value. Default value is {...}
      See Also:

    • setSubmenuDisabledImage

      public Menu setSubmenuDisabledImage(ImgHTMLProperties submenuDisabledImage) throws IllegalStateException
      Default image to use for the submenu indicator when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Parameters:
      submenuDisabledImage - New submenuDisabledImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getSubmenuDisabledImageAsImgHTMLProperties

      public ImgHTMLProperties getSubmenuDisabledImageAsImgHTMLProperties()
      Default image to use for the submenu indicator when the item is disabled. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Returns:
      Current submenuDisabledImage value. Default value is {...}
      See Also:

    • setSubmenuFieldProperties

      public Menu setSubmenuFieldProperties(ListGridField submenuFieldProperties) throws IllegalStateException
      Custom properties for the automatically generated submenu column.

      See showSubmenus for an overview of the submenu column.

      Parameters:
      submenuFieldProperties - New submenuFieldProperties value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSubmenuFieldProperties

      public ListGridField getSubmenuFieldProperties()
      Custom properties for the automatically generated submenu column.

      See showSubmenus for an overview of the submenu column.

      Returns:
      Current submenuFieldProperties value. Default value is null

    • setSubmenuImage

      public Menu setSubmenuImage(String submenuImage) throws IllegalStateException
      Default image to use for the submenu indicator. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Parameters:
      submenuImage - New submenuImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getSubmenuImage

      public String getSubmenuImage()
      Default image to use for the submenu indicator. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Returns:
      Current submenuImage value. Default value is {...}
      See Also:

    • setSubmenuImage

      public Menu setSubmenuImage(ImgHTMLProperties submenuImage) throws IllegalStateException
      Default image to use for the submenu indicator. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Parameters:
      submenuImage - New submenuImage value. Default value is {...}
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getSubmenuImageAsImgHTMLProperties

      public ImgHTMLProperties getSubmenuImageAsImgHTMLProperties()
      Default image to use for the submenu indicator. The value can be either a regular SCImgURL which can specify size:w,h;, or an ImgHTMLProperties object, specifying at least src, width and height.

      If submenuDirection is set to "left", the image src will have the suffix "_left" appended to it.

      Returns:
      Current submenuImage value. Default value is {...}
      See Also:

    • setTarget

      public Menu setTarget(Canvas target)
      Optional target canvas for this menu. Available as a parameter to dynamic menuItem configuration methods such as MenuItem.checkIf().

      Whenever a Menu is shown as a contextMenu by a widget due to Canvas.contextMenu being set, menu.target is automatically set to the widget that showed the contextMenu.

      If this item has any submenus the target will be propagated down to these child menus.

      Parameters:
      target - New target value. Default value is null
      Returns:
      Menu instance, for chaining setter calls

    • getTarget

      public Canvas getTarget()
      Optional target canvas for this menu. Available as a parameter to dynamic menuItem configuration methods such as MenuItem.checkIf().

      Whenever a Menu is shown as a contextMenu by a widget due to Canvas.contextMenu being set, menu.target is automatically set to the widget that showed the contextMenu.

      If this item has any submenus the target will be propagated down to these child menus.

      Returns:
      Current target value. Default value is null

    • setTitleFieldProperties

      public Menu setTitleFieldProperties(ListGridField titleFieldProperties) throws IllegalStateException
      Custom properties for the automatically generated title column.
      Parameters:
      titleFieldProperties - New titleFieldProperties value. Default value is null
      Returns:
      Menu instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTitleFieldProperties

      public ListGridField getTitleFieldProperties()
      Custom properties for the automatically generated title column.
      Returns:
      Current titleFieldProperties value. Default value is null

    • setUseKeys

      public Menu setUseKeys(Boolean useKeys)
      A boolean indicating whether this menu should use shortcut keys. Set useKeys to false in a menu's initialization block to explicitly disable shortcut keys.
      Parameters:
      useKeys - New useKeys value. Default value is true
      Returns:
      Menu instance, for chaining setter calls

    • getUseKeys

      public Boolean getUseKeys()
      A boolean indicating whether this menu should use shortcut keys. Set useKeys to false in a menu's initialization block to explicitly disable shortcut keys.
      Returns:
      Current useKeys value. Default value is true

    • fetchData

      public void fetchData()
      This DataBoundComponent method does not apply to Menu.
      Specified by:
      fetchData in interface DataBoundComponent
      Overrides:
      fetchData in class ListGrid

    • fetchData

      public void fetchData(Criteria criteria)
      Description copied from interface: DataBoundComponent
      Retrieves data from the DataSource that matches the specified criteria.

      When fetchData() is first called, if data has not already been provided via setData(), this method will create a ResultSet, which will be configured based on component settings such as fetchOperation and dataPageSize, as well as the general purpose dataProperties. The created ResultSet will automatically send a DSRequest to retrieve data from the dataSource, and from then on will automatically manage paging through large datasets, as well as performing filtering and sorting operations inside the browser when possible - see the ResultSet docs for details.

      NOTE: do not use both autoFetchData and a call to fetchData() - this may result in two DSRequests to fetch data. Use either autoFetchData and setAutoFetchCriteria() or a manual call to fetchData() passing criteria.

      Whether a ResultSet was automatically created or provided via setData(), subsequent calls to fetchData() will simply call resultSet.setCriteria().

      Changes to criteria may or may not result in a DSRequest to the server due to client-side filtering. You can call willFetchData(criteria) to determine if new criteria will result in a server fetch.

      If you need to force data to be re-fetched, you can call invalidateCache() and new data will automatically be fetched from the server using the current criteria and sort direction. NOTE: when using invalidateCache() there is no need to also call fetchData() and in fact this could produce unexpected results.

      This method takes an optional callback parameter (set to a DSCallback) to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed. In this case the data is updated synchronously, so as soon as this method completes you can interact with the new data. If necessary, you can use resultSet.willFetchData() to determine whether or not a server fetch will occur when fetchData() is called with new criteria.

      In addition to the callback parameter for this method, developers can use resultSet.addDataArrivedHandler to be notified every time data is loaded.

      Specified by:
      fetchData in interface DataBoundComponent
      Overrides:
      fetchData in class ListGrid
      Parameters:
      criteria - Search criteria. If a DynamicForm is passed in as this argument instead of a raw criteria object, will be derived by calling DynamicForm.getValuesAsCriteria()
      See Also:

    • fetchData

      public void fetchData(Criteria criteria, DSCallback callback)
      Description copied from interface: DataBoundComponent
      Retrieves data from the DataSource that matches the specified criteria.

      When fetchData() is first called, if data has not already been provided via setData(), this method will create a ResultSet, which will be configured based on component settings such as fetchOperation and dataPageSize, as well as the general purpose dataProperties. The created ResultSet will automatically send a DSRequest to retrieve data from the dataSource, and from then on will automatically manage paging through large datasets, as well as performing filtering and sorting operations inside the browser when possible - see the ResultSet docs for details.

      NOTE: do not use both autoFetchData and a call to fetchData() - this may result in two DSRequests to fetch data. Use either autoFetchData and setAutoFetchCriteria() or a manual call to fetchData() passing criteria.

      Whether a ResultSet was automatically created or provided via setData(), subsequent calls to fetchData() will simply call resultSet.setCriteria().

      Changes to criteria may or may not result in a DSRequest to the server due to client-side filtering. You can call willFetchData(criteria) to determine if new criteria will result in a server fetch.

      If you need to force data to be re-fetched, you can call invalidateCache() and new data will automatically be fetched from the server using the current criteria and sort direction. NOTE: when using invalidateCache() there is no need to also call fetchData() and in fact this could produce unexpected results.

      This method takes an optional callback parameter (set to a DSCallback) to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed. In this case the data is updated synchronously, so as soon as this method completes you can interact with the new data. If necessary, you can use resultSet.willFetchData() to determine whether or not a server fetch will occur when fetchData() is called with new criteria.

      In addition to the callback parameter for this method, developers can use resultSet.addDataArrivedHandler to be notified every time data is loaded.

      Specified by:
      fetchData in interface DataBoundComponent
      Overrides:
      fetchData in class ListGrid
      Parameters:
      criteria - Search criteria. If a DynamicForm is passed in as this argument instead of a raw criteria object, will be derived by calling DynamicForm.getValuesAsCriteria()
      callback - callback to invoke when a fetch is complete. Fires only if server contact was required
      See Also:

    • fetchData

      public void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
      This DataBoundComponent method does not apply to Menu.
      Specified by:
      fetchData in interface DataBoundComponent
      Overrides:
      fetchData in class ListGrid
      Parameters:
      criteria - Search criteria. If a DynamicForm is passed in as this argument instead of a raw criteria object, will be derived by calling DynamicForm.getValuesAsCriteria()
      callback - callback to invoke when a fetch is complete. Fires only if server contact was required
      requestProperties - additional properties to set on the DSRequest that will be issued

    • getAllItems

      public MenuItem[] getAllItems()
      Retrieves the full set of items for this menu, including hidden items
      Returns:

    • getCellStyle

      public String getCellStyle(ListGridRecord record, int rowNum, int colNum)
      Return the CSS class for a cell. By default this method has the following implementation:
      - return any custom style for the record (GridRenderer.recordCustomStyleProperty) if defined.
      - create a style name based on the result of GridRenderer.getBaseStyle() and the state of the record using the rules described in CellStyleSuffixes.

      Cell Styles are customizable by:

      • attaching a custom style to a record by setting record[this.recordCustomStyleProperty] to some valid CSS style name.
      • modifying the base style returned by getBaseStyle() [see that method for further documentation on this]
      • overriding this function

      In addition to this, getCellCSSText() may be overriden to provide custom cssText to apply on top of the styling attributes derived from the named style.

      Note: This is an override point.

      Overrides:
      getCellStyle in class ListGrid
      Parameters:
      record - record object for this row and column
      rowNum - number of the row
      colNum - number of the column
      Returns:
      CSS style for this cell. See CSSStyleName
      See Also:

    • getItem

      public MenuItem getItem(int item)
      Get a particular MenuItem by index. Note that by default the index passed in is interpreted as the position within currently visible set of items for the menu, not including hidden items.

      To look up an item based on its position in the full set of specified items, including those that are not visible, pass in the logicalIndex parameter.

      If passed a MenuItem, returns it.

      Parameters:
      item - index of the MenuItem
      Returns:
      the MenuItem, Pointer to the item, or null if not defined

    • getItem

      public MenuItem getItem(int item, boolean logicalIndex)
      Get a particular MenuItem by index. Note that by default the index passed in is interpreted as the position within currently visible set of items for the menu, not including hidden items.

      To look up an item based on its position in the full set of specified items, including those that are not visible, pass in the logicalIndex parameter.

      If passed a MenuItem, returns it.

      Parameters:
      item - index of the MenuItem
      logicalIndex - Interpret the index passed in with regards to the full set of specified items.
      Returns:
      the MenuItem, Pointer to the item, or null if not defined

    • getVisibleItemNum

      public int getVisibleItemNum(MenuItem item)
      Given a MenuItem, return its index in the currently visible set of items.

      To get the index of the item in the full set of items, including hidden items, use getItemNum() instead

      Parameters:
      item - Menu Item to find
      Returns:
      index of the item in the visible items, or -1 if not found.
      See Also:

    • hideContextMenu

      public void hideContextMenu()
      Hide the context menu - alias for hide()
      Overrides:
      hideContextMenu in class Canvas
      See Also:

    • addItemClickHandler

      public HandlerRegistration addItemClickHandler(ItemClickHandler handler)
      Add a itemClick handler.

      Executed when a menu item with no click handler is clicked by the user. This itemClick handler must be specified as a function. It is passed an item parameter that is a reference to the clicked menu item.

      Specified by:
      addItemClickHandler in interface HasItemClickHandlers
      Parameters:
      handler - the itemClick handler
      Returns:
      HandlerRegistration used to remove this handler

    • setCriteria

      public void setCriteria(Criteria criteria)
      This DataBoundComponent method is not supported - use initialCriteria to apply criteria to the fetches made by menus.
      Overrides:
      setCriteria in class ListGrid
      Parameters:
      criteria - new criteria to show

    • setCriteria

      public void setCriteria(AdvancedCriteria criteria)
      This DataBoundComponent method is not supported - use initialCriteria to apply criteria to the fetches made by menus.
      Parameters:
      criteria - new criteria to show

    • setItemHidden

      public boolean setItemHidden(MenuItem item)
      Hides or shows the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the hidden state.
      Parameters:
      item - MenuItem in question, or its index. Note that if an index is passed it will be interpreted as the index in the full specified set of items rather than the visible-index of the item.
      Returns:
      true if the hidden state was changed
      See Also:

    • setItemHidden

      public boolean setItemHidden(int item)
      Hides or shows the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the hidden state.
      Parameters:
      item - MenuItem in question, or its index. Note that if an index is passed it will be interpreted as the index in the full specified set of items rather than the visible-index of the item.
      Returns:
      true if the hidden state was changed
      See Also:

    • setItemHidden

      public boolean setItemHidden(MenuItem item, boolean newState)
      Hides or shows the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the hidden state.
      Parameters:
      item - MenuItem in question, or its index. Note that if an index is passed it will be interpreted as the index in the full specified set of items rather than the visible-index of the item.
      newState - true to hide the menu item, false to show it.
      Returns:
      true if the hidden state was changed
      See Also:

    • showContextMenu

      public Boolean showContextMenu()
      Show this menu as a context menu, that is, immediately adjacent to the current mouse position.
      Returns:
      false == stop processing this event
      See Also:

    • hideAllMenus

      public static void hideAllMenus()
      Hide all menus that are currently open. This method is useful to hide the current set of menus including submenus, and dismiss the menu's clickMask.

    • setDefaultProperties

      public static void setDefaultProperties(Menu menuProperties)
      Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

      Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

      Parameters:
      menuProperties - properties that should be used as new defaults when instances of this class are created
      See Also:

    • onInit_ListGrid

      protected void onInit_ListGrid()
      Overrides:
      onInit_ListGrid in class ListGrid

    • getSubmenu

      public Menu getSubmenu(MenuItem item)
      Creates and returns the submenu associated with the provided MenuItem.
      Parameters:
      menuItem - to target
      Returns:
      submenu for that menuItem
      See Also:

    • setDataProperties

      public void setDataProperties(Tree dataProperties) throws IllegalStateException
      For a Menu that uses a DataSource, these properties will be passed to the automatically-created ResultTree. This can be used for various customizations such as modifying the automatically-chosen parentIdField.
      Parameters:
      dataProperties - dataProperties Default value is null
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getItems

      public MenuItem[] getItems()
      Return the menu items.
      Returns:
      the menu items

    • setTitle

      public void setTitle(String title)
      When used in a MenuBar, the title of the menu button create will be the title of the Menu.
      Overrides:
      setTitle in class Canvas
      Parameters:
      title - the title

    • removeItem

      public void removeItem(MenuItem item)

    • addItem

      public void addItem(MenuItem item)

    • addItem

      public void addItem(MenuItem item, int index)

    • getItemNum

      public int getItemNum(MenuItem item)
      Given a MenuItem, return it's index in the items array.
      Parameters:
      item - the MenuItem
      Returns:
      index of the item, or -1 if not defined.

    • setItemProperties

      public void setItemProperties(int item, MenuItem properties)
      Set arbitrary properties for a particular menu item.
      Parameters:
      item - index of the MenuItem
      properties - properties to apply to the item

    • setItemChecked

      public Boolean setItemChecked(MenuItem item)
      Checks or unchecks the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the checked state.
      Parameters:
      item - MenuItem in question, or it's index
      Returns:
      true if the checked state was changed

    • setItemChecked

      public Boolean setItemChecked(int item)
      Checks or unchecks the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the checked state.
      Parameters:
      item - MenuItem in question, or it's index
      Returns:
      true if the checked state was changed

    • setItemChecked

      public Boolean setItemChecked(MenuItem item, boolean newState)
      Checks or unchecks the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the checked state.
      Parameters:
      item - MenuItem in question, or it's index
      newState - true to check the menu item, false to uncheck it. If not passed, true is assumed
      Returns:
      true if the checked state was changed

    • setItemChecked

      public Boolean setItemChecked(int item, boolean newState)
      Checks or unchecks the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the checked state.
      Parameters:
      item - MenuItem in question, or it's index
      newState - true to check the menu item, false to uncheck it. If not passed, true is assumed
      Returns:
      true if the checked state was changed

    • setItemEnabled

      public Boolean setItemEnabled(MenuItem item)
      Enables or disables the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the enabled state.
      Parameters:
      item - MenuItem in question, or it's index
      Returns:
      true if the enabled state was changed

    • setItemEnabled

      public Boolean setItemEnabled(int item)
      Enables or disables the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the enabled state.
      Parameters:
      item - MenuItem in question, or it's index
      Returns:
      true if the enabled state was changed

    • setItemEnabled

      public Boolean setItemEnabled(MenuItem item, boolean newState)
      Enables or disables the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the enabled state.
      Parameters:
      item - MenuItem in question, or it's index
      newState - true to enable the menu item, false to disable it. If not passed, true is assumed
      Returns:
      true if the enabled state was changed

    • setItemEnabled

      public Boolean setItemEnabled(int item, boolean newState)
      Enables or disables the menu item according to the value of newState, and redraws the menu if necessary. Returns true if there's a change in the enabled state.
      Parameters:
      item - MenuItem in question, or it's index
      newState - true to enable the menu item, false to disable it. If not passed, true is assumed
      Returns:
      true if the enabled state was changed

    • setItemIcon

      public Boolean setItemIcon(MenuItem item, String newIcon)
      Sets the icon and disabled icon (if specified) for a particular menu item and redraws the menu if necessary. Returns true if the icon changed.
      Parameters:
      item - MenuItem in question, or it's index
      newIcon - new icon URL
      Returns:
      true == something changed, redraw is called for

    • setItemIcon

      public Boolean setItemIcon(int item, String newIcon)
      Sets the icon and disabled icon (if specified) for a particular menu item and redraws the menu if necessary. Returns true if the icon changed.
      Parameters:
      item - MenuItem in question, or it's index
      newIcon - new icon URL
      Returns:
      true == something changed, redraw is called for

    • setItemIcon

      public Boolean setItemIcon(MenuItem item, String newIcon, String newDisabledIcon)
      Sets the icon and disabled icon (if specified) for a particular menu item and redraws the menu if necessary. Returns true if the icon changed.
      Parameters:
      item - MenuItem in question, or it's index
      newIcon - new icon URL
      newDisabledIcon - new icon URL for disabled image
      Returns:
      true == something changed, redraw is called for

    • setItemIcon

      public Boolean setItemIcon(int item, String newIcon, String newDisabledIcon)
      Sets the icon and disabled icon (if specified) for a particular menu item and redraws the menu if necessary. Returns true if the icon changed.
      Parameters:
      item - MenuItem in question, or it's index
      newIcon - new icon URL
      newDisabledIcon - new icon URL for disabled image
      Returns:
      true == something changed, redraw is called for

    • setItemTitle

      public Boolean setItemTitle(MenuItem item, String newTitle)
      Sets the title of a particular menu item to the string specified by newTitle and redraws the menu if necessary.
      Parameters:
      item - MenuItem in question, or it's index
      newTitle - new title
      Returns:
      true if the title was changed, and false otherwise

    • setItemTitle

      public Boolean setItemTitle(int item, String newTitle)
      Sets the title of a particular menu item to the string specified by newTitle and redraws the menu if necessary.
      Parameters:
      item - MenuItem in question, or it's index
      newTitle - new title
      Returns:
      true if the title was changed, and false otherwise

    • getOrCreateRef

      public static Menu getOrCreateRef(JavaScriptObject jsObj, MenuItem parentItem)

    • relinkJavaScriptObject

      public void relinkJavaScriptObject(JavaScriptObject jsObj)

    • getOrCreateJsObj

      public JavaScriptObject getOrCreateJsObj()
      Specified by:
      getOrCreateJsObj in interface DataBoundComponent
      Overrides:
      getOrCreateJsObj in class BaseWidget

    • setConfig

      public void setConfig(JavaScriptObject config)
      Overrides:
      setConfig in class BaseWidget

    • setIconFieldDefaults

      public static void setIconFieldDefaults(ListGridField iconFieldDefaults)
      Default properties for the automatically generated icon column. Default object includes properties to set width and to show icon for this column.

      To modify the behavior or appearance of this column, developers may set iconFieldProperties at the instance level, or iconFieldDefaults to affect all instances of the class. See showIcons for an overview of the icon column.

      Parameters:
      iconFieldDefaults -

    • getIconFieldDefaults

      public static ListGridField getIconFieldDefaults()
      Default properties for the automatically generated icon column. Default object includes properties to set width and to show icon for this column.

      To modify the behavior or appearance of this column, developers may set iconFieldProperties at the instance level, or iconFieldDefaults to affect all instances of the class. See showIcons for an overview of the icon column.

      Parameters:
      iconFieldDefaults - Default value is object

    • setKeyFieldDefaults

      public static void setKeyFieldDefaults(ListGridField keyFieldDefaults)
      Default properties for the automatically generated key column. Default object includes properties to set width and to show key for this column.

      To modify the behavior or appearance of this column, developers may set keyFieldProperties at the instance level, or keyFieldDefaults to affect all instances of the class. See showKeys for an overview of the key column.

      Parameters:
      keyFieldDefaults - Default value is object

    • getKeyFieldDefaults

      public static ListGridField getKeyFieldDefaults()
      Default properties for the automatically generated key column. Default object includes properties to set width and to show key for this column.

      To modify the behavior or appearance of this column, developers may set keyFieldProperties at the instance level, or keyFieldDefaults to affect all instances of the class. See showKeys for an overview of the key column.

      Parameters:
      keyFieldDefaults - Default value is object

    • setSubmenuFieldDefaults

      public static void setSubmenuFieldDefaults(ListGridField submenuFieldDefaults)
      Default properties for the automatically generated submenu column. Default object includes properties to set width, align and to show submenu icon for this column.

      To modify the behavior or appearance of this column, developers may set submenuFieldProperties at the instance level, or submenuFieldDefaults to affect all instances of the class. See showSubmenus for an overview of the submenu column.

      Parameters:
      submenuFieldDefaults - Default value is object

    • getSubmenuFieldDefaults

      public static ListGridField getSubmenuFieldDefaults()
      Default properties for the automatically generated submenu column. Default object includes properties to set width, align and to show submenu icon for this column.

      To modify the behavior or appearance of this column, developers may set submenuFieldProperties at the instance level, or submenuFieldDefaults to affect all instances of the class. See showSubmenus for an overview of the submenu column.

      Parameters:
      submenuFieldDefaults - Default value is object

    • setTitleFieldDefaults

      public static void setTitleFieldDefaults(ListGridField titleFieldDefaults)
      Default properties for the automatically generated title column. Default object includes properties to set width and to show title for this column.

      To modify the behavior or appearance of this column, developers may set titleFieldProperties at the instance level, or titleFieldDefaults to affect all instances of the class

      Parameters:
      titleFieldDefaults - Default value is object

    • getTitleFieldDefaults

      public static ListGridField getTitleFieldDefaults()
      Default properties for the automatically generated title column. Default object includes properties to set width and to show title for this column.

      To modify the behavior or appearance of this column, developers may set titleFieldProperties at the instance level, or titleFieldDefaults to affect all instances of the class

      Parameters:
      titleFieldDefaults - Default value is object

    • setLogicalStructure

      public LogicalStructureObject setLogicalStructure(MenuLogicalStructure s)
      Setter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.

    • getLogicalStructure

      public LogicalStructureObject getLogicalStructure()
      Getter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.
      Specified by:
      getLogicalStructure in interface LogicalStructure
      Overrides:
      getLogicalStructure in class ListGrid