How to Show Tooltips in Scriptable macOS Apps Using JavaScript or AppleScript

Exploring Tooltip Display in Scriptable macOS Applications

Developers working on macOS often encounter scenarios where displaying quick contextual information via tooltips enhances user experience. However, managing such behavior dynamically within frontmost apps can be challenging. Leveraging scripting tools like AppleScript or JavaScript through osascript opens up possibilities for more control.

Although Objective-C offers a way to create custom tooltip windows, it may not always be the optimal solution. Tooltips generated this way are limited because they don’t interact well with other apps when triggered by shortcuts or in real-time. This raises the question of whether built-in properties, such as toolTip, can provide a more efficient solution.

The goal here is to explore if there’s a method to dynamically assign tooltips via AppleScript or JavaScript. Ideally, this would involve using a script to tell the currently active app to display a tooltip without requiring elaborate custom UI code or disrupting the user’s workflow.

This article will investigate how the toolTip property functions within macOS and if it can be invoked dynamically. We’ll assess existing approaches and discuss alternative ways to control tooltip behavior seamlessly in scriptable apps.

Implementing Tooltip Functionality in macOS through Scripts

The first solution leverages AppleScript to interact with the frontmost application. It checks which application is active and attempts to apply the toolTip property if the app supports it. This approach demonstrates how simple scripting logic can dynamically interact with supported apps, such as TextEdit. If the app doesn’t allow setting a tooltip, the script provides user feedback using a dialog box. This method offers simplicity but is limited by the fact that not all applications expose their tooltip properties to AppleScript.

The second example uses JavaScript for Automation (JXA), which is Apple's native automation scripting environment. It allows more complex logic compared to AppleScript and offers better integration with other JavaScript tools. By querying the currently active process through system events, the script identifies the frontmost app and attempts to assign a tooltip to it. This solution highlights the flexibility of JXA in interacting with macOS apps, but it still depends on the app exposing the toolTip property. If not, the script gracefully falls back to displaying a message dialog.

The third solution dives into Objective-C, embedded in AppleScript, to create a custom tooltip-like window. This approach bypasses the limitations of the toolTip property by generating a small, floating window that behaves like a tooltip. The script initializes a new NSWindow and adjusts its properties to ensure it stays on top of other windows without stealing focus. This method is useful when developers need a tooltip that is independent of the app's native support. However, it requires more advanced knowledge of Objective-C and macOS frameworks, making it slightly more complex to implement and maintain.

Lastly, the provided unit tests are designed to validate the behavior of the JavaScript automation solution. By mocking the Application object and its tooltip assignment logic, these tests ensure that the tooltip is correctly set when the target app supports it. Unit tests play a crucial role in ensuring that the script behaves as expected in different scenarios, catching errors early in development. These tests also demonstrate best practices for code validation, particularly in automation environments, where scripts interact with multiple processes and need to perform consistently.

-- Check if the frontmost app supports tooltips
tell application "System Events"
   set frontApp to (name of first application process whose frontmost is true)
end tell

-- Example: Try to set a tooltip on TextEdit if it's the front app
if frontApp = "TextEdit" then
   tell application "TextEdit"
      set toolTip of front window to "This is a dynamic tooltip!"
   end tell
else
   display dialog "Tooltip not supported for the current app."
end if

// Use osascript to run JavaScript code targeting the front app
const app = Application.currentApplication();
app.includeStandardAdditions = true;

// Check if TextEdit is frontmost, set tooltip if true
const frontAppName = app.systemEvents.processes.whose({ frontmost: true })[0].name();
if (frontAppName === "TextEdit") {
   const textEdit = Application("TextEdit");
   textEdit.windows[0].toolTip = "This is a tooltip!";
} else {
   app.displayDialog("Current app does not support tooltips.");
}

use framework "Foundation"
use framework "AppKit"
property tooltip : missing value

-- Create a custom tooltip-like window
set tooltip to current application's NSWindow's alloc()'s
    initWithContentRect:(current application's NSMakeRect(100, 100, 200, 50))
    styleMask:1 backing:(current application's NSBackingStoreBuffered) defer:true
tooltip's setTitle:"Custom Tooltip"
tooltip's setLevel:(current application's NSFloatingWindowLevel)
tooltip's makeKeyAndOrderFront:true

-- Ensure it stays above other windows without stealing focus
tooltip's setHidesOnDeactivate:false

const assert = require('assert');

// Mock of Application object
const mockApp = {
   name: "TextEdit",
   toolTip: "",
   setToolTip: function (text) { this.toolTip = text; }
};

assert.strictEqual(mockApp.toolTip, "");
mockApp.setToolTip("Unit test tooltip");
assert.strictEqual(mockApp.toolTip, "Unit test tooltip");
console.log("Test passed!");

Enhancing Tooltip Display in macOS with Advanced Techniques

One essential aspect of working with tooltips in macOS is understanding the limitations of inter-application scripting. Not all applications expose their UI elements through scripting interfaces, which means developers often need to mix solutions, such as combining AppleScript with native frameworks like AppKit. This ensures consistent results even in complex scenarios, such as when applications do not natively support tooltips or when dynamic interaction is needed.

A critical consideration is how macOS manages window layers and focus. Custom tooltip windows created with Objective-C must remain above all other windows without interfering with user input. This behavior can be achieved using floating window levels, but it requires managing the tooltip's lifecycle effectively. For example, developers should ensure that the tooltip disappears after a set time or when the user interacts with the original app. Failure to manage this can lead to performance issues or unintended behavior.

Another alternative approach worth mentioning is the use of Keyboard Maestro or other macOS automation tools. These tools can trigger AppleScript or JavaScript solutions via custom keyboard shortcuts, offering seamless integration with the user’s workflow. However, automating tooltips across different apps requires error handling, as some apps may not respond to scripting requests. Thus, combining multiple methods—like conditional checks and custom Objective-C windows—ensures robust performance in diverse environments.