philipp/KDDockWidgets
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Markdownlint the project

Browse Source
This commit is contained in:
Allen Winter
2022-07-12 11:12:33 -04:00
parent fedce40883
commit b52b1335a6
8 changed files with 130 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.mdlrc Normal file
View File

@@ -0,0 +1 @@
style ".mdlrc.rb"

4
.mdlrc.rb Normal file
View File

@@ -0,0 +1,4 @@
all
rule 'MD013', :line_length => 100, :tables => false
rule 'MD029', :style => :ordered
exclude_rule 'MD033'

7
.pre-commit-config.yaml
View File

@@ -38,3 +38,10 @@ repos:
exclude: (.py.cmake|Doxyfile.cmake) exclude: (.py.cmake|Doxyfile.cmake)
- id: cmake-format - id: cmake-format
exclude: (.py.cmake|Doxyfile.cmake) exclude: (.py.cmake|Doxyfile.cmake)
- repo: https://github.com/markdownlint/markdownlint
rev: v0.11.0
hooks:
- id: markdownlint
entry: mdl
language: ruby
files: \.(md|mdown|markdown)$

10
README-QtQuick.md
View File

@@ -1,15 +1,13 @@
Supported Qt versions and toolchains # KDDockWidgets and QtQuick
=====================================
## Supported Qt versions and toolchains
KDDockWidgets for QtQuick requires a C++17 capable compiler and Qt >= 6.2.1. KDDockWidgets for QtQuick requires a C++17 capable compiler and Qt >= 6.2.1.
Qt 5.15.2 will probably also work, but it's not built and tested by KDAB CI, we Qt 5.15.2 will probably also work, but it's not built and tested by KDAB CI, we
advise users to move to Qt6 as soon as possible. advise users to move to Qt6 as soon as possible.
## Troubleshooting
TROUBLESHOOTING
===============
- QtGraphicalEffects is not supported, as it's buggy when moving between different QWindows. - QtGraphicalEffects is not supported, as it's buggy when moving between different QWindows.
See for example QTBUG-94943, KDDockWidgets issue #213. Also search the Qt bug tracker See for example QTBUG-94943, KDDockWidgets issue #213. Also search the Qt bug tracker

43
README-WASM.md
View File

@@ -1,33 +1,40 @@
WebAssembly # KDDockWidgets with WebAssembly
===========
KDDockWidgets works with WebAssembly with the following known limitations: KDDockWidgets works with WebAssembly with the following known limitations:
- Classic drop indicators are not supported, only the segmented ones. This is because - Classic drop indicators are not supported, only the segmented ones. This is because
WASM doesn't support windows with translucency. WASM doesn't support windows with translucency.
- Might be slow on Linux, depending on your browser, while dragging or resizing windows. - Might be slow on Linux, depending on your browser, while dragging or resizing windows.
Please file a bug with Qt, as it's out of scope for KDDW to fix. Please file a bug with Qt, as it's out of scope for KDDW to fix.
Demo: ## Demo
=====
A demo is available at https://demos.kdab.com/wasm/kddockwidgets/dockwidgets.html A demo is available at <https://demos.kdab.com/wasm/kddockwidgets/dockwidgets.html>.
Build tips for KDDW: ## Build tips for KDDW
====================
- Visit <https://doc.qt.io/qt-5/wasm.html> if you haven't yet
- Visit https://doc.qt.io/qt-5/wasm.html if you haven't yet
- Open a terminal suitable for WASM development (with the correct Qt and toolchain in PATH, etc) - Open a terminal suitable for WASM development (with the correct Qt and toolchain in PATH, etc)
- KDDockWidgets can be built with `cmake -DCMAKE_TOOLCHAIN_FILE=/usr/local/emsdk-1.39.8/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -DCMAKE_FIND_ROOT_PATH=~/Qt/5.15.1/wasm_32/ -DKDDockWidgets_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release`
(Adapt the paths to your own situation)
Builds tips for your own app: - KDDockWidgets can be built with:
=============================
```bash
cmake \
-DCMAKE_TOOLCHAIN_FILE=/usr/local/emsdk-1.39.8/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake
-DCMAKE_FIND_ROOT_PATH=~/Qt/5.15.1/wasm_32/ -DKDDockWidgets_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release`
(Adapt the paths to your own situation)
```
## Builds tips for your own app ==
- Link to KDDW (libkddockwidgets.a, or similar) - Link to KDDW (libkddockwidgets.a, or similar)
- As the build is static, don't forget to initialize KDDW's resources: - As the build is static, don't forget to initialize KDDW's resources:
```
#ifdef QT_STATIC ```cpp
Q_INIT_RESOURCE(kddockwidgets_resources); #ifdef QT_STATIC
#endif Q_INIT_RESOURCE(kddockwidgets_resources);
#endif
``` ```

