deeaitch/yourls-ui
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
v1.0
yourls-ui/README.md
T
deeaitch 39ab7acc08 Final readme
2026-10-01 12:02:03 -04:00

7.1 KiB
Raw Permalink Blame History

yourls-ui 1.0

Small Qt tray utility for shortening URLs using the YOURLS API.

The application sits in the system tray and allows quickly shortening the URL currently stored in the clipboard.

It was designed as a lightweight helper for everyday use with a self-hosted YOURLS instance.

Features (v1.0)

  • System tray application
  • Simple configuration window
  • Uses YOURLS API with signature authentication
  • Reads URL from clipboard
  • Accepts plain URLs, quoted URLs, Markdown links and browser URL MIME data
  • Generates a short URL
  • Reuses existing short links returned by YOURLS for duplicate URLs
  • Copies the short URL back to clipboard
  • Supports Wayland clipboard access through focused dialogs and verifies copying
  • Shows popup with clickable link
  • Error reporting with API response
  • Debug-only diagnostics for clipboard and API troubleshooting

How it works

  1. Application starts
  2. If configuration exists → it goes directly to the system tray
  3. If configuration is missing → settings window opens

From the tray menu you can run:

Cut URL

The application will:

  1. Read the current clipboard
  2. Check if the content is a valid URL
  3. Call the YOURLS API
  4. Receive a shortened link
  5. Show a popup window with the result
  6. Copy the shortened link back to clipboard and verify the copy

If YOURLS returns HTTP 400 with error:url and an existing short link for the same source URL, the application uses that link as a successful result.

On Wayland, Cut URL opens a small window when the application is inactive. Activate it to allow clipboard access; the URL is read automatically once the clipboard becomes available. You can also click Read clipboard, or cancel. The result window copies the short URL after gaining focus and displays whether the copy succeeded. Clicking OK retries and verifies the copy before closing.

Configuration

The settings window contains:

API URL
API signature

Example:

API URL:
https://example.com/yourls-api.php

Signature:
ABC123

⚠️ Important:

The signature field must contain only the signature value, not:

signature=ABC123

Correct:

ABC123

Tray menu

Right click the tray icon to access the menu:

Cut URL
Settings
Help
About
Exit

Double clicking the tray icon opens the settings window.

Building

Requirements:

Qt 6
Qt Widgets
Qt Network
qmake from Qt 6 (qmake6 on this system)
C++17 compiler

Build:

mkdir -p build-qt6
cd build-qt6
qmake6 ../yourls-ui.pro CONFIG+=release CONFIG-=debug
make

The Qt 6 qmake executable may be named qmake on other systems; check its version with qmake -v before building.

Or open yourls-ui.pro in Qt Creator, select a Qt 6 kit and use a new build directory separate from any existing Qt 5 build.

Debugging clipboard URLs

Build and run a debug executable from a terminal:

mkdir -p build/Desktop-Debug
cd build/Desktop-Debug
qmake6 ../../yourls-ui.pro CONFIG+=debug CONFIG-=release
make
./yourls-ui 2>clipboard-debug.log

Exit any already running instance before starting this executable. Choose Cut URL and inspect clipboard-debug.log. Debug builds log the executable path, Qt platform, clipboard MIME formats, raw text and its UTF-8 hex bytes, parsed URL, request stage, HTTP status and API status. The API signature and full request query are not logged. Clipboard diagnostics may contain private URLs; review the log before sharing it. These diagnostics are compiled out of release builds using QT_NO_DEBUG.

Project structure

main.cpp
    Application entry point

mainwindow.h / mainwindow.cpp
    Main application window
    Tray integration
    UI logic

mainwindow.ui
    Qt Designer UI for settings window

yourlsclient.h / yourlsclient.cpp
    YOURLS API client
    Handles HTTP requests and responses

clipboardurl.h
    Clipboard MIME data and URL text parsing

clipboardresultdialog.h
    Focus-aware clipboard writing and copy verification

tests/
    Standalone qmake projects for automated tests

The YOURLS API communication is encapsulated in YourlsClient.

Tests

The tests/ directory contains three independent test executables:

Test Coverage
clipboardurl_test Plain, quoted and Markdown URLs; browser MIME URLs; query strings, fragments and parentheses; invalid or empty input.
yourlsclient_test HTTP 200 success, HTTP 400 duplicate reuse, rejection of mismatched or invalid links, other API errors and HTTP 500; URL encoding in requests.
clipboardresultdialog_test No clipboard overwrite before focus, automatic copying on activation, copy verification and retry, and copying on platforms without the focus requirement.

Tests require Qt 6 and a C++17 compiler. The API and dialog tests also require the Qt Test module; the dialog test uses Qt Widgets and the API test uses Qt Network.

Run the following from the repository root. Each subshell builds and runs one test in its own directory:

mkdir -p build/tests/clipboardurl build/tests/yourlsclient build/tests/clipboardresultdialog

(
  cd build/tests/clipboardurl &&
  qmake6 ../../../tests/clipboardurl_test.pro &&
  make &&
  ./clipboardurl_test
)

(
  cd build/tests/yourlsclient &&
  qmake6 ../../../tests/yourlsclient_test.pro &&
  make &&
  ./yourlsclient_test
)

(
  cd build/tests/clipboardresultdialog &&
  qmake6 ../../../tests/clipboardresultdialog_test.pro &&
  make &&
  QT_QPA_PLATFORM=offscreen ./clipboardresultdialog_test
)

The API test starts a local HTTP server and requires permission to bind a loopback port. It uses a test signature and does not contact a real YOURLS instance. The dialog test uses Qt's offscreen platform for automated checks; it does not verify a real Wayland compositor.

For a manual Wayland check, copy a URL in another application, choose Cut URL, activate the clipboard dialog, then activate the result window. Confirm that it reports a successful copy, close it with OK, and paste into another application. Repeat with the same URL to verify reuse of the existing short link. Debug builds additionally report verified: true for a successful clipboard write.

API call

The application performs a request similar to:

GET /yourls-api.php
?action=shorturl
&format=json
&signature=<signature>
&url=<url>

Example:

https://example.com/yourls-api.php?action=shorturl&format=json&signature=ABC123&url=https%3A%2F%2Fexample.com

Future ideas

Possible improvements for future versions:

Hotkey support

Global hotkey to trigger URL shortening.

Clipboard watcher

Automatically detect URLs copied to clipboard.

Tray notifications

Use system notifications instead of popup dialog.

Recent history

Store last shortened URLs.

Custom alias

Allow specifying custom short URL alias.

Open YOURLS admin

Add tray menu entry for opening YOURLS admin panel.

Packaging

Provide:

AppImage
.deb package

Version

v1.0

Stable release with Wayland clipboard support, verified short URL copying, reuse of existing YOURLS links, automated regression tests and debug diagnostics.

Author

deeaitch

License

GPL

Reference in new issue View Git Blame Copy Permalink