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

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

    See source

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

    See source

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

    See source

    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.

    See source

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

    See source

    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.

    See source

    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.

    See source

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

    See source

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

  • viewChildren : ViewCollection

    readonly

    A collection of toolbar children.

    See source

  • viewElement : HTMLElement

    readonly

    Toolbar element.

    See source

  • viewFocusTracker : FocusTracker

    readonly

    Toolbar focus tracker.

    See source

  • viewFocusables : ViewCollection

    readonly

    A collection of focusable toolbar elements.

    See source

  • viewItemsView : ItemsView

    readonly

    A view containing toolbar items.

    See source

  • viewLocale : Locale

    readonly

    Toolbar locale.

    See source

  • _areItemsOverflowing : Boolean

    private

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

    See source

Methods

  • constructor( view )

    Creates an instance of the DynamicGrouping toolbar behavior.

    See source

    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.

    See source

    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.

    See source

    Returns

    DropdownView

  • _enableGroupingOnMaxWidthChange()

    private

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

    See source

  • _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).

    See source

    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.

    See source

    The opposite of _ungroupFirstItem.

  • _ungroupFirstItem()

    private

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

    See source

    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.

    See source

    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.