tanin47 / tip

Programmable tooltip that can be used with any Mac OS app

Universal Tip

Tip (or its full name, Universal Tip) is a programmable tooltip that can be used with any Mac OS app. You can select the text and hit the shortcuts to activate a tooltip with useful info.

"Useful info" is programmed by you using your favourite programming language.

For me, who is prone to Repetitive strain injury and Carpal tunnel syndrome, Tip reduces hand movement which helps reduce the risk of the injury.

I'd love for you to try it!

Questions? please don't hesitate to open a Github issue.

Examples

Convert the seconds from epoch to the human-readable time and copy it to clipboard

Tip is used within Chrome.

If you've installed Tip, try converting seconds from epoch to time by triggering Tip on the following string: 1577733633

Open Github code search on the selected text

Tip is used within Sublime.

Open a file on Github from an error stacktrace line

Tip is used within Terminal.

Open a JIRA ticket on the selected text

Tip is used within Terminal.

You can make your own info provider. The possibility is endless!

Installation

1. Install Tip from Mac App Store
   • You can also download it from the release page and move Tip.app to under /Applications
2. Download and copy scripts/provider.script to ~/Library/Application\ Scripts/tanin.tip/provider.script. Run chmod 755 ~/Library/Application\ Scripts/tanin.tip/provider.script.
   • Or you can simply run: curl -o ~/Library/Application\ Scripts/tanin.tip/provider.script --create-dirs https://raw.githubusercontent.com/tanin47/tip/master/scripts/provider.script && chmod 755 ~/Library/Application\ Scripts/tanin.tip/provider.script
3. Go to System Preferences > Keyboard > Shortcuts > Services > Scroll down to the "Text" section. You should see "Tip: open tips" under the "Text" section.
   • Please make sure to check it.
   • You can also set the shortcuts here.

The sample provider script is in Ruby, so you need Ruby to run it. Otherwise, you can make your own provider as well.

See how to develop the provider script here.

Usage

1. Select the text
2. Hit the configured short key. The default shortcut is Cmd + &.
3. The tooltip with relevant info will show
4. Use arrow keys to choose an item in the tooltip and hit 'Enter' to perform the appropriate action. Alternatively, you can click an item as well

Currently, Tip supports 3 actions: (1) Copy to clipboard if the item is text, (2) Open URL if the item is URL, and (3) Execute a command.

See how to develop the provider script here.

Customize the shortcut

Go to System Preferences > Keyboard > Shortcuts > Services and set the shortcut for "Tip: open tips".

If your shortcut doesn't include the Command key, you will need to activate it manually by:

1. Selecting a text
2. Clicking on the application menu > Services > "Tip: open tips"

Now you'll be able to use the new shortcut for Tip.

Choosing a good shortcut

I've found that Cmd + F3 is a good shortcut. I haven't encountered an application that uses this shortcut yet.

My setup, which enables me to use Tip seamlessly, is:

• An extra mouse button emits Cmd + F3
• 4-finger touch on the trackpad emits Cmd + F3

I use Noo.app to configure my mouse buttons and trackpad.

Privacy

There are 3 components that enables Tip to maintain a high degree of privacy: App Sandbox, NSService, and NSUserUnixTask

1. Tip runs in App Sandbox without requesting for an additional permission. With App Sandbox, Tip can only read/write files from a few predefined directories and, specifically, can only execute (not write) the files within ~/Library/Application\ Scripts/tanin.tip. This is the reason why the provider script is under ~/Library/Application\ Scripts/tanin.tip/.

2. Tip is based on NSServices. Tip doesn't (and cannot) see the content of other applications. When you explicit trigger Tip, Mac OS gives Tip the selected text.

3. Tip uses NSUserUnixTask, which is intended to execute user-supplied scripts, and will execute them outside of the application's sandbox, if any. This enables provider.script (a user-supplied script) many more use cases because it runs outside of the sandbox.

Great design by Apple. It is a huge win in terms of privacy.

Technical detail

Tip is an NSServices. When user selects text and hits the shortcut, the selected text is sent to Tip. Then, Tip invokes the command-line tool with the selected text as the first argument, i.e ~/Library/Application\ Scripts/tanin.tip/provider.script [selected-text] --bundle-id [the-app-that-you-activate-tip-on].

The command-line tool processes the input, decides which info to show, and prints the tip items as JSON that looks like below:

[
  {"type": "text", "value": "Some text"},
  {"type": "url", "label": "Go to JIRA", "value": "https://your-jira-url/JIRA-0001"},
]

Tip processes the JSON and renders the tooltip at the mouse location.

Tip on the internet

• Nerd-Spielzeug „Universal Tip“: Programmierbarer Tooltip für macOS
• PopClipのように、macOSのツールチップにRubyでプログラム可能なアクションを表示することが出来る「Universal Tip」がリリース。
• Show HN: A programmable tooltip on Mac OS posted by myself
• Universal tooltip on Mac OS X for programmers. Hackable. Work with every app also posted by myself

