This page documents the four standalone GUI widget classes in maxGraph: MaxWindow, MaxLog, MaxPopupMenu, and MaxToolbar. These components create floating windows, debug consoles, context menus, and toolbars as HTML DOM elements directly within the browser document. They are independent of the graph rendering pipeline and can be used with or alongside a Graph instance.
For the PopupMenuHandler plugin — which wraps MaxPopupMenu inside the graph's plugin system and triggers it on right-click — see 4.1 For the MaxLog logging API and usage patterns, see 7.3 For the Editor class wrapper that uses MaxToolbar in an application context, see 2.5
All three classes extend EventSource, giving them a consistent addListener / fireEvent API. They manage their own DOM nodes and do not depend on any graph state.
Component summary:
| Class | File | Purpose |
|---|---|---|
MaxWindow | packages/core/src/gui/MaxWindow.ts | Draggable, resizable floating window |
MaxLog | packages/core/src/gui/MaxLog.ts | Singleton debug console with floating window |
MaxPopupMenu | packages/core/src/gui/MaxPopupMenu.ts | Context/popup menu with submenu support |
MaxToolbar | packages/core/src/gui/MaxToolbar.ts | Icon/button/combo toolbar |
Class hierarchy:
Sources: packages/core/src/gui/MaxWindow.ts178 packages/core/src/gui/MaxLog.ts47 packages/core/src/gui/MaxPopupMenu.ts55 packages/core/src/gui/MaxToolbar.ts48
MaxWindow is constructed with a title string, a content HTMLElement, position coordinates, optional dimensions, and behavioral flags.
new MaxWindow(title, content, x, y, width?, height?, minimizable?, movable?, replaceNode?, style?)
When content is not null, the constructor calls init() then sequentially installs the maximize, minimize, and close handlers. If movable is true, installMoveHandler() is called. The constructed div is appended to document.body unless replaceNode is supplied.
packages/core/src/gui/MaxWindow.ts178-213
DOM tree built by init():
Sources: packages/core/src/gui/MaxWindow.ts229-309
The default CSS class name is mxWindow. This is applied to both div and table. The title cell class becomes mxWindowTitle, and the content pane class becomes mxWindowPane. A custom style string can override these names.
Controls are appended as <img> elements inside the buttons div. Their icon URLs are derived from Client.imageBasePath:
| Property | Default URL fragment | Controlled by |
|---|---|---|
closeImage | /close.gif | setClosable(bool) |
minimizeImage | /minimize.gif | setMinimizable(bool) |
normalizeImage | /normalize.gif | shown when minimized/maximized |
maximizeImage | /maximize.gif | setMaximizable(bool) |
resizeImage | /resize.gif | setResizable(bool) |
packages/core/src/gui/MaxWindow.ts312-334
installCloseHandler() — fires CLOSE event; calls destroy() if destroyOnClose is true, otherwise calls setVisible(false).installMinimizeHandler() — toggles content visibility and fires MINIMIZE or NORMALIZE.installMaximizeHandler() — expands to full document size, fires MAXIMIZE or NORMALIZE. Also responds to dblclick on the title bar.installMoveHandler() — sets cursor: move on the title, registers drag gesture on document.packages/core/src/gui/MaxWindow.ts571-801
A module-level variable activeWindow tracks the single currently active MaxWindow. Clicking the title or table fires activate(), which increments the z-index of this window and decrements that of the previously active window. An ACTIVATE event is fired with a previousWindow property.
packages/core/src/gui/MaxWindow.ts29 packages/core/src/gui/MaxWindow.ts402-422
| Method | Behavior |
|---|---|
setVisible(visible) | Calls show() or hide() if state differs |
show() | Sets display: '', calls activate(), fires SHOW |
hide() | Sets display: none, fires HIDE |
destroy() | Fires DESTROY, releases events, removes div from DOM |
fit() | Calls styleUtils.fit() to constrain window to viewport |
setSize(w, h) | Enforces minimumSize, updates div, table, contentWrapper |
setLocation(x, y) | Sets div.style.left/top |
getX() / getY() | Reads div.style.left/top as integers |
packages/core/src/gui/MaxWindow.ts880-956
| Event constant | Fired when |
|---|---|
InternalEvent.MOVE_START | User begins dragging the title |
InternalEvent.MOVE | During drag |
InternalEvent.MOVE_END | Drag released |
InternalEvent.RESIZE_START | Resize grip pressed |
InternalEvent.RESIZE | During resize drag |
InternalEvent.RESIZE_END | Resize released |
InternalEvent.MAXIMIZE | Window maximized |
InternalEvent.MINIMIZE | Window minimized |
InternalEvent.NORMALIZE | Window returned to normal |
InternalEvent.ACTIVATE | Window brought to front |
InternalEvent.SHOW | Window made visible |
InternalEvent.HIDE | Window hidden |
InternalEvent.CLOSE | Close button clicked |
InternalEvent.DESTROY | Before DOM removal |
Sources: packages/core/src/gui/MaxWindow.ts107-175
MaxLog is a singleton debug console that displays log messages in a floating MaxWindow. It provides an in-browser alternative to the browser's developer console, useful for debugging graph operations without leaving the page.
MaxLog is implemented as a class with only static methods and properties. All interaction is through the class itself:
The window is created lazily on first call to setVisible(true), show(), or any logging method.
packages/core/src/gui/MaxLog.ts47
The init() method constructs a MaxWindow containing a three-row table:
MaxWindow, displays "Console - mxGraph {VERSION}"<textarea> filling the available heightThe window is positioned at (window.width - 320, window.height - 210) with dimensions 300x160. It supports all standard MaxWindow operations: minimize, maximize, resize, move, and close.
packages/core/src/gui/MaxLog.ts57-189
DOM structure created by init():
Sources: packages/core/src/gui/MaxLog.ts62-98
Six buttons are added by default via addButton(label, funct):
| Button | Function |
|---|---|
| Info | Calls info() to write navigator object properties to console |
| DOM | Writes document.body inner HTML to console |
| Trace | Toggles MaxLog.TRACE flag, controlling whether trace(), enter(), leave() methods output |
| Copy | Copies textarea content to clipboard via navigator.clipboard.writeText() |
| Show | Opens textarea content in a new popup window using guiUtils.popup() |
| Clear | Clears the textarea value |
Custom buttons can be added by calling addButton(label, funct) after the window is initialized.
packages/core/src/gui/MaxLog.ts101-138
Messages written before init() is called are stored in the static buffer string property. When the textarea is created, the buffer is copied into textarea.value, then subsequent writes append directly to the textarea.
This allows logging to start before the window is visible:
packages/core/src/gui/MaxLog.ts77 packages/core/src/gui/MaxLog.ts218 packages/core/src/gui/MaxLog.ts333-345
| Method | Behavior |
|---|---|
show() | Calls setVisible(true) |
setVisible(visible) | Calls init() if needed, then delegates to window.setVisible(visible) |
isVisible() | Returns window.isVisible() or false if window not yet created |
The window's destroyOnClose property is set to false, meaning closing the window hides it but keeps the object alive. Calling show() again will re-display the same window with its accumulated log content.
packages/core/src/gui/MaxLog.ts164 packages/core/src/gui/MaxLog.ts240-266
Since MaxLog.window is a MaxWindow instance, applications can listen to window events:
See the MaxWindow section above for the full list of events.
packages/core/src/gui/MaxLog.ts152-160
For the complete logging API (debug(), warn(), trace(), enter(), leave(), etc.), see 7.3
Sources: packages/core/src/gui/MaxLog.ts47-364
The constructor accepts an optional factoryMethod function. Two DOM structures are built immediately:
table.mxPopupMenu containing tbody — the item listdiv.mxPopupMenu wrapping the table — the floating containerThe div has its context menu disabled via InternalEvent.disableContextMenu.
new MaxPopupMenu(factoryMethod?)
where factoryMethod has the signature:
packages/core/src/gui/MaxPopupMenu.ts55-81
addItem() is the primary method for building menu content. It returns a <tr> element typed as PopupMenuItem, which can itself be passed as the parent argument for nested submenus.
addItem(title, image?, funct?, parent?, iconCls?, enabled?, active?, noHover?)
| Parameter | Type | Purpose |
|---|---|---|
title | string | Label text |
image | string | null | Icon URL |
funct | (evt: MouseEvent) => void | Click handler |
parent | PopupMenuItem | null | Parent row for submenu nesting |
iconCls | string | null | CSS class for icon (used if no image) |
enabled | boolean | Disables styling if false |
active | boolean | Suppresses event listeners if false |
noHover | boolean | Disables hover class toggling |
When smartSeparators is true, a pending separator added via addSeparator() is only rendered if another item actually follows it.
packages/core/src/gui/MaxPopupMenu.ts184-310
Submenus are created lazily. When addItem is called with a parent row for the first time, createSubmenu(parent) runs, building a new div.mxPopupMenu and table.mxPopupMenu attached to that row. A submenu arrow image (submenuImage) is injected into the third column of the parent row.
showSubmenu(parent, row) positions the submenu div to the right of its parent row, with overflow protection that moves it to the left side if it would go off-screen. hideSubmenu(parent) recursively removes the active submenu chain.
packages/core/src/gui/MaxPopupMenu.ts330-498
Menu and submenu DOM structure:
Sources: packages/core/src/gui/MaxPopupMenu.ts331-384
popup(x, y, cell, evt) is the entry point for showing the menu at screen coordinates:
div at (x, y)tbodyitemCount to 0factoryMethod(this, cell, evt) — the factory populates itemsitemCount > 0, calls showMenu() and fires SHOWshowMenu() appends div to document.body and calls styleUtils.fit().
hideMenu() removes div from document.body, calls hideSubmenu(), and fires HIDE.
packages/core/src/gui/MaxPopupMenu.ts436-498
| Event | Fired by |
|---|---|
InternalEvent.SHOW | popup() after menu is shown |
InternalEvent.HIDE | hideMenu() after menu is removed |
The popup menu uses these CSS class names, which must be defined in a stylesheet. The library ships default styles in @maxgraph/core/css/common.css. Custom overrides follow this pattern (from packages/html/stories/css/menu-style.css):
| Selector | Applied to |
|---|---|
div.mxPopupMenu | Outer floating container |
table.mxPopupMenu | Inner table |
tr.mxPopupMenuItem | Each menu item row |
td.mxPopupMenuItem | Item label cell |
td.mxPopupMenuIcon | Item icon cell |
tr.mxPopupMenuItemHover | Hovered item row |
Sources: packages/html/stories/css/menu-style.css1-37
MaxToolbar wraps a host HTMLElement passed to the constructor. All toolbar items are appended as children of this container.
new MaxToolbar(container: HTMLElement)
packages/core/src/gui/MaxToolbar.ts48-52
addItem(title, icon, funct, pressedIcon?, style?, factoryMethod?)
Adds a clickable icon (via <img>) or button (via <button> if icon is null). Default class name is mxToolbarItem, or mxToolbarMode if a factoryMethod is supplied. When factoryMethod is provided, clicking the item opens a MaxPopupMenu positioned below the icon.
packages/core/src/gui/MaxToolbar.ts102-200
addCombo(style?)
Adds a <select> element inside a div.mxToolbarComboContainer. Returns the <select>.
addActionCombo(title, style?)
Same as addCombo but resets to the first option after each selection. Use with addOption to attach callbacks. addOption(combo, title, value) attaches a function directly to the option element as option.funct.
packages/core/src/gui/MaxToolbar.ts207-273
addSwitchMode(title, icon, funct, pressedIcon?, style?)
Adds a permanently-toggleable mode item. Only one switch mode can be visually selected at a time. This is appropriate for mutually exclusive tool modes (e.g., select vs. connect). The first inserted switch mode item becomes the default.
addMode(title, icon, funct, pressedIcon, style?, toggle?)
Adds a mode item that resets back to the default after a single use. Double-clicking sets noReset = true, preventing automatic reset. The first inserted mode item becomes the default.
packages/core/src/gui/MaxToolbar.ts280-392
Sources: packages/core/src/gui/MaxToolbar.ts280-437
| Method | Behavior |
|---|---|
selectMode(domNode, funct) | Deselects current mode, selects domNode, fires SELECT |
resetMode(forced?) | Reverts to defaultMode unless noReset blocks it |
addSeparator(icon) | Delegates to addItem(null, icon, null) |
addBreak() | Appends <br> to container |
addLine() | Appends <hr> to container |
destroy() | Releases event listeners, destroys internal menu, nulls refs |
| Event | Property | Fired by |
|---|---|---|
InternalEvent.SELECT | function — the selected function | selectMode(), addSwitchMode() click handler |
The GUI components integrate with graph workflows in two primary patterns:
Pattern 1: MaxPopupMenu via PopupMenuHandler plugin
The PopupMenuHandler class (a graph plugin) extends MaxPopupMenu and triggers popup() in response to right-click events on the graph container. It is included in the default plugin list returned by getDefaultPlugins(). Custom factory methods are assigned to popupMenuHandler.factoryMethod.
packages/html/stories/MenuStyle.stories.ts113-148
Pattern 2: Standalone MaxPopupMenu in event handlers
A MaxPopupMenu can be constructed with its own factory method and shown anywhere, independent of the graph plugin system. The ShowRegion story demonstrates this: a custom RubberBandHandler subclass creates its own MaxPopupMenu and calls popup() directly on mouseUp.
packages/html/stories/ShowRegion.stories.ts86-122
Component interaction overview:
Sources: packages/html/stories/ShowRegion.stories.ts81-122 packages/html/stories/MenuStyle.stories.ts113-148 packages/core/src/gui/MaxToolbar.ts157-189
All three components require CSS to be functional. The base styles are shipped in the @maxgraph/core/css/common.css bundle, which must be imported explicitly in any project using these components:
MaxWindow uses class names derived from the style constructor parameter (default mxWindow). MaxPopupMenu uses fixed class names prefixed with mxPopupMenu. MaxToolbar uses fixed class names prefixed with mxToolbar.
Custom visual overrides can be applied by re-declaring any of these selectors in application CSS after the base import. See packages/html/stories/css/menu-style.css for a practical example of popup menu restyling.
Sources: packages/html/stories/ShowRegion.stories.ts46-48 packages/html/stories/MenuStyle.stories.ts50-52 packages/core/src/gui/MaxWindow.ts234-235 packages/core/src/gui/MaxPopupMenu.ts67-77
Refresh this wiki