Hotspot mappings (`toolbar-map.json`)

The toolbar is described by a small JSON file inside the active theme. Edit it by hand, or use Appearance → Customize toolbar…, a graphical editor where you draw and resize hotspots on the picture, assign actions, tooltips and menus, preview the result and save into the theme.

What a button can do

A button names an action. Only these are possible; anything else is rejected with a message saying which button and why.

1. An approved application action (list below).
2. A native IRC command, such as cmd:/join #help. It runs through the same validated command pipeline as typed text, so aliases and credential protections apply. Commands that look like authentication (identify, login, auth, register, password, oper and similar) are refused so no secret ends up in a theme file.
3. A script command, script:hello, which runs /hello only if an approved, running script provides that command. Otherwise the button is greyed with the reason.
4. menu, which opens the button’s dropdown.

A mapping cannot run a program, a script’s code or JavaScript, and cannot touch the file system.

Approved actions

Action	Does	Available when
server.add server.connect server.disconnect server.reconnect server.edit server.save	Server management for the active network	Live mode; connect and disconnect depend on state
channels.browse channels.join channels.favorites channels.recent channels.favorite.toggle	Channel list, join prompt, favourites, recent channels	A network is selected
dm.list	Pick an open private conversation	Live mode
aliases.open settings.open	Dialogs	Live mode
help.open	Shortcuts and commands	Always
notifications.open	Recent mentions and messages	Always
appearance.open appearance.import appearance.reset appearance.theme.next toolbar.edit	Appearance and toolbar tools	Always
layout.tabs layout.single layout.grid2 layout.grid4	Conversation layout	Always
sidebar.toggle members.toggle	Panels	Always
transfers.open	File transfers are not implemented	Never; shown disabled

Unavailable actions are shown dimmed with the reason in the tooltip.

Format 1: ribbon mode

{
  "format": 1,
  "mode": "ribbon",
  "buttons": [
    { "id": "servers", "icon": "servers", "label": "Servers", "subtitle": "Manage",
      "tooltip": "Servers — Add, connect and edit your IRC servers",
      "action": "menu",
      "menu":    [ { "label": "Add server…", "action": "server.add" } ],
      "context": [ { "label": "Add server…", "action": "server.add" } ] }
  ]
}

Field	Meaning
format	Must be 1
mode	"ribbon" (default) or "image"
buttons	1 to 24 buttons
id	Unique; lowercase letters, digits and dashes (up to 24)
label	1 to 24 characters
subtitle, icon	Optional, up to 24 characters. Icons: servers channels messages aliases commands transfers bell palette help grid settings plus
tooltip	Up to 160 characters
action	A plain click does this. If the button also has a menu, the small caret (or the ↓ key) opens it. "menu" makes the click itself open the dropdown
menu	Up to 16 items { "label", "action" }
context	Items for right-click (and the Menu key or Shift+F10). Falls back to menu

Items in menu and context cannot themselves be "menu".

Image mode

{
  "format": 1,
  "mode": "image",
  "reference": { "width": 960, "height": 64 },
  "artwork": "Graphics/toolbar.png",
  "hover":   "Graphics/toolbar-hover.png",
  "pressed": "Graphics/toolbar-pressed.png",
  "buttons": [
    { "id": "aliases", "label": "Aliases", "action": "aliases.open",
      "tooltip": "Aliases — Manage shortcuts and custom IRC commands",
      "rect": { "x": 480, "y": 8, "w": 144, "h": 48 } }
  ]
}

• reference is the pixel size of the artwork the hotspots were drawn on. Hotspots are stored in those pixels and drawn as percentages of the displayed picture, so they stay on their buttons when the window scales.
• Each button needs a rect (x, y, w, h) inside the reference size, at least 4×4.
• Hotspots are real buttons: they support keyboard focus (Tab and the arrow keys), Enter and Space, tooltips on hover and focus, right-click menus, and use label as their accessible name.