324 lines
7.1 KiB
Markdown
324 lines
7.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|