How-To Guide ⏱ ~20 minutes

Adding a Toolbar to Your App

Toolbars give your app a native, professional feel — the same row of icon buttons you see in Finder, Mail, and most other desktop apps. This guide walks you through adding one to an existing HyperXTalk stack, step by step.

What you'll end up with

A native toolbar attached to your stack window
Toolbar buttons with SF Symbols icons and labels
Click handlers wired up in your stack script
The ability to show and hide the toolbar on demand

Step 1 — Create the Toolbar

Open the stack you want to add a toolbar to and go to the stack script. The first thing you need to do is create the toolbar itself. The best place to do this is in an openStack handler so it's ready as soon as the stack opens:

stack script
on openStack
   create toolbar "mainBar" in this stack
end openStack

The string "mainBar" is the identifier you'll use to refer to this toolbar in every subsequent command. Choose something descriptive — if your app has different toolbars for different modes, names like "editBar" or "formatBar" make things clearer.

💡 The toolbar won't be visible yet. We'll set it visible at the end, after all its items are configured. This avoids the user seeing buttons appear one by one.

Step 2 — Add Toolbar Items

Each button in the toolbar is called an item. You define items by setting their label and icon, then tell the toolbar which items to show and in what order.

Set labels and icons

stack script
-- Labels (shown beneath each button)
set the itemLabel["fileNew"]  of toolbar "mainBar" to "New"
set the itemLabel["fileOpen"] of toolbar "mainBar" to "Open"
set the itemLabel["fileSave"] of toolbar "mainBar" to "Save"

-- Icons (SF Symbols names)
set the itemIcon["fileNew"]   of toolbar "mainBar" to "doc.badge.plus"
set the itemIcon["fileOpen"]  of toolbar "mainBar" to "folder"
set the itemIcon["fileSave"]  of toolbar "mainBar" to "square.and.arrow.down"

Set the item order

Setting labels and icons registers the items but doesn't add them to the visible toolbar yet. You control which items appear — and in what order — by setting itemNames to a return-separated list:

set the itemNames of toolbar "mainBar" to \
   "fileNew" & return & "fileOpen" & return & "fileSave"

You can reorder items at any time by setting itemNames again. Items not in the list are hidden but not deleted — useful if you want to swap toolbars between modes.

Step 3 — Choose Your Icons

Icons are specified using SF Symbols names — Apple's built-in icon library with over 6,000 symbols. Download the free SF Symbols app to search and preview them. You can also use an image imported into your stack by passing its filename instead of a symbol name:

-- Use a stack image instead of an SF Symbol
set the itemIcon["myButton"] of toolbar "mainBar" to "MyLogo.png"

🟢 You can mix SF Symbols and stack images in the same toolbar — use whichever works best for each button. Stack images should ideally be square and at least 32×32 pixels.

Step 4 — Show the Toolbar

Back in your openStack handler, after all the item setup, make the toolbar visible:

set the toolbarVisible of toolbar "mainBar" to true

You can toggle visibility at any time — for example from a View menu item:

set the toolbarVisible of toolbar "mainBar" to \
   not the toolbarVisible of toolbar "mainBar"

Step 5 — Handle Button Clicks

When the user clicks a toolbar button, HyperXTalk sends a toolbarItemClicked message with the item's identifier as a parameter. Add this handler to your stack script or card script — not an object script:

stack script
on toolbarItemClicked pItemName
   switch pItemName
      case "fileNew"
         doMenu "New Stack"
         break
      case "fileOpen"
         doMenu "Open Stack..."
         break
      case "fileSave"
         save this stack
         break
   end switch
end toolbarItemClicked

The switch statement is the cleanest way to handle multiple buttons — it checks pItemName against each case and runs the matching block. Add as many cases as you have toolbar items.

Putting It All Together

Here's the complete stack script with everything in place:

stack script
on openStack
   -- Create the toolbar
   create toolbar "mainBar" in this stack

   -- Set item labels
   set the itemLabel["fileNew"]  of toolbar "mainBar" to "New"
   set the itemLabel["fileOpen"] of toolbar "mainBar" to "Open"
   set the itemLabel["fileSave"] of toolbar "mainBar" to "Save"

   -- Set item icons
   set the itemIcon["fileNew"]   of toolbar "mainBar" to "doc.badge.plus"
   set the itemIcon["fileOpen"]  of toolbar "mainBar" to "folder"
   set the itemIcon["fileSave"]  of toolbar "mainBar" to "square.and.arrow.down"

   -- Set item order
   set the itemNames of toolbar "mainBar" to \
      "fileNew" & return & "fileOpen" & return & "fileSave"

   -- Show the toolbar
   set the toolbarVisible of toolbar "mainBar" to true
end openStack

on toolbarItemClicked pItemName
   switch pItemName
      case "fileNew"
         doMenu "New Stack"
         break
      case "fileOpen"
         doMenu "Open Stack..."
         break
      case "fileSave"
         save this stack
         break
   end switch
end toolbarItemClicked

🟢 Want to go deeper? The Native Toolbars tutorial covers additional topics including using stack images as icons and toggling toolbar visibility.