253 lines
4.4 KiB
Markdown
253 lines
4.4 KiB
Markdown
# yourls-ui
|
|
|
|
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 (v0.1)
|
|
|
|
- System tray application
|
|
- Simple configuration window
|
|
- Uses YOURLS API with **signature authentication**
|
|
- Reads URL from clipboard
|
|
- Generates a short URL
|
|
- Copies the short URL back to clipboard
|
|
- Shows popup with clickable link
|
|
- Error reporting with API response
|
|
|
|
---
|
|
|
|
# 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. Copy the shortened link back to clipboard
|
|
6. Show a popup window with the result
|
|
|
|
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
|
|
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
|
|
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
|
|
```
|
|
|
|
The YOURLS API communication is encapsulated in `YourlsClient`.
|
|
|
|
---
|
|
|
|
# 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://example.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
|
|
|
|
```
|
|
v0.1
|
|
```
|
|
|
|
Initial working release.
|
|
|
|
---
|
|
|
|
# Author
|
|
|
|
```
|
|
deeaitch
|
|
```
|
|
|
|
---
|
|
|
|
# License
|
|
|
|
GPL
|