8
README-Wayland.md
View File

@@ -1,13 +1,13 @@
# KDDockWidgets and Wayland
Wayland support is done and has been tested on KDE (Kwin) and weston. Wayland support is done and has been tested on KDE (Kwin) and weston.
Limitations ## Limitations
============
Wayland works very differently than traditional desktops and imposes us some, Wayland works very differently than traditional desktops and imposes us some,
limitations. Here's a list of different behaviours which KDDockWidgets will have limitations. Here's a list of different behaviours which KDDockWidgets will have
when running on Wayland: when running on Wayland:
- A title bar can either be used for drag&dock or for moving the window around. - A title bar can either be used for drag&dock or for moving the window around.
- For this reason, floating windows now have two title bars. - For this reason, floating windows now have two title bars.
@@ -28,7 +28,5 @@ when running on Wayland:
- Kwin specific: - Kwin specific:
- The pixmap that's shown during a drag can't be bigger than 250x250. Might be a bug. - The pixmap that's shown during a drag can't be bigger than 250x250. Might be a bug.
All in all it's pretty decent and usable. Any further improvements should be done at the server or All in all it's pretty decent and usable. Any further improvements should be done at the server or
protocol level now. protocol level now.

63
README-bindings.md
View File

@@ -1,26 +1,29 @@
# KDDockWidgets and Python bindings
These are the instructions for building the Python bindings for KDDockWidgets. These are the instructions for building the Python bindings for KDDockWidgets.
Make sure you have PySide2, shiboken2 and shiboken2-generator installed. Make sure you have PySide2, shiboken2 and shiboken2-generator installed.
As this time, you cannot get shiboken2-generator because the wheels are not on PyPi. As this time, you cannot get shiboken2-generator because the wheels are not on PyPi.
To use the wheels do this: To use the wheels do this:
``` ```bash
% pip3 install \ % pip3 install \
--index-url=http://download.qt.io/official_releases/QtForPython/ \ --index-url=http://download.qt.io/official_releases/QtForPython/ \
--trusted-host download.qt.io \ --trusted-host download.qt.io \
shiboken2 pyside2 shiboken2_generator shiboken2 pyside2 shiboken2_generator
``` ```
For more info visit https://doc.qt.io/qtforpython/shiboken2/gettingstarted.html For more info visit <https://doc.qt.io/qtforpython/shiboken2/gettingstarted.html>.
afterwards run 'pip3 list | grep PySide2' afterwards run 'pip3 list | grep PySide2'
Note the version *must* match the same Qt you intend to use when building KDDockWidgets. Note the version *must* match the same Qt you intend to use when building KDDockWidgets.
Not supported: Not supported:
- Debug builds
- static builds - debug builds
- python2 bindings - static builds
- only some 32-bit platforms are supported. see https://wiki.qt.io/Qt_for_Python - python2 bindings
- only some 32-bit platforms are supported (see <https://wiki.qt.io/Qt_for_Python>)
Tell CMake to build the bindings by passing the `-DKDDockWidgets_PYTHON_BINDINGS=True' option, Tell CMake to build the bindings by passing the `-DKDDockWidgets_PYTHON_BINDINGS=True' option,
followed by the make command. followed by the make command.
@@ -33,42 +36,42 @@ to CMake (adjust to the python path on your system).
To run the KDDW python example To run the KDDW python example
``` ```bash
$ export PYTHONPATH=/kddw/install/path # Only if needed export PYTHONPATH=/kddw/install/path # Only if needed
$ cd python/examples/ cd python/examples/
$ rcc -g python -o rc_assets.py ../../examples/dockwidgets/resources_example.qrc rcc -g python -o rc_assets.py ../../examples/dockwidgets/resources_example.qrc
$ python3 main.py python3 main.py
``` ```
Build Issues Build Issues
* If you see errors like "Unable to locate Clang's built-in include directory" - If you see errors like "Unable to locate Clang's built-in include directory"
then first make sure you have llvm installed. If you still have problems try then first mROUBLESHOOTINGake sure you have llvm installed. If you still have problems try
setting the environment variable `LLVM_INSTALL_DIR` to point to your llvm installation. setting the environment variable `LLVM_INSTALL_DIR` to point to your llvm installation.
Examples: Examples:
``` ```bash
export LLVM_INSTALL_DIR=/usr/local/opt/llvm-11 export LLVM_INSTALL_DIR=/usr/local/opt/llvm-11
set "LLVM_INSTALL_DIR=C:\Program Files\LLVM" #Windows set "LLVM_INSTALL_DIR=C:\Program Files\LLVM" #Windows
``` ```
* When building the examples you may encounter errors loading shared libraries from shiboken2_generator. - When building the examples you may encounter errors loading shared libraries from shiboken2_generator.
Try: Try:
``` ```bash
export LD_LIBRARY_PATH=/usr/local/lib/python/dist-packages/PySide2/Qt/lib #linux export LD_LIBRARY_PATH=/usr/local/lib/python/dist-packages/PySide2/Qt/lib #linux
export DYLD_LIBRARY_PATH=/usr/local/lib/python/dist-packages/PySide2/Qt/lib #Mac export DYLD_LIBRARY_PATH=/usr/local/lib/python/dist-packages/PySide2/Qt/lib #Mac
#adjust to wherever your PySide is installed (Adjust to wherever your PySide is installed)
``` ```
* On Windows the `libclang.dll` that ship with QtForPython is not compatible with MSVC2019. - On Windows the `libclang.dll` that ship with QtForPython is not compatible with MSVC2019.
To fix this, copy the `libclang.dll` that comes with llvm into shiboken2, like so: To fix this, copy the `libclang.dll` that comes with llvm into shiboken2, like so:
``` ```bash
cd C:\Python37\Lib\site-packages\shiboken2_generator cd C:\Python37\Lib\site-packages\shiboken2_generator
copy libclang.dll libclang.dll.save copy libclang.dll libclang.dll.save
copy "C:\Program Files\llvm\bin\libclang.dll" libclang.dll copy "C:\Program Files\llvm\bin\libclang.dll" libclang.dll
#Python3 installation in C:\Python37 and llvm in c:\Program Files\llvm. adjust as needed (Python3 installation in C:\Python37 and llvm in c:\Program Files\llvm. adjust as needed)
``` ```

121
README.md
View File

@@ -1,7 +1,7 @@
# KDDockWidgets
[![Build Status](https://travis-ci.com/KDAB/KDDockWidgets.svg?branch=master)](https://travis-ci.com/KDAB/KDDockWidgets) [![Build Status](https://travis-ci.com/KDAB/KDDockWidgets.svg?branch=master)](https://travis-ci.com/KDAB/KDDockWidgets)
KDDockWidgets
=============
`KDDockWidgets` is a Qt dock widget library written by KDAB, suitable for replacing `KDDockWidgets` is a Qt dock widget library written by KDAB, suitable for replacing
`QDockWidget` and implementing advanced functionalities missing in Qt. `QDockWidget` and implementing advanced functionalities missing in Qt.
@@ -9,9 +9,8 @@ Although `KDDockWidgets` is ready to be used out of the box, it can also be seen
as a framework to allow building very tailored custom docking systems. It tries as a framework to allow building very tailored custom docking systems. It tries
to expose every internal widget and every knob for the app developer to tune. to expose every internal widget and every knob for the app developer to tune.
## Motivation
Motivation
==========
Throughout the years KDAB contributed and funded bug fixes and features to `QDockWidget`. Throughout the years KDAB contributed and funded bug fixes and features to `QDockWidget`.
Sadly, this was very painful. Each bug fix or feature took many days of implementation, Sadly, this was very painful. Each bug fix or feature took many days of implementation,
and an equal number of days just to fix dozens of regressions. and an equal number of days just to fix dozens of regressions.
@@ -22,15 +21,15 @@ creative with their requests, so it was clear we needed a better docking framewo
You will find more information in these places: You will find more information in these places:
* [our official home page](https://www.kdab.com/development-resources/qt-tools/kddockwidgets) - [our official home page](https://www.kdab.com/development-resources/qt-tools/kddockwidgets)
* [online detailed browsable API reference](https://docs.kdab.com/kddockwidgets) - [online detailed browsable API reference](https://docs.kdab.com/kddockwidgets)
* [our example programs](examples/) - [our example programs](examples/)
We also have an [in browser demo](https://demos.kdab.com/wasm/kddockwidgets/dockwidgets.html). Note We also have an [in browser demo](https://demos.kdab.com/wasm/kddockwidgets/dockwidgets.html). Note
however that this demo isn't fully featured, as it's running on Qt for WebAssembly. however that this demo isn't fully featured, as it's running on Qt for WebAssembly.
Features ## Features
========
- Provide advanced docking that QDockWidget doesn't support - Provide advanced docking that QDockWidget doesn't support
- Native window resize on Windows (allowing for Aero-snap even with custom title bar decorations) - Native window resize on Windows (allowing for Aero-snap even with custom title bar decorations)
- Arrow drop indicators for great drop precision - Arrow drop indicators for great drop precision
@@ -66,49 +65,45 @@ Features
- Optional minimize and maximize button on the title bar - Optional minimize and maximize button on the title bar
- FloatingWindows can be utility windows or full native - FloatingWindows can be utility windows or full native
Screen capture ## Screen capture
==============
![Screen capture](./screencap.gif?raw=true "The docking system in action") ![Screen capture](./screencap.gif?raw=true "The docking system in action")
## Building and requirements
Building and requirements
=========================
To build KDDockWidgets you'll need: To build KDDockWidgets you'll need:
- CMake - CMake
- Qt 5.15.x or Qt6 >= 6.2 - Qt 5.15.x or Qt6 >= 6.2
- Ninja (Other generators might work but are untested) - Ninja (Other generators might work but are untested)
- C++17 capable compiler - C++17 capable compiler
- Qt Widgets module - Qt Widgets module
- Qt X11Extras module if on Linux/X11 - Qt X11Extras module if on Linux/X11
- Qt Quick and QuickControls2 modules if using the QtQuick support - Qt Quick and QuickControls2 modules if using the QtQuick support
- Qt private development headers, for instance, for Qt5: - Qt private development headers, for instance, for Qt5:
- SUSE: libqt5-qtbase-private-headers-devel - SUSE: libqt5-qtbase-private-headers-devel
- Ubuntu, debian-based: qtbase5-private-dev - Ubuntu, debian-based: qtbase5-private-dev
- Fedora, redhat-based: qt5-qtbase-private-devel - Fedora, redhat-based: qt5-qtbase-private-devel
- others: consult your distro - others: consult your distro
Open a terminal capable of building Qt applications. Open a terminal capable of building Qt applications.
Make sure you have cmake, ninja, compiler, Qt, etc in PATH. Make sure you have cmake, ninja, compiler, Qt, etc in PATH.
Adapt the instructions to suit your cmake generator and operating system. Adapt the instructions to suit your cmake generator and operating system.
``` ```bash
$ cmake -G Ninja -DCMAKE_INSTALL_PREFIX=/path/where/to/install ../path/to/kddockwidgets cmake -G Ninja -DCMAKE_INSTALL_PREFIX=/path/where/to/install ../path/to/kddockwidgets
$ cmake --build . cmake --build .
$ cmake --build . --target install cmake --build . --target install
``` ```
The installation directory defaults to `c:\KDAB\KDDockWidgets-<version>` on Windows The installation directory defaults to `c:\KDAB\KDDockWidgets-<version>` on Windows
and `/usr/local/KDAB/KDDockWidgets-<version>` on non-Windows. and `/usr/local/KDAB/KDDockWidgets-<version>` on non-Windows.
You can change the installation location by passing the option `-DCMAKE_INSTALL_PREFIX=/install/path` to cmake. Change the installation location by passing the option `-DCMAKE_INSTALL_PREFIX=/install/path` to CMake.
## Trying out the examples
Trying out the examples
=======================
A full demo that showcases most of the features lives in [examples/dockwidgets](examples/dockwidgets). A full demo that showcases most of the features lives in [examples/dockwidgets](examples/dockwidgets).
A simpler example can be found in [examples/minimal](examples/minimal), A simpler example can be found in [examples/minimal](examples/minimal),
@@ -116,25 +111,24 @@ which might be more indicated to learn the API, as it's less overwhelming than t
To build and run the example: To build and run the example:
``` ```bash
$ cd path/to/kddockwidgets/examples/dockwidgets/ cd path/to/kddockwidgets/examples/dockwidgets/
$ cmake -G Ninja -DCMAKE_PREFIX_PATH=/path/where/kddw/is/installed cmake -G Ninja -DCMAKE_PREFIX_PATH=/path/where/kddw/is/installed
$ cmake --build . cmake --build .
$ ./kddockwidgets_example ./kddockwidgets_example
``` ```
## Using
Using
=====
From your CMake Qt5 project, add From your CMake Qt5 project, add
``` ```cmake
find_package(KDDockWidgets CONFIG) find_package(KDDockWidgets CONFIG)
``` ```
or for Qt6 or for Qt6
``` ```cmake
find_package(KDDockWidgets-qt6 CONFIG) find_package(KDDockWidgets-qt6 CONFIG)
``` ```
@@ -144,13 +138,11 @@ That's all you need to do (the imported target also brings in the include direct
You may also need to modify the `CMAKE_PREFIX_PATH` environment variable depending You may also need to modify the `CMAKE_PREFIX_PATH` environment variable depending
on where you installed KDDockWidgets. on where you installed KDDockWidgets.
## Python Bindings
Python Bindings
================
Please refer to [README-bindings.md](README-bindings.md). Please refer to [README-bindings.md](README-bindings.md).
Versioning ## Versioning
==========
New features go to master while the stable branch only accepts non-intrusive bug fixes. New features go to master while the stable branch only accepts non-intrusive bug fixes.
@@ -164,9 +156,7 @@ not so they can change internal business logic.
We don't promise or test binary compatibility. It's advised that you recompile We don't promise or test binary compatibility. It's advised that you recompile
your application whenever updating KDDW. your application whenever updating KDDW.
## Styling
Styling
========
Almost all private widgets used by KDDW can be derived by the user to give them Almost all private widgets used by KDDW can be derived by the user to give them
a custom look. That's done by providing your own FrameworkWidgetFactory. Run a custom look. That's done by providing your own FrameworkWidgetFactory. Run
@@ -180,29 +170,24 @@ Warning: When using private headers, be sure to rebuild your application wheneve
update to a new KDDW version. Binary compatibility is only kept when using public update to a new KDDW version. Binary compatibility is only kept when using public
headers. headers.
## Licensing
Licensing
=========
KDDockWidgets is (C) 2019-2022, Klarälvdalens Datakonsult AB, and is licensed according to KDDockWidgets is (C) 2019-2022, Klarälvdalens Datakonsult AB, and is licensed according to
the terms of the [GPL 2.0](LICENSES/GPL-2.0-only.txt) or [GPL 3.0](LICENSES/GPL-3.0-only.txt). the terms of the [GPL 2.0](LICENSES/GPL-2.0-only.txt) or [GPL 3.0](LICENSES/GPL-3.0-only.txt).
Contact KDAB at <info@kdab.com> to inquire about commercial licensing. Contact KDAB at <info@kdab.com> to inquire about commercial licensing.
## Get Involved
Get Involved Please submit your issue reports to our GitHub space at <https://github.com/KDAB/KDDockWidgets>.
============
Please submit your issue reports to our GitHub space at
https://github.com/KDAB/KDDockWidgets
When reporting bugs please make it easy for the maintainer to reproduce it. Use `examples/minimal/`
When reporting bugs please make it easy for the maintainer to reproduce it. Use `examples/minimal/` or or `examples/dockwidgets/` for reproducing the problem. If you did modifications to the example
`examples/dockwidgets/` for reproducing the problem. If you did modifications to the example in order to in order to reproduce then please attach the *patch* and not a picture of your changes. You can
reproduce then please attach the *patch* and not a picture of your changes. You can get a patch by doing get a patch by doing `git diff > repro.diff` at the repo root.
`git diff > repro.diff` at the repo root.
Also state which KDDW sha1, branch or version you're using, and which operating system. Also state which KDDW sha1, branch or version you're using, and which operating system.
KDAB will happily accept external contributions; however, **all** contributions require a KDAB will happily accept external contributions; however, **all** contributions require a
signed [Copyright Assignment Agreement](docs/KDDockWidgets-CopyrightAssignmentForm.pdf). signed [Copyright Assignment Agreement](docs/KDDockWidgets-CopyrightAssignmentForm.pdf).
@@ -212,8 +197,8 @@ Contact info@kdab.com for more information.
Thanks to our [contributors](CONTRIBUTORS.txt). Thanks to our [contributors](CONTRIBUTORS.txt).
About KDAB ## About KDAB
==========
KDDockWidgets is supported and maintained by Klarälvdalens Datakonsult AB (KDAB). KDDockWidgets is supported and maintained by Klarälvdalens Datakonsult AB (KDAB).
The KDAB Group is the global No.1 software consultancy for Qt, C++ and The KDAB Group is the global No.1 software consultancy for Qt, C++ and
@@ -225,10 +210,10 @@ We continue to help develop parts of Qt and are one of the major contributors
to the Qt Project. We can give advanced or standard trainings anywhere to the Qt Project. We can give advanced or standard trainings anywhere
around the globe on Qt as well as C++, OpenGL, 3D and more. around the globe on Qt as well as C++, OpenGL, 3D and more.
Please visit https://www.kdab.com to meet the people who write code like this. Please visit <https://www.kdab.com> to meet the people who write code like this.
Stay up-to-date with KDAB product announcements: Stay up-to-date with KDAB product announcements:
* [KDAB Newsletter](https://news.kdab.com) - [KDAB Newsletter](https://news.kdab.com)
* [KDAB Blogs](https://www.kdab.com/category/blogs) - [KDAB Blogs](https://www.kdab.com/category/blogs)
* [KDAB on Twitter](https://twitter.com/KDABQt) - [KDAB on Twitter](https://twitter.com/KDABQt)