## 1. Project Overview & Quickstart (flameshot-org/flameshot) ## File: README.md ## Preview ## Index - [Features](#features) - [Usage](#usage) - [Usage on Windows](#usage-on-windows) - [Usage on Hyprland / Sway / wlroots](#usage-on-hyprland--sway--wlroots) - [Usage on minimal X11 window managers](#usage-on-minimal-x11-window-managers) - [CLI configuration](#cli-configuration) - [Config file](#config-file) - [Keyboard Shortcuts](#keyboard-shortcuts) - [Local](#local) - [Global](#global) - [On KDE Plasma desktop](#on-kde-plasma-desktop) - [On Gnome (Ubuntu, Fedora and more)](#on-gnome-ubuntu-fedora-and-more) - [On XFCE 4](#on-xfce-4) - [On Fluxbox](#on-fluxbox) - [Considerations](#considerations) - [Installation](#installation) - [Prebuilt Packages](#prebuilt-packages) - [Packages from Repository](#packages-from-repository) - [MacOS](#macos) - [Windows](#windows) - [Compilation](#compilation) - [Dependencies](#dependencies) - [Compile-time](#compile-time) - [Run-time](#run-time) - [Optional](#optional) - [Debian](#debian) - [Fedora](#fedora) - [Arch](#arch) - [Build](#build) - [Install](#install) - [License](#license) - [Privacy Policy](#privacy-policy) - [Code Signing Policy](#code-signing-policy) - [Contribute](#contribute) - [Acknowledgment](#acknowledgment) ## Features - Customizable appearance. - Easy to use. - In-app screenshot editing. - DBus interface. - Upload to Imgur. ## Usage Executing the command `flameshot` without parameters will launch a running instance of the program in the background without taking actions. If your desktop environment provides tray area, a tray icon will also appear in the tray for users to perform configuration and management. Example commands: - Capture with GUI: ```shell flameshot gui ``` - Capture with GUI with custom save path: ```shell flameshot gui -p ~/myStuff/captures ``` - Capture with GUI after 2 seconds delay (can be useful to take screenshots of mouse hover tooltips, etc.): ```shell flameshot gui -d 2000 ``` - Fullscreen capture with custom save path (no GUI) and delayed: ```shell flameshot full -p ~/myStuff/captures -d 5000 ``` - Fullscreen capture with custom save path copying to clipboard: ```shell flameshot full -c -p ~/myStuff/captures ``` - Capture the screen containing the mouse and print the image (bytes) in PNG format: ```shell flameshot screen -r ``` - Capture the screen number 1 and copy it to the clipboard: ```shell flameshot screen -n 1 -c ``` In case of doubt choose the first or the second command as shortcut in your favorite desktop environment. A systray icon will be in your system's panel while Flameshot is running. Do a right click on the tray icon and you'll see some menu items to open the configuration window and the information window. Check out the About window to see all available shortcuts in the graphical capture mode. ### Usage on Windows On Windows, `flameshot.exe` will behave as expected for all supported command-line arguments, but it will not output any text to the console. This is problematic if, for example, you are running `flameshot.exe -h`. If you require console output, run `flameshot-cli.exe` instead. `flameshot-cli.exe` is a minimal wrapper around `flameshot.exe` that ensures all stdout is captured and output to the console. ### Usage on Hyprland / Sway / wlroots Please [refer to this document](docs/UsageHyprlandSwayWlroots.md) for detailed instructions on how to set up Flameshot on Hyprland, Sway, and wlroots-based Wayland compositors. ### Usage on minimal X11 window managers On minimal X11 window managers (i3, dwm, xmonad, bspwm, ...), capturing may fail because no portal backend implements the Screenshot interface (errors such as *"Could not locate the org.freedesktop.portal.Desktop service"* or *"Screenshot portal timed out"*). Please [refer to this document](docs/UsageX11MinimalWM.md) for the fix (enabling the legacy X11 capture). ### CLI configuration You can use the graphical menu to configure Flameshot, but alternatively you can use your terminal or scripts to do so. - Open the configuration menu: ```shell flameshot config ``` - Show the initial help message in the capture mode: ```shell flameshot config --showhelp true ``` - For more information about the available options use the help flag: ```shell flameshot config -h ``` ### Config file You can also edit some of the settings (like overriding the default colors) in the configuration file.\ Linux path: `~/.config/flameshot/flameshot.ini`.\ Windows path: `C:\Users\{YOURNAME}\AppData\Roaming\flameshot\flameshot.ini`. When copying over the config file from Linux to Windows or vice versa, make sure to correct the `savePath` variable,\ so that the screenshots save in the right directory on your desired file system. ## Keyboard shortcuts ### Local These shortcuts are available in GUI mode: | Keys | Description | |--- |--- | | P | Set the Pencil as paint tool | | D | Set the Line as paint tool | | A | Set the Arrow as paint tool | | S | Set Selection as paint tool | | R | Set the Rectangle as paint tool | | C | Set the Circle as paint tool | | M | Set the Marker as paint tool | | T | Add text to your capture | | B | Set Pixelate as the paint tool | | ←, ↓, ↑, → | Move selection 1px | | Shift + ←, ↓, ↑, → | Resize selection 1px | | Ctrl + Shift + ←, ↓, ↑, → | Symmetrically resize selection 2px | | Esc | Quit capture | | Ctrl + M | Move the selection area | | Ctrl + C | Copy to clipboard | | Ctrl + S | Save selection as a file | | Ctrl + Z | Undo the last modification | | Ctrl + Shift + Z | Redo the next modification | | Ctrl + Q | Leave the capture screen | | Ctrl + O | Choose an app to open the capture | | Ctrl + Return | Commit text in text area| | Ctrl + Backspace | Cancel current selection | | Return | Upload the selection to Imgur | | Spacebar | Toggle visibility of sidebar with options of the selected tool, color picker for the drawing color and history menu | | G | Starts the color picker | | Right Click | Show the color wheel | | Mouse Wheel | Change the tool's thickness | | Print screen | Capture Screen | | Shift + Print | Screenshot History | | Ctrl + drawing *line*, *arrow* or *marker* | Drawing only horizontally, vertically or diagonally | | Ctrl + drawing *rectangle* or *circle* | Keeping aspect ratio | Shift + drag a handler of the selection area: mirror redimension in the opposite handler. ### Global - Windows: Prt Sc (fixed, cannot be changed) and Win + Shift + X (can be changed in the settings) - macOS: cmd + Shift + X (can be changed in the settings) - Linux: Flameshot doesn't yet support Prt Sc out of the box, but you can set this up with a bit of configuration: #### On KDE Plasma desktop To make configuration easier, there's a [file](docs/shortcuts-config/flameshot-shortcuts-kde.kksrc) in the repository that more or less automates this process. This file will assign the following hotkeys by default: | Keys | Description | |--- |--- | | Prt Sc | Start the Flameshot screenshot tool and take a screenshot | | Ctrl + Prt Sc | Wait for 3 seconds, then start the Flameshot screenshot tool and take a screenshot | | Shift + Prt Sc | Take a full-screen (all monitors) screenshot and save it | | Ctrl + Shift + Prt Sc | Take a full-screen (all monitors) screenshot and copy it to the clipboard | If you don't like the defaults, they can be changed later. Steps for using the configuration: 1. The configuration file makes Flameshot automatically save screenshots to `~/Pictures/Screenshots` without opening the save dialog. Make sure that folder exists by running: ```shell mkdir -p ~/Pictures/Screenshots ``` (If you don't like the default location, you can skip this step and configure your preferred directory later.) 2. Download the configuration file: ```shell cd ~/Desktop wget https://raw.githubusercontent.com/flameshot-org/flameshot/master/docs/shortcuts-config/flameshot-shortcuts-kde.khotkeys ``` 3. Make sure you have the `khotkeys` installed using your package manager to enable custom shortcuts in KDE Plasma. 4. Go to _System Settings_ → _Shortcuts_ → _Custom Shortcuts_. 5. If an entry exists for Spectacle (the default KDE screenshot utility), you'll need to disable it because its shortcuts might conflict with Flameshot's. Do this by unchecking the _Spectacle_ entry. 6. Click _Edit_ → _Import..._, navigate to the configuration file and open it. 7. Now the Flameshot entry should appear in the list. Click _Apply_ to apply the changes. 8. If you want to change the default hotkeys, you can expand the entry, select the appropriate action and modify it as you wish; the process is pretty self-explanatory. 9. If you installed Flameshot as a Flatpak, you will need to create a symlink to the command: ```shell ln -s /var/lib/flatpak/exports/bin/org.flameshot.Flameshot ~/.local/bin/flameshot ``` #### On Gnome (Ubuntu, Fedora and more) To use Flameshot instead of the default screenshot application in Gnome we need to remove the binding on Prt Sc key, and then create a new binding for `flameshot gui` ([adapted](https://askubuntu.com/posts/1039949/revisions) from [Pavel's answer on AskUbuntu](https://askubuntu.com/revisions/1036473/1)). 1. Remove the binding on Prt Sc: Go to _Settings_ > _Keyboard_ > _View and Customise Shortcuts_ > _Screenshots_ > _Take a screenshot interactively_ and press `backspace` 2. Add custom binding on Prt Sc: Go to _Settings_ > _Keyboard_ > _View and Customise Shortcuts_ > _Custom shortcuts_ and press the '+' button at the bottom. 3. Name the command as you like it, e.g. `flameshot`. And in the command insert `/usr/bin/flameshot gui` or `flatpak run org.flameshot.Flameshot gui` if installed via flatpak. 4. Then click "_Set Shortcut.._" and press Prt Sc. This will show as "_print_". Now every time you press Prt Sc, it will start the Flameshot GUI instead of the default application. #### On XFCE 4 1. Go to `Keyboard` settings 2. Switch to the tab `Application Shortcuts` 3. Find the entry ```text Command Shortcut xfce4-screenshooter -fd 1 Print ``` 4. Replace `xfce4-screenshooter -fd 1` with `flameshot gui` Now every time you press Prt Sc it will start Flameshot GUI instead of the default application. #### On Fluxbox 1. Edit your `~/.fluxbox/keys` file 2. Add a new entry. `Print` is the key name, `flameshot gui` is the shell command; for more options see [the fluxbox wiki](https://sillyslux.github.io/fluxbox-wiki/en/wiki/Keyboard-Shortcuts/). ```text Print :Exec flameshot gui ``` 3. Refresh Fluxbox configuration with **Reconfigure** option from the menu. ## Considerations - Experimental Gnome Wayland and Plasma Wayland support. - If you are using Gnome you need to install the [AppIndicator and KStatusNotifierItem Support](https://extensions.gnome.org/extension/615/appindicator-support/) extension in order to see the system tray icon. - Press Enter or Ctrl + C when you are in a capture mode and you don't have an active selection and the whole desktop will be copied to your clipboard. Pressing Ctrl + S will save your capture to a file. Check the [Shortcuts](#keyboard-shortcuts) for more information. - Flameshot works best with a desktop environment that includes D-Bus. See this [article](https://wiki.archlinux.org/index.php/Flameshot#Troubleshooting) for tips on using Flameshot in a minimal window manager (dwm, i3, xmonad, etc). - In order to speed up the first launch of Flameshot (D-Bus init of the app can be slow), consider starting the application automatically on boot. - Quick tip: If you don't have Flameshot to autostart at boot and you want to set keyboard shortcut, use the following as the command for the keybinding: ```sh ( flameshot &; ) && ( sleep 0.5s && flameshot gui ) ``` ## Installation Flameshot can be installed on Linux, Microsoft Windows, and macOS. ### Prebuilt packages Some prebuilt packages are provided on [the release page of the GitHub project repository](https://github.com/flameshot-org/flameshot/releases). ### Packages from Repository There are packages available in the repository of some Linux distributions: - [Arch](https://archlinux.org/packages/extra/x86_64/flameshot/): `pacman -S flameshot` + Snapshot also available via AUR: [flameshot-git](https://aur.archlinux.org/packages/flameshot-git). - [Debian 10+](https://tracker.debian.org/pkg/flameshot): `apt install flameshot` + Package for Debian 9 ("Stretch") also [available via stretch-backports](https://backports.debian.org/). - [Ubuntu](https://launchpad.net/ubuntu/+source/flameshot): `apt install flameshot` + A [PPA supporting Ubuntu 22.04 and newer](https://launchpad.net/~quentiumyt/+archive/ubuntu/flameshot) is provided by [Quentin Lienhardt](https://github.com/QuentiumYT) that offers an up-to-date version of `flameshot`. - [openSUSE](https://software.opensuse.org/package/flameshot): `zypper install flameshot` - [Void Linux](https://github.com/void-linux/void-packages/tree/master/srcpkgs/flameshot): `xbps-install flameshot` - [Solus](https://dev.getsol.us/source/flameshot/): `eopkg it flameshot` - [Fedora](https://src.fedoraproject.org/rpms/flameshot): `dnf install flameshot` - [NixOS](https://search.nixos.org/packages?query=flameshot): `nix-env -iA nixos.flameshot` - [ALT](https://packages.altlinux.org/en/sisyphus/srpms/flameshot/): `su - -c "apt-get install flameshot"` - [Snap/Flatpak/AppImage](https://github.com/flameshot-org/packages) - [Docker](https://github.com/ManuelLR/docker-flameshot) - [Windows](https://github.com/majkinetor/au-packages/tree/master/flameshot) ### macOS - [MacPorts](https://www.macports.org): `sudo port selfupdate && sudo port install flameshot` - [Homebrew](https://brew.sh): `brew install --cask flameshot` **Note** that because of macOS security features, you may not be able to open flameshot when installed using brew. If you see the message `“flameshot” cannot be opened because the developer cannot be verified.` you will need to follow the steps below: 1. Go to the Applications folder (Finder > Go > Applications, or Shift+Command+A) 1. Right-Click on "flameshot.app" and choose "Open" from the context menu 2. In the dialog click "Open" On MacOs 15 and above, you will have to go to system settings -> privacy and security after doing this and click "Open Anyway" or you can open flameshot first time with the following command. ```sudo xattr -rd com.apple.quarantine /Applications/flameshot.app``` After following all those steps above, `flameshot` will open without problems in your Mac. ### Windows - [Scoop](https://github.com/ScoopInstaller/Extras/blob/master/bucket/flameshot.json): `scoop install flameshot` Expand this section to see what distros are using an up to date version of flameshot ### Tray icon **Note** that for the Flameshot icon to appear in your tray area, you should have a systray software installed. This is especially true for users who use minimal [window managers](https://wiki.archlinux.org/index.php/window_manager) such as [dwm](https://dwm.suckless.org/). In some [Desktop Environment](https://wiki.archlinux.org/index.php/Desktop_environment) installations (e.g Gnome), the systray might be missing and you can install an application or plugin (e.g [Gnome shell extension](https://extensions.gnome.org/extension/1503/tray-icons/)) to add the systray to your setup. It has been [reported](https://github.com/flameshot-org/flameshot/issues/1009#issuecomment-700781081)) that icon of some software, including Flameshot, does not show in [gnome-shell-extension-appindicator](https://github.com/ubuntu/gnome-shell-extension-appindicator). Alternatively, in case you don't want to have a systray, you can always call Flameshot from the terminal. See [Usage section](#usage). ## Compilation To build the application in your system, you'll need to install the dependencies needed for it and package names might be different for each distribution, see [Dependencies](#dependencies) below for more information. You can also install most of the Qt dependencies via [their installer](https://www.qt.io/download-qt-installer). If you were developing Qt apps before, you probably already have them. This project uses [CMake](https://cmake.org/) build system, so you need to install it in order to build the project (on most Linux distributions it is available in the standard repositories as a package called `cmake`). If your distribution provides too old version of CMake (e.g. Ubuntu or Debian) you can [download it on the official website](https://cmake.org/download/). Also you can open and build/debug the project in a C++ IDE. For example, in Qt Creator you should be able to simply open `CMakeLists.txt` via `Open File or Project` in the menu after installing CMake into your system. [More information about CMake projects in Qt Creator](https://doc.qt.io/qtcreator/creator-project-cmake.html). ### Dependencies #### Compile-time - Qt >= 6.2.4 (available by default on Ubuntu Jammy) + Development tools - GCC >= 11 - CMake >= 3.22 #### Run-time - Qt + SVG #### Optional - Git - OpenSSL - CA Certificates - Qt Image Formats - for additional export image formats (e.g. tiff, webp, and more) #### Debian ```shell # Compile-time apt install g++ cmake build-essential qt6-base-dev qt6-tools-dev-tools qt6-svg-dev qt6-tools-dev # Run-time apt install libkf6guiaddons-dev libqt6dbus6 libqt6network6 libqt6core6 libqt6widgets6 libqt6gui6 libqt6svg6 qt6-qpa-plugins # Optional apt install git openssl ca-certificates qt6-image-formats-plugins ``` #### Fedora ```shell # Compile-time dnf install gcc-c++ cmake qt6-qtbase-devel qt6-qtsvg-devel qt6-qttools qt6-linguist qt6-qttools-devel kf6-kguiaddons-devel # Run-time dnf install qt6-qtbase qt6-qtsvg kf6-kguiaddons # Optional dnf install git openssl ca-certificates qt6-qtimageformats ``` #### Arch ```shell # Compile-time pacman -S cmake base-devel git qt6-base qt6-tools kguiaddons # Run-time pacman -S qt6-svg # Optional pacman -S openssl ca-certificates qt6-imageformats ``` #### Nix Development Shell: ```shell # Without flakes: nix-shell # With flakes: nix develop ``` ```shell # Build flameshot nix build # Build and run flameshot nix run ``` #### macOS First of all you need to install [brew](https://brew.sh) and then install the dependencies ```shell brew install qt6 brew install cmake ``` ### Build After installing all the dependencies, Flameshot can be built. #### Installation/build dir For the translations to be loaded correctly, the build process needs to be aware of where you want to install Flameshot. ```shell # Directory where build files will be placed, may be relative export BUILD_DIR=build # Directory prefix where Flameshot will be installed. If you are just building and don't want to # install, comment this environment variable. # This excludes the bin/flameshot part of the install, # e.g. in /opt/flameshot/bin/flameshot, the CMAKE_INSTALL_PREFIX is /opt/flameshot # This must be an absolute path. Requires CMAKE 3.29. export CMAKE_INSTALL_PREFIX=/opt/flameshot # Linux cmake -S . -B "$BUILD_DIR" \ && cmake --build "$BUILD_DIR" #MacOS cmake -S . -B "$BUILD_DIR" \ -DQt6_DIR="$(brew --prefix qt6)/lib/cmake/Qt6" \ && cmake --build "$BUILD_DIR" ``` When the `cmake --build` command has completed you can launch Flameshot from the `project_folder/build/src` folder. ### Install Note that if you install from source, there _is no_ uninstaller, so consider installing to a custom directory. #### To install into a custom directory Make sure you are using cmake `>= 3.29` and build Flameshot with `$CMAKE_INSTALL_PREFIX` set to the installation directory. If this is not done, the translations won't be found when using a custom directory. Then, run the following: ```bash # !Build with CMAKE_INSTALL_PREFIX and use cmake >= 3.29! Using an older cmake will cause # installation into the default /usr/local dir. # You may need to run this with privileges cmake --install "$BUILD_DIR" ``` #### To install to the default install directory ```bash # You may need to run this with privileges cmake --install "$BUILD_DIR" ``` ### FAQ ## License - The main code is licensed under [GPLv3+](LICENSE) - The logo of Flameshot is licensed under [Free Art License v1.3](data/img/app/flameshotLogoLicense.txt) - The button icons are licensed under Apache License 2.0. See: https://github.com/google/material-design-icons - The code at capture/capturewidget.cpp is based on https://github.com/ckaiser/Lightscreen/blob/master/dialogs/areadialog.cpp (GPLv2) - The code at capture/capturewidget.h is based on https://github.com/ckaiser/Lightscreen/blob/master/dialogs/areadialog.h (GPLv2) - I copied a few lines of code from KSnapshot regiongrabber.cpp revision `796531` (LGPL) - Qt-Color-Widgets taken and modified from https://github.com/mbasaglia/Qt-Color-Widgets (see their license and exceptions in the project) (LGPL/GPL) Info: If I take code from your project and that implies a relicense to GPLv3+, you can reuse my changes with the original previous license of your project applied. ## Privacy Policy This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. ## Code Signing Policy For Windows binaries, this program uses free code signing provided by [SignPath.io](https://signpath.io?utm_source=foundation&utm_medium=github&utm_campaign=flameshot), and a certificate by the [SignPath Foundation](https://signpath.org?utm_source=foundation&utm_medium=github&utm_campaign=flameshot). Code signing is currently a manual process so not every patch release will be signed. ## Contribute If you want to contribute check the [CONTRIBUTING.md](docs/CONTRIBUTING.md) ## Acknowledgment Thanks to those who have shown interest in the early development process: - [lupoDharkael](https://github.com/lupoDharkael) - [Cosmo](https://github.com/philpem) - [XerTheSquirrel](https://github.com/XerTheSquirrel) - [The members of Sugus GNU/Linux](https://github.com/SUGUS-GNULinux) - ismatori Thanks to sponsors: - [Namecheap](https://www.namecheap.com/) - [JetBrains](https://www.jetbrains.com/) - [SignPath](https://signpath.io/) - [addy.io](https://addy.io/) --- ## File: data/img/material/README.md Google Material Design Icons are licensed under Apache License 2.0 (see LICENSE.txt) --- ## File: docs/dev/src/debugging.md # Debugging ## `FLAMESHOT_DEBUG_CAPTURE` With this cmake variable set to `ON`, the flameshot capture GUI window won't bypass the window manager. This allows you to manipulate the capture GUI window like any other window while debugging. This can be useful if a debugging breakpoint is triggered while flameshot is in full screen mode. Without this variable, you might have trouble inspecting the code due to a frozen full-screen window. Usage: ```shell cmake -DFLAMESHOT_DEBUG_CAPTURE=ON ... ``` --- ## File: docs/dev/src/docs.md # Maintaining the documentation The narrative documentation is written in markdown and built into HTML using [MkDocs][mkdocs], particularly the [MkDocs material theme][mkdocs-material]. The source code documentation is generated using Doxygen and adapted for MkDocs using [MkDoxy][mkdoxy] (a tweaked custom fork of the original). The source code of this documentation can be found [here][doc-source]. !!! tip In order to edit a page from the documentation, click the :material-pencil: button in the top right corner of the page. Please note that this button won't work within the API section of the documentation - the button is removed from there during [post-processing][], but it will still be visible when [serving the website locally][serving-locally]. ## Serving locally To serve the documentation locally, run the `make serve` target in the `docs/dev` directory. The server is available at the port designated in the output of the command. ## Notes and conventions - When you add new files or rename existing files or section names, be sure to edit the `nav` property of [mkdocs.yml][mkdocs.yml]. - Always insert links as [reference style links][markdown:reference-style-links]. This will make the docs source code more readable and make broken links more easily detectable and replaceable. ### Post-processing There are some tweaks we make to the generated HTML documentation. We do that in the `make build` target, by running the [post-process.sh][post-process.sh] script. To see what post-processing we do, see that file. For this reason, the version of the documentation served locally using `make serve` will not match the generated HTML documentation 100%. But those inconsistencies are few and minor. ## Dependencies ```shell pip install \ mkdocs \ mkdocs-material \ git+https://github.com/veracioux/mkdoxy@v1.0.0 ``` !!! note We use a forked version of [mkdoxy][mkdoxy-original] that can be found [here][mkdoxy], that fixes some annoying things from the original. ## Deployment The developer documentation is served from the official Flameshot website [flameshot.org][website]. Here's how. The official website itself is served from this [repo][website-repo]. That repo contains the user documentation. It's deployed using GitHub pages -- the served files can be found on the [gh-pages][] branch of that repo. This branch is automatically created by the [build][website-build] workflow on master. To make the developer docs available on the official site, we use a custom GitHub action called [deploy-dev-docs][] in the [flameshot][] repo. This action will build and deploy this documentation into the `docs/dev` subdirectory of the [gh-pages][] branch. ### The deploy-dev-docs GitHub workflow This workflow checks out the flameshot website [repo][website-repo] and does the following: - Creates a clean [dev-docs-staging][] branch (we'll explain why, below). - Generates the developer docs under `docs/dev` there and makes a commit - Checks out the [gh-pages][] branch and makes the same commit there - Force-pushes the dev-docs-staging branch to the website repo - Pushes the gh-pages branch to the website repo Since the [gh-pages][] branch is re-created from scratch by the [website deployment workflow][website-build], the commit that added the developer documentation will be lost. That's why we have to re-apply the commit during the [website deployment workflow][website-build] as well. **That is the reason why we created the** [**dev-docs-staging**][dev-docs-staging] **branch in the first place.** !!! note The deploy-dev-docs workflow is set to run on the `docs` branch as well as `master`. This branch is used for debugging the developer docs and its associated workflows, without polluting the `master` branch with unnecessary commits. #### Access tokens In order to make changes to the [website repo][website-repo] from within a workflow in the [flameshot repo][flameshot], the workflow needs to use an access token, which it obtains from the `TOKEN_PUSH_TO_WEBSITE_REPO` secret. The following process was used to set it up: 1. A flameshot organization member with write access must create a personal access token (PAT) [here][PAT] with write access to the [website repo][website-repo]. 2. A secret named `TOKEN_PUSH_TO_WEBSITE_REPO` must be added to the [flameshot][] repo and its value must be set to the PAT. This can be done [here][action-secrets]. For best security practice, the token should be set to expire after some time (currently ~6 months). The token can be regenerated without the need to recreate it. After regeneration you will need to update the `TOKEN_PUSH_TO_WEBSITE_REPO` secret, which can be done [here][edit-secret]. !!! tip The currently active PAT is owned by [veracioux][] and is set to expire on July 31 2024. If you notice the token has expired, ask him to re-generate it. [post-processing]: #post-processing [serving-locally]: #serving-locally [flameshot]: https://github.com/flameshot-org/flameshot [website]: https://flameshot.org [doc-source]: https://github.com/flameshot-org/flameshot/tree/master/docs/dev [website-repo]: https://github.com/flameshot-org/flameshot-org.github.io [gh-pages]: https://github.com/flameshot-org/flameshot-org.github.io/tree/gh-pages [dev-docs-staging]: https://github.com/flameshot-org/flameshot-org.github.io/tree/dev-docs-staging [action-secrets]: https://github.com/flameshot-org/flameshot/settings/secrets/actions [edit-secret]: https://github.com/flameshot-org/flameshot/settings/secrets/actions/TOKEN_PUSH_TO_WEBSITE_REPO [mkdocs.yml]: https://github.com/flameshot-org/flameshot/blob/master/docs/dev/mkdocs.yml [post-process.sh]: https://github.com/flameshot-org/flameshot/blob/master/docs/dev/post-process.sh [deploy-dev-docs]: https://github.com/flameshot-org/flameshot/blob/master/.github/workflows/deploy-dev-docs.yml [website-build]: https://github.com/flameshot-org/flameshot-org.github.io/blob/master/.github/workflows/build.yml [markdown:reference-style-links]: https://www.markdownguide.org/basic-syntax/#reference-style-links [mkdocs]: https://www.mkdocs.org/ [mkdocs-material]: https://squidfunk.github.io/mkdocs-material [mkdoxy-original]: https://github.com/JakubAndrysek/mkdoxy [mkdoxy]: https://github.com/veracioux/mkdoxy [PAT]: https://github.com/settings/tokens?type=beta [veracioux]: https://github.com/veracioux --- ## File: docs/dev/src/faq.md # FAQ !!! todo Incomplete page. ### How do I create a new subcommand? ### How do I add a new tool? ### How do I add a new config setting? There are currently two groups of settings: `General` and `Shortcuts`. The necessary steps are usually the following: - Determine a name for the setting - for a general setting, it must be a valid C++ identifier, for a shortcut it must be the name of a tool type from TODO. - Add a getter and a setter for the setting in [`ConfigHandler`][ConfigHandler]. For most settings you should use the [`CONFIG_GETTER_SETTER`][CONFIG_GETTER_SETTER] macro. If your setting is unusual enough you may need to use [`CONFIG_GETTER`][CONFIG_GETTER] or [`CONFIG_SETTER`][CONFIG_SETTER] individually, or even need to create the methods manually. - If you need custom validation or conversion for the value, you must create a subclass of [`ValueHandler`][ValueHandler]. Otherwise you can use one of the existing ones in [valuehandler.h][]. - If you want to make your setting available in the configuration GUI (usually you do), you should add the appropriate widgets into one of the tabs of [`ConfigWindow`][ConfigWindow]. If your setting doesn't fit into any of the existing tabs, you can add a new one, but please discuss it with us first. To get a deeper understanding of how the configuration works, please see [Configuration][config]. ### How do I add a new export action? (@borgmanJeremy @mehrad This is my preferred terminology over final action, need consensus) [config]: index.md#configuration [confighandler.h]: flameshot/confighandler_8h [confighandler.cpp]: flameshot/confighandler_8cpp [valuehandler.h]: flameshot/valuehandler_8h [ValueHandler]: flameshot/classValueHandler [ConfigHandler]: flameshot/classConfigHandler [ConfigWindow]: flameshot/classConfigWindow [CONFIG_GETTER_SETTER]: flameshot/confighandler_8h/#define-config_getter_setter [CONFIG_GETTER]: flameshot/confighandler_8h/#define-config_getter [CONFIG_SETTER]: flameshot/confighandler_8h/#define-config_setter --- ## File: docs/dev/src/index.md # Flameshot developer docs Thank you for your interest in developing flameshot. This developer documentation (hopefully) has an intuitive structure. It tries to describe what code is run when a user performs an action in Flameshot. !!! important **Please read this entire page. It will make your life a whole lot easier when contributing to Flameshot. If you know exactly what you want to work on, you should look at [FAQ](./faq) ** ## Project structure Flameshot is built on C++/Qt5 with CMake as its build system. The source code is located under `src/`. The entrypoint is `src/main.cpp`. ### `main.cpp` Flameshot provides both a GUI and a CLI (the latter currently works only on Linux and macOS). ### Build system The main cmake file is `CMakeLists.txt` in the project root. It `include`s some files from the `cmake/` directory as well. These files together control some more general aspects of the build process, like project information, packaging, caching etc. There is also the file `src/CMakeLists.txt`. It mostly defines how the source files are compiled into targets and how the external libraries are linked. It does some other stuff too. Currently, there isn't a clear separation of concerns between `CMakeLists.txt` and `src/CMakeLists.txt`. In the future we should refactor these files to make it more clear why each of them exists. ## What happens when I launch flameshot? There are two ways to launch flameshot: daemon mode and single-action mode. In both modes, an instance of [`Flameshot`][Flameshot] is created via [`Flameshot::start()`][Flameshot::start]. [`Flameshot`][Flameshot] provides the high level API for interacting with flameshot; and its methods mimic the CLI subcommands a great deal. This object is a singleton, so it can only be created once. It is accessed as [`Flameshot::instance()`][Flameshot::instance]. !!! note On Windows, only daemon mode is currently supported. ### Single-action mode (via command line interface) Single-action mode (also called one-off mode) is triggered when flameshot is launched with a command line argument - for example as `flameshot gui`. As its name implies, it performs a single action, such as "take a screenshot interactively by opening a GUI" or "take a screenshot of the entire screen", etc. Afterwards, Flameshot quits. ### Daemon mode This mode is triggered when the `flameshot` command is launched. In this mode, a flameshot process is started in the background. A system tray is displayed if the user hasn't disabled it in the config. In addition to [`Flameshot::start()`][Flameshot::start], if the current process is the daemon, it also calls [`FlameshotDaemon::start()`][FlameshotDaemon::start] during initialization. The daemon has the following purposes: - Run in the background, wait for the user to press a hotkey, and perform corresponding action. This is true for **Windows** and **macOS**, but not for **Linux**. On Linux, hotkeys are meant to be handled by the desktop environment or equivalent. - Provide a system tray that the user can click to initiate actions via context menu - Periodically check for updates and notify the user - Act as a host for persistent phenomena. Example: On X11 (linux), when a program inserts content into the clipboard, it must keep running so the content persists in the clipboard. !!! note All of the above are user-configurable. #### `FlameshotDaemon` The class [`FlameshotDaemon`][FlameshotDaemon] handles all communication with the daemon. The class provides public static methods that are designed so that the caller does not need to know if the current process is a flameshot daemon or a single-action invocation of Flameshot. If the current process is the daemon, then the static methods of [`FlameshotDaemon`][FlameshotDaemon] will call the corresponding instance methods of the singleton. If not, the current process will communicate with the daemon process via D-Bus. Then, within the daemon process, those D-Bus calls will be translated into [`FlameshotDaemon`][FlameshotDaemon] instance method calls. ## Configuration The configuration is handled by [`ConfigHandler`][ConfigHandler]. It is decoupled from any user interface, so it serves the configuration for both the GUI and CLI. All configuration settings recognized by the config files are defined as getters in this class. There are also setters for each setting, named as per the usual convention. For example, the setting `savePath` has a getter named `savePath` and a setter named `setSavePath`. Before working on a new config setting for flameshot, please read [this FAQ entry][faq:add-config-setting]. ### Interesting notes - [`ConfigHandler`][ConfigHandler] is based on `QSettings` - The configuration uses the `ini` format - The configuration is automatically reloaded when the config file changes ## Conventions - Always use `&Class::signal` and `&Class::slot` instead of `SIGNAL(signal())` and `SLOT(slot())`. This usually provides better code introspection and makes refactoring easier and less error-prone. [Flameshot]: flameshot/classFlameshot [Flameshot::instance]: flameshot/classFlameshot#function-instance [Flameshot::start]: flameshot/classFlameshot#function-start [ConfigHandler]: flameshot/classConfigHandler [FlameshotDaemon]: flameshot/classFlameshotDaemon [FlameshotDaemon::start]: flameshot/classFlameshotDaemon#function-start [confighandler.h]: flameshot/confighandler_8h [confighandler.cpp]: flameshot/confighandler_8cpp [faq:add-config-setting]: faq/#how-do-i-add-a-new-config-setting [matrix-room]: https://matrix.to/#/#flameshot-org:matrix.org --- ## File: docs/RFC/0000-Add-Opacity-slider.md # Add an opacity slider to the Tool Settings ### To be Reviewed By * borgmanJeremy * mmahmoudian * Flameshot developers ### Authors * Pr. Sunflower ### Status: Draft ~~| Discussion | Active | Dropped | Superseded~~ [Pr. Sunflower] This is the first time the authors are redacting a document of this sort and they kindly request to double-check their writings and to assist them in missing parts. ### Superseded by N/A ### Related * Issue #249 * Issue #1085 ## Problem Currently the drawing and marking tools in Flameshot only have one, non-customisable opacity setting. This current setting is bad for highlighting text because the Marker tool looks very pale. To compensate the user often has to highlight multiple times which is not convenient and time-consuming. Here is a comparison of Flameshot's Marker tool with Microsoft's **Snip & Sketch** Highlighter tool: ### Black text on light background **Flameshot:** **Snip & Sketch:** ### White text on dark background **Flameshot:** **Snip & Sketch:** ## Anti-Goals Flameshot's Marker tool does a very good job at keeping the text readable so this is not linked to this request. ## Solution **Add a way to control opacity, like an opacity slider in the Tool Settings.** Add an opacity slider under "Active thickness". ## Performance Impact [Pr. Sunflower:] *I need help for this part.* Do you anticipate the proposed changes to impact performance in any way? Are there plans to measure and/or mitigate the impact? ## Backwards Compatibility and Upgrade Path [Pr. Sunflower:] *I need help for this part.* Will the regular rolling upgrade process work with these changes? How do the proposed changes impact backwards-compatibility? Are message or file formats changing? Is there a need for a deprecation process to provide an upgrade path to users who will need to adjust their applications? ## Prior Art [Pr. Sunflower:] *I don't think this part is useful.* What would be the alternatives to the proposed solution? What would happen if we don’t solve the problem? Why should this proposal be preferred? ## FAQ [Pr. Sunflower:] *I need help for this part.* Answers to questions you’ve commonly been asked after requesting comments for this proposal. ## Errata [Pr. Sunflower:] *I need help for this part.* What are minor adjustments that had to be made to the proposal since it was approved? --- ## File: docs/CONTRIBUTING.md # Contributing Contributions are welcome! Here's how you can help: - [Translating](#translations) - [Contributing code](#code) - [Reporting issues](#issues) - [Donating](#donations) ## Translations See [translation instructions](https://github.com/flameshot-org/translation-instruction). ## Code For small fixes or incremental improvements simply fork the repo and follow the process below. For larger changes submit an [RFC:](RFC.md) 1. [Fork](https://help.github.com/articles/fork-a-repo/) the repository and [clone](https://help.github.com/articles/cloning-a-repository/) your fork. 2. Start coding! - Implement your feature. - Check your code works as expected. - Run the code formatter: `clang-format -i $(git ls-files "*.cpp" "*.h")` 3. Commit your changes to a new branch (not `master`, one change per branch) and push it: - Commit messages should: - Header line: explain the commit in one line (use the imperative) - Be descriptive. - Have a first line with less than *80 characters* and have a second line that is *empty* if you want to add a description. 4. Once you are happy with your changes, submit a pull request. - Open the pull-request. - Add a short description explaining briefly what you've done (or if it's a work-in-progress - what you need to do) ## Issues 1. Do a quick search on GitHub to check if the issue has already been reported. 2. [Open an issue](https://github.com/flameshot-org/flameshot/issues/new) and describe the issue you are having - you could include: - Screenshots - Ways to reproduce the issue. - Your Flameshot version. - Your platform (e.g. Windows 10 or Ubuntu 15.04 x64) After reporting you should aim to answer questions or clarifications as this helps pinpoint the cause of the issue. ## Donations Please refer to [the donation page on website]() for details, but as a brief recap, Flameshot does **not** accept financial donations, but we encourage you to put code bounty on the platform of your choice on the issues you like to be addressed. --- ## File: docs/ReleaseNote_12.1.md ## V12.1.0 This is a minor release that fixed some bugs introduced in the v12 release. ## What's Changed * Fix typos by @luzpaz in https://github.com/flameshot-org/flameshot/pull/2705 * rename Imgur API Key to Imgur Application Client ID by @thehunmonkgroup in https://github.com/flameshot-org/flameshot/pull/2719 * fix issue about externalWidget launchapp by @Alaskra in https://github.com/flameshot-org/flameshot/pull/2698 * Fix size not appearing on size tool when started from launcher by @borgmanJeremy in https://github.com/flameshot-org/flameshot/pull/2734 * Added option to pin menu to close pin by @borgmanJeremy in https://github.com/flameshot-org/flameshot/pull/2736 * disable option to launch on start by default by @borgmanJeremy in https://github.com/flameshot-org/flameshot/pull/2735 * Fix magnify windows by @borgmanJeremy in https://github.com/flameshot-org/flameshot/pull/2746 * DesktopFileParser only reads .desktop files @wd5gnr https://github.com/flameshot-org/flameshot/pull/2742 ## New Contributors * @cliffcoffee made their first contribution in https://github.com/flameshot-org/flameshot/pull/2726 * @thehunmonkgroup made their first contribution in https://github.com/flameshot-org/flameshot/pull/2719 * @wd5gnr made their first contribution in https://github.com/flameshot-org/flameshot/pull/2742 **Full Changelog**: https://github.com/flameshot-org/flameshot/compare/v12.0.0...v12.1.0 ## 2. Official Technical Reference & Guides (flameshot-org/flameshot-org.github.io) [](https://github.com/flameshot-org/flameshot/blob/master/LICENSE) [](https://github.com/flameshot-org/flameshot/releases) # [Flameshot.org](https://flameshot.org) > Powerful yet simple to use screenshot software. This is the repository of [flameshot.org](https://flameshot.org). For the software code, you should go to [the main repository](https://github.com/flameshot-org/flameshot/). This static website is powered by [zola](https://www.getzola.org). # Development ## building the website locally It is essential that you build the website locally on your computer (it would take about 1 second) to check if the changes you have made are correctly getting converted to HTML. Typically typos can mess things up. To build the website, you first need to install [zola](https://www.getzola.org/) (zola v0.22.1) (the static website generator that we use for this website), and then follow these steps: - Navigate to the root directory of the cloned repository - Run `zola serve` to start a local server for development - look for possible errors or messages - Open `127.0.0.1:1111` in your browser to see the website The browser will automatically refresh on any changes made. Sass is setup to auto compile when the scss is edited. ## Convention Please follow these conventions while trying to contribute (click on each item to open the details):
  1. Code blocks Please make sure to define the language in the markdown: ´´´sh some commands here ```
  2. Images of pages in `/content/docs/` - Image related to each markdown file goes into the dedicated folder for that markdown file. For instance the images of file `/content/docs/guide/wayland-help.md` goes into the folder `/static/media/content/docs/guide/wayland-help/`. - Please make sure there is no copy-righted content in the image - Please make sure the size is not too wide or too long - For creating arrows and markings, please use the `#fa0164` color - Please consider adding the caption/alt-text (it goes between double quotes after the address of the image path. Check the example below) Example of a good practice: ```md ```
  3. Referencing Flameshot buttons The convention is to have the name of the button first (you can run Flameshot and use your mouse to hover over the button and see what it's name is), and then the icon. For the icon you can find the button you want in: and then replace the filename with the `XXXX` in the following line: ```html ```
  4. Spelling Although we are not very strict, but the preferred spelling is the American spelling of the words (e.g "analyze" instead of "analyse"). When in doubt, please check the word in the [Merriam-Webster](https://www.merriam-webster.com) dictionary. Again, don't sweat about it, but it is good to be consistent.
  5. Body text - Although not very strict, it is preferred to have one sentence per line (this can be avoided in lists as it can break the continuity in Markdown lists - The paragraphs should be separated by one empty line, and sections and headings by two empty lines - try avoiding complicated words, but if you want to use one, please consider linking it to it's definition in [Wordnik](https://www.wordnik.com) or [Merriam-Webster](https://www.merriam-webster.com).