FAQ

Why is Tip written in Objective-C instead of Swift?

Because I don't know how to write Swift. I'd like to switch to Swift though.

What does Tip mean?

Tip is a Thai word that means magical and divine. The word is derived from the word, divya, which exists in both Pali and Sanskrit.

tip's Issues

Idea: keyboard shortcut in popup window

Hi,

Thank you for creating such a great app!
Would it be possible to use Ctrl-n/Ctrl-p or j/k etc. in the popup window to move the selected row?

Regards.

Activate Tip on what is currently stored in the clipboard

Because some apps don't follow the standard way of rendering text on Mac OS X.

At least, this would allow users to use Tip on these incompatible apps.

Render image on the tooltip

We can support rendering image on the tooltip. Tip can accept a base64 encoded image.

If the image is from URL, the provider script is responsible for fetching the image and encode it.

Activating Tip with no selected text

It seems we can support it.

It will be useful in a certain situation like maybe I want to just launch a certain app or certain website.

Adding label to "text" action

This is a feature request. Currently text action has the text as the visible "label".

The use case would be (for example) having several "text modification actions" and being able to choose among them. For instance, imagine having a convert_to_milliseconds(input) and a convert_to_seconds(input). Without a label you would only see the output, which would then be confusing (this is an artificial example).

type: execute?

tip looks awesome. I'm playing around with it and enjoy it. Thank you!

I was wondering if besides text and url, is it possible to execute any other external script? e.g. bash, run an external program etc? Did I miss anything? otherwise, I think it would really boost its versatility if it's possible.

Comment: Couldn't see the tooltip until I changed the default command (Cmd+&) to something else

Hi,

I'd gone through the install process and couldn't figure out why the tooltip wasn't appearing.

I had:

• Moved the Tip app into ~/Library/Application \Scripts
• Ensured that provider.script was present and had text in it
• Ensured that "Tip" was checked on in System Prefs -> Keyboard -> Shortcuts

I then changed the default command to something new, Cmd+Shift+3, and only then was the tooltip appearing.

I wanted to comment about it in case it's happened to anyone else---and also to ask if there is something finicky with the default command. If so, then perhaps the readme could be updated?

Thanks,
Tsardines

PS - The app is working very nicely, btw 👍

TipNoticeView when hidden messes up the autolayout when the TipTableView has only one item

Instead of hiding TipNoticeView, we might need to remove the view completely to disable its constraints. That seems heavy.

Maybe we need another way.

We could separate a popover as well. One for TipTableView and another for TipNoticeView.

Python version of provider.script

Hi,

Love the app!

Here is a Python 3 version of your simple provider.script example.

#!/usr/bin/env python3

import json
import sys


def main(input):
    #sys.stderr.write(f'Input: {input}\n')

    items = [
        {'type': 'text', 'value': f'Input {input}'},
        {'type': 'url',  'label': f'Google {input}', 'value': f'https://google.com/search?q={input}'}
    ]

    print(json.dumps(items))


if __name__ == "__main__":

    main(sys.argv[1])

cheers,
Tony

Tip too large for amount of options

In RC 1.2.1, with a label for a text action the "tip window size" is too large for the amount of options:

This also happens with non-text:

This is not the case in the release in the App store:

(note that I had edited the text action to always return foo in this situation)

type: execute with user argument

An example use case: I want to calculate 9% of a selected number.

Here's the flow:

1. Select a number
2. Activate Tip
3. Tip presents an executable item with a text box. I input 9% and press enter.
4. Tip shows 9% of the selected number

Maximum length of input?

First of all, I love this tool. So simple and customizable!

After using the tool for quite some time, I noticed there is a limit of how large the selected section is. After some further investigation I noticed that the provider.script can't handle any selection larger then ~30.000 characters. Is this limit set on purpose or is it some kind of bug?

Here is an example text:
github_tip_not_working_example.txt

Search for # copy till here and select everything till here and script is working. If you select everything, the script loads for ages.

Tip does not open in Chrome or VS Code

Hi, thanks for making this great tool! Unfortunately it does not work inside every app for me. I tried it with different shortcuts (e.g. FN + OPTION + F4) and that works in Slack and Safari but not in Chrome or VS Code. I am on macOS Monterey 12.0.1 (21A559) with an M1 MacBook and a German keyboard. Are there any log files I can check to debug the issue?

tip cannot be triggered in some app (preview, telegram, vscode)

Hi there,
I find that I cannot trigger tip in the pdf document opened by preview with shortcut trigger tooltip not show up.
But in Chrome and sublime everything work as expected below in Chrome

Support invoking services on the file type

One idea for functionality is to select 2 files and invoke diff.

