Class

DynamicGrouping (ui/toolbar)

@ckeditor/ckeditor5-ui/src/toolbar/toolbarview

class private

A toolbar behavior that makes the items respond to changes in the geometry.

In a nutshell, it groups items that do not fit visually into a single row of the toolbar (due to limited space). Items that do not fit are aggregated in a dropdown displayed at the end of the toolbar.

┌──────────────────────────────────────── ToolbarView ──────────────────────────────────────────┐
| ┌─────────────────────────────────────── #children ─────────────────────────────────────────┐ |
| |   ┌─────── #itemsView ────────┐ ┌──────────────────────┐ ┌── #groupedItemsDropdown ───┐   | |
| |   |       #ungroupedItems     | | ToolbarSeparatorView | |        #groupedItems       |   | |
| |   └──────────────────────────-┘ └──────────────────────┘ └────────────────────────────┘   | |
| |                                  \---------- only when toolbar items overflow --------/    | |
| └───────────────────────────────────────────────────────────────────────────────────────────┘ |
└───────────────────────────────────────────────────────────────────────────────────────────────┘

Filtering

Properties

  • cachedPadding : Number

    readonly

    A cached value of the horizontal padding style used by _updateGrouping to manage the items that do not fit into a single toolbar line. This value can be reused between updates because it is unlikely that the padding will change and re–using Window.getComputedStyle() is expensive.

  • destroy : function

    readonly

    A method called after the toolbar has been destroyed. It allows cleaning up after the toolbar behavior, for instance, this is the right place to detach event listeners, free up references, etc.

  • groupedItems : ViewCollection

    readonly

    A subset of toolbar items. A collection of the toolbar items that do not fit into a single row of the toolbar. Grouped items are displayed in a dedicated dropdown.

    When none of the items were grouped, this collection is empty.

  • groupedItemsDropdown : DropdownView

    readonly

    The dropdown that aggregates grouped items that do not fit into a single row of the toolbar. It is displayed on demand as the last of toolbar children and offers another (nested) toolbar which displays items that would normally overflow.

  • render : function

    readonly

    A method called after the toolbar has been rendered. It can be used to, for example, customize the behavior of the toolbar when its element is available.

    Parameters

    view : ToolbarView

    An instance of the toolbar being rendered.

  • resizeObserver : ResizeObserver

    readonly

    An instance of the resize observer that helps dynamically determine the geometry of the toolbar and manage items that do not fit into a single row.

    Note: Created in _enableGroupingOnResize.

  • shouldUpdateGroupingOnNextResize : Boolean

    readonly

    A flag indicating that an items grouping update has been queued (e.g. due to the toolbar being visible) and should be executed immediately the next time the toolbar shows up.

  • ungroupedItems : ViewCollection

    readonly

    A subset of toolbar items. Aggregates items that fit into a single row of the toolbar and were not grouped into a dropdown. Items of this collection are displayed in the itemsView.

    When none of the items were grouped, it matches the items collection in size and order.

  • view : ToolbarView

    readonly

    A toolbar view this behavior belongs to.

  • viewChildren : ViewCollection

    readonly

    A collection of toolbar children.

  • viewElement : HTMLElement

    readonly

    Toolbar element.

  • viewFocusTracker : FocusTracker

    readonly

    Toolbar focus tracker.

  • viewFocusables : ViewCollection

    readonly

    A collection of focusable toolbar elements.

  • viewItemsView : ItemsView

    readonly

    A view containing toolbar items.

  • viewLocale : Locale

    readonly

    Toolbar locale.

  • _areItemsOverflowing : Boolean

    private

    Returns true when element children visually overflow, for instance if the toolbar is narrower than its members. Returns false otherwise.

Methods

  • constructor( view )

    Creates an instance of the DynamicGrouping toolbar behavior.

    Parameters

    view : ToolbarView

    An instance of the toolbar that this behavior is added to.

  • _updateGrouping()

    protected

    When called, it will check if any of the ungroupedItems do not fit into a single row of the toolbar, and it will move them to the groupedItems when it happens.

    At the same time, it will also check if there is enough space in the toolbar for the first of the groupedItems to be returned back to ungroupedItems and still fit into a single row without the toolbar wrapping.

  • _createGroupedItemsDropdown() → DropdownView

    private

    Creates the groupedItemsDropdown that hosts the members of the groupedItems collection when there is not enough space in the toolbar to display all items in a single row.

    Returns

    DropdownView
  • _enableGroupingOnMaxWidthChange()

    private

    Enables the grouping functionality, just like _enableGroupingOnResize but the difference is that it listens to the changes of maxWidth instead.

  • _enableGroupingOnResize()

    private

    Enables the functionality that prevents ungroupedItems from overflowing (wrapping to the next row) upon resize when there is little space available. Instead, the toolbar items are moved to the groupedItems collection and displayed in a dropdown at the end of the row (which has its own nested toolbar).

    When called, the toolbar will automatically analyze the location of its ungroupedItems and "group" them in the dropdown if necessary. It will also observe the browser window for size changes in the future and respond to them by grouping more items or reverting already grouped back, depending on the visual space available.

  • _groupLastItem()

    private

    When called, it will remove the last item from ungroupedItems and move it back to the groupedItems collection.

    The opposite of _ungroupFirstItem.

  • _ungroupFirstItem()

    private

    Moves the very first item belonging to groupedItems back to the ungroupedItems collection.

    The opposite of _groupLastItem.

  • _updateFocusCycleableItems()

    private

    Updates the focus–cycleable items collection so it represents the up–to–date state of the UI from the perspective of the user.

    For instance, the groupedItemsDropdown can show up and hide but when it is visible, it must be subject to focus cycling in the toolbar.

    See the collection documentation to learn more about the purpose of this method.