jaspr_ribbon_toolbar #

An MS Office–style ribbon toolbar component for Jaspr web apps, rendered to an HTML5 <canvas>. A direct port of the Xojo XjRibbon library.

What's in this package #

This pub.flutter-io.cn package contains the reusable ribbon component — the library your Jaspr app depends on. It does not include the visual designer or the example apps (those live in the GitHub repository).

Visual designer — build ribbons without code #

The visual designer is a standalone web app for designing ribbons visually: upload SVG/PNG icons, edit the structure, assign tags, and save a self-contained .ribbon bundle. It runs in any browser — no Dart toolchain needed if you download the prebuilt.

Get it:

• Prebuilt (no Dart needed): download jaspr_ribbon_designer-0.5.0.zip from GitHub Releases, unzip, and serve with any static server:

  python3 -m http.server -d web 8000
  

• From source: clone the repo and cd apps/jaspr_ribbon_designer && jaspr serve

Quick start #

dart pub add jaspr_ribbon_toolbar

import 'package:jaspr_ribbon_toolbar/jaspr_ribbon_toolbar.dart';

final ribbon = RibbonDefinition(tabs: [
  RibbonTab(caption: 'Home', groups: [
    RibbonGroup(caption: 'Clipboard', items: [
      RibbonItem.large(caption: 'Paste', tag: 'clipboard.paste', iconKey: 'paste'),
      RibbonItem.small(caption: 'Cut', tag: 'clipboard.cut', iconKey: 'cut'),
    ]),
  ]),
]);

Render the <canvas>, then drive it:

RibbonCanvasController(
  canvas: canvasElement,
  definition: ribbon,
  colors: RibbonColors.light,
  onEvent: (event) {
    switch (event) {
      case ItemPressedEvent(:final tag):              handleCommand(tag);
      case DropdownMenuActionEvent(:final menuItemTag): handleCommand(menuItemTag);
      case CollapseStateChangedEvent():               /* … */
      case TabChangedEvent():                         /* … */
    }
  },
).attach();

Load a .ribbon bundle (self-contained, icons embedded):

final ribbon = RibbonDefinition.fromJsonString(jsonString);

Features #

• All seven control kinds: large / small / dropdown / splitbutton / toggle / checkbox / separator.
• Tab-based navigation with hover states and contextual tabs.
• Collapse/expand via chevron or double-click.
• Dark mode — runtime-toggleable port of Xojo's ResolveColors palette.
• SVG/PNG icons by string key (IconRegistry).
• Canvas-rendered dropdown menus — anchored, viewport-aware.
• HiDPI backing-store scaling for crisp rendering on retina.
• Sealed event API — exhaustive switch over RibbonEvent.

Documentation #

• Tutorial (3 parts + 3 runnable apps)
• .ribbon schema reference
• Xojo → Dart porting guide
• Full source + API docs

License #

MIT — see LICENSE.