Idea: Context-aware providers

By looking at the provider examples it looks like they get the selected text, but no other information. I think it would be very useful if providers can know which application the selection is from. For example if the applications bundle identifier was passed to the provider.

Idea: Force Touch, 3-finger touch to activate tip

Hi,

Loving tip! Would it be possible to activate the tooltip by the use of force touch? That would be very useful.

Thanks again!

• Simon

I love your program, thank you for made it

Hi Tanin,
I really like your program, thank you.
Is it possible to call Tip with arguments?
because I would like to call it by a shorcut then screencapture a part screen to OCR, then show as a Tooltip,
But I have to select a word when I want to call Tip.
If you can help me please
Thanks in advance

The popup show appear around highlighted text rather than mouse position

This is especially important if you are not using keyboard shortcuts. The mouse had moved down to click the context menu and the tip appears at the mouse pointer, instead of highlighted text.

Rust library

For anyone interested, I whipped together a small library to help develop providers in Rust: tippytap

One of the main motivations was to reduce the latency on invoking tip to a minimum, which I think was a success.

Nice!

Cool idea!

I have a small feature request. Right now when opening the tooltip and hitting Escape, the focus doesn't go back to the previous window. Can this be fixed?

right-click?

I <3 tip. It's just so simple but so useful. Thanks again for creating it!

Sorry if this is a dumb question, but is it possible to integrate tip with the right-click menu? or some other option via the mouse only?

I'm usually trying to use the keyboard as much as possible and avoid the mouse, but in tip's case, of course the mouse highlight makes the most sense. The combination of mouse and keyboard shortcut however makes things a bit less than optimal.

Just curious if there's some ways to make things even a bit faster?

High-latency provider script

Problem

A real-world use case is a provider script that invokes https://dictionaryapi.com/ to get a meaning for a word.

The provider script might take a few seconds or more. Our tooltip should signal user about this delay by showing the loading icon.

Considerations

• How would it work with the current provider script that is instantaneous?

Design

The provider script returns the first result with the param hasMore:

{
  "items": [{"type": "text", "value": "instant item"}],
  "hasMore": true
}

When hasMore is true, Tip will show the items and the loading icon to user and wait for additional stdout.

This mechanism is endless if hasMore keeps being true.

When hasMore is false, the provider script should end after printing the JSON.

Tip will not end the provider script process.

Additional mechanism

• Tip should support timing out. Maybe we set it to 30 seconds.

Render HTML

We can support an HTML item where the provider provides static html code with width and height (and allow scrollability).

That would support a more advance use case like multi-line text and image and many other cases.

Tip/ExternalTipper.m#L91-L93

tip/mac-app/Tip/ExternalTipper.m

Lines 91 to 93 in ff04a89

	struct passwd *pw = getpwuid(getuid());
	assert(pw);
	task.launchPath = [NSString stringWithFormat:@"%@/.tip/provider", [NSString stringWithUTF8String:pw->pw_dir]];

FYI - You can just use NSHomeDirectory() here instead of dropping down into Darwin.

Looks like a fun and useful project; gonna give it a run when I get home. Thanks for sharing it!

Prevent focused app from receiving shortcut

I was wondering if it is possible to prevent the currently focused app from receiving the shortcut that is set for tip. In my case a recent update to Firefox has added some functionality to my chosen shortcut, which breaks my workflow (and there doesn't seem to be a way in Firefox to disable it).

I've chosen a new shortcut for now, which doesn't seem to have any conflicts with any apps I'm using, but it would be annoying if the same thing would happen again in the future. For tip to be truly usable everywhere in the system it would be great if it could take "full control" of the shortcut.

Brew installation & example service providers

Hey Tanin! Really love this utility. Two quick thoughts:

• brew install --cask tip works. Might be a good add to your installation instructions.
• Would be fun to encourage people to submit PRs for their provider scripts. Have there been any provider scripts you've come across that have been interesting?

Support of whitespace in app url handlers

macOS (and iOS) and a lot of apps for these platforms support a variety of custom url-handlers for data exchange.

One of my favourite integrations is with Flexibit's Fantastical to create new events via the terminal:

# see also https://flexibits.com/fantastical/help/integration-with-other-apps
$ open -g "x-fantastical3://parse?s=10:30 Meet Alice"

So I wrote a provider

def create_calendar(input)
  return [] unless input
  [{
       type: 'url',
       label: 'Create Event',
       value: "x-fantastical3://parse?s=#{input}"
  }]
end

The idea is sound but unfortunately, Tip does not open the URL if the input contains whitespace. URL encoding is not a viable option in this case since it will not be decoded.

A lot of other very interesting apps in the "Productivity Space" like Hammerspoon and BetterTouchTool have a url handler, which would open up a lot of interesting stuff.

I would love to see the custom URL handler being called with the full string.