LocateCursor 🖱️🕵🏼

Ever lost your cursor on a big screen or with multiple monitors? It happens to the best of us! 😵‍💫😂

LocateCursor is a super lightweight tool for macOS that helps you find that sneaky cursor. When you fire it up, it dims your screen and shines a spotlight on your cursor. 🔍

What it can do ✨

• Cool Presets: Comes with default, presentation, and simple modes out of the box.
• Change it up: Tweak how the highlighter looks with command-line syntax.
• Command-Line Power: Use the terminal to switch modes or even create your own custom style.
• Multi-Monitor Friendly: The spotlight always finds your cursor, no matter which screen it's on.
• Feather-light: It's a simple app that won't hog your resources.

Installation 🛠️

1. Build or Download the Binary:

   • Build from source (see below), or download the pre-built locatecursor binary.

2. Copy to a Folder in Your PATH:

   • For example, to install to /usr/local/bin:

     sudo cp locatecursor /usr/local/bin/
     

   • Also copy the locatecursor.json configuration file to the same folder:

     sudo cp locatecursor.json /usr/local/bin/
     

   • Make sure the binary is executable:

     sudo chmod +x /usr/local/bin/locatecursor
     

3. Verify Installation:

   • Run:

     locatecursor --help
     

   • You should see usage instructions.

Note: The locatecursor.json file must be in the same folder as the locatecursor binary.

How to use it 🚀

You can run locatecursor straight from your terminal.

• Default Mode:

  locatecursor
  

  Dims the screen and puts a circle around your cursor for a second.

• Presentation Mode:

  locatecursor -p presentation
  

  Perfect for presentations! It shows a persistent, semi-transparent yellow circle around the cursor.

• Simple Mode:

  locatecursor -p simple
  

  Displays a simple red circle with a yellow border.

• Go Custom: You can get creative by passing a JSON string with your own settings:

  locatecursor -c '{"duration":5,"screenOpacity":0.1,"circle":{"radius":50,"opacity":0.8,"color":"blue","border":{"width":2,"color":"white"}}}'
  

• Turn it Off: To exit a persistent mode (like presentation), just type:

  locatecursor off
  

  Or, even easier, just press the Esc key!

Configuration ⚙️

You can tweak the settings in the locatecursor.json file. Place it in the same folder as the locatecursor executable. Feel free to change the existing presets or add your own.

Here's what the options mean:

{
  "default": {
    "duration": 1,
    "screenOpacity": 0.5,
    "circle": {
      "radius": 80,
      "opacity": 0.0,
      "color": "clear",
      "border": {
        "width": 2,
        "color": "white"
      }
    }
  },
  "presentation": {
    "duration": 0,
    "screenOpacity": 0.3,
    "circle": {
      "radius": 80,
      "opacity": 0.3,
      "color": "yellow",
      "border": {
        "width": 2,
        "color": "white"
      }
    }
  },
  "simple": {
    "duration": 5,
    "screenOpacity": 0,
    "circle": {
      "radius": 100,
      "opacity": 0.5,
      "color": "red",
      "border": {
        "width": 5,
        "color": "yellow"
      }
    }
  }
}

• duration: How long the highlighter stays visible (in seconds). 0 means it's on until you turn it off.
• screenOpacity: How much the screen dims (from 0.0 to 1.0).
• circle: All about the circle around your cursor.
  • radius: How big the circle is (in pixels).
  • opacity: How see-through the circle's color is (from 0.0 to 1.0).
  • color: The circle's fill color. Use names (like "red", "blue") or hex codes (like "#FF5733").
  • border: Give the circle a border.
    • width: How thick the border is (in pixels).
    • color: The border's color.

Building from Source 🛠️

You can build this with Xcode or right from your terminal.

With Xcode

1. Clone the repo:

   git clone https://github.com/luciodaou/LocateCursor.git
   

2. Open the project in Xcode.
3. Build it! The app will appear in the Products directory.

From the Command Line

swiftc LocateCursor/main.swift -o locatecursor -F /System/Library/Frameworks

This will create the locatecursor app in your project's root directory. Move it to a folder on PATH as instructed on Installation section.

License 📄

This project is under the MIT License. See the LICENSE file for details.

Support 🙏

If you like this app, consider supporting it. Thanks a bunch!

---

Icon from Helper icons created by Fathema Khanom - Flaticon