CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DynamicGrouping (ui/toolbar)

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

class private
See source

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

  • readonly

    cachedPadding : Number

    See source

    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.

  • readonly

    destroy : function

    See source

    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.

  • readonly

    groupedItems : ViewCollection

    See source

    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.

  • readonly

    groupedItemsDropdown : DropdownView

    See source

    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.

  • readonly

    render : function

    See source

    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.

  • readonly

    resizeObserver : ResizeObserver

    See source

    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.

  • readonly

    shouldUpdateGroupingOnNextResize : Boolean

    See source

    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.

  • readonly

    ungroupedItems : ViewCollection

    See source

    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.

  • readonly

    view : ToolbarView

    See source

    A toolbar view this behavior belongs to.

  • readonly

    viewChildren : ViewCollection

    See source

    A collection of toolbar children.

  • readonly

    viewElement : HTMLElement

    See source

    Toolbar element.

  • readonly

    viewFocusTracker : FocusTracker

    See source

    Toolbar focus tracker.

  • readonly

    viewFocusables : ViewCollection

    See source

    A collection of focusable toolbar elements.

  • readonly

    viewItemsView : ItemsView

    See source

    A view containing toolbar items.

  • readonly

    viewLocale : Locale

    See source

    Toolbar locale.

  • private

    _areItemsOverflowing : Boolean

    See source

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

Methods

  • constructor( view )

    See source

    Creates an instance of the DynamicGrouping toolbar behavior.

    Parameters

    view : ToolbarView

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

  • protected

    _updateGrouping()

    See source

    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.

  • private

    _createGroupedItemsDropdown() → DropdownView

    See source

    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

  • private

    _enableGroupingOnMaxWidthChange()

    See source

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

  • private

    _enableGroupingOnResize()

    See source

    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.

  • private

    _groupLastItem()

    See source

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

    The opposite of _ungroupFirstItem.

  • private

    _ungroupFirstItem()

    See source

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

    The opposite of _groupLastItem.

  • private

    _updateFocusCycleableItems()

    See source

    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.