Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integrate QT documentation into doxygen

Browse Source
This commit is contained in:
Tobias Taschner
2018-10-03 19:16:39 +02:00
parent f8460059cd
commit 141b5bdf0f
4 changed files with 83 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/doxygen/Doxyfile
View File

@@ -296,6 +296,7 @@ INPUT = mainpages \
../ios \ ../ios \
../msw \ ../msw \
../osx \ ../osx \
../qt \
../../interface ../../interface
INPUT_ENCODING = UTF-8 INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.h *.md FILE_PATTERNS = *.h *.md

4
docs/doxygen/mainpages/platdetails.h
View File

@@ -167,7 +167,9 @@ wxWindowBase::GetDefaultBorder(), returning wxBORDER_NONE.
wxQt is a port of wxWidgets using Qt libraries. It requires Qt 5 or later. wxQt is a port of wxWidgets using Qt libraries. It requires Qt 5 or later.
For further information, please see the files in docs/qt in the distribution. @subpage plat_qt_install "Build Instructions"
@subpage plat_qt_architecture "Architecture Overview"
@section page_port_wxiOS wxiOS @section page_port_wxiOS wxiOS

18
docs/qt/architecture.md
View File

@@ -1,4 +1,4 @@
# wxQt Architecture # wxQt Architecture {#plat_qt_architecture}
## Internals ## Internals
@@ -7,11 +7,11 @@ wxQT uses the same techniques like other ports to wrap the Qt toolkit classes in
### Current (original) Approach ### Current (original) Approach
An '''internal pointer m_qtWindow''' in wxWindow holds the reference to the QWidget (or derived) counterpart, and is accesible through the virtual method '''GetHandle'''. An '''internal pointer m_qtWindow''' in wxWindow holds the reference to the QWidget (or derived) counterpart, and is accesible through the virtual method '''GetHandle'''.
This pointer and other window styles are set up in the '''PostCreation''' method that must be called by the derived classes (mostly controls) to initialize the widget correctly. This pointer and other window styles are set up in the '''PostCreation''' method that must be called by the derived classes (mostly controls) to initialize the widget correctly.
Not doing so will cause painting and deletion issues, as the base class will not know how to handle the Qt widget. Not doing so will cause painting and deletion issues, as the base class will not know how to handle the Qt widget.
wxControl even provides a protected method '''QtCreateControl''' that will do the common initialization (including post creation step, moving, sizing, etc., and calling the base to add the child to the parent). wxControl even provides a protected method '''QtCreateControl''' that will do the common initialization (including post creation step, moving, sizing, etc., and calling the base to add the child to the parent).
'''Warning:''' Take care of not calling any function that can raise an assertion before `PostCreation`, for example wxFAIL_MSG, as it will interrupt the normal initialization, hence the later cleanup will crash. '''Warning:''' Take care of not calling any function that can raise an assertion before `PostCreation`, for example wxFAIL_MSG, as it will interrupt the normal initialization, hence the later cleanup will crash.
For example, this issue was caused by WXValidateStyle in wxCheckBox::Create, that was "failing silently" in unit tests, and then raising segmentation faults when the object was later deleted (as Qt checkbox counterpart was never being deleted due the aborted initialization). For example, this issue was caused by WXValidateStyle in wxCheckBox::Create, that was "failing silently" in unit tests, and then raising segmentation faults when the object was later deleted (as Qt checkbox counterpart was never being deleted due the aborted initialization).
Many controls have also other pointers to allow to map different sub-widgets and other features. Many controls have also other pointers to allow to map different sub-widgets and other features.
@@ -28,9 +28,9 @@ Note that some special cases are '''not real windows''' like the `wxTabFrame` (A
### Scroll Areas ### Scroll Areas
In both approaches, special care should be taken with scrolling areas, as Qt manages this ones slightly different to wxWidgets. In both approaches, special care should be taken with scrolling areas, as Qt manages this ones slightly different to wxWidgets.
'''QtGetScrollBarsContainer''' should be reimplemented to return the QScrollArea widget or similar (where the scroll bars are places). '''QtGetScrollBarsContainer''' should be reimplemented to return the QScrollArea widget or similar (where the scroll bars are places).
That widget should implement a '''viewport()''' (Qt idiom to differentiate the draw-able area). That widget should implement a '''viewport()''' (Qt idiom to differentiate the draw-able area).
Attempts to paint directly to the scroll area itself will fail. Attempts to paint directly to the scroll area itself will fail.
This is already handled in the QtHandlePaintEvent wxWindowQt method. This is already handled in the QtHandlePaintEvent wxWindowQt method.
@@ -54,19 +54,19 @@ Qt objects needs to be sub-classed to '''re-implement events''' and '''connect s
The approach chosen was to use templates to help inherit QObject's (QWidget), providing a common base to handle events and signal infrastructure: The approach chosen was to use templates to help inherit QObject's (QWidget), providing a common base to handle events and signal infrastructure:
* '''wxQtSignalHandler< wxWindow >:''' allows emitting wx events for Qt events & signals. This should be used used for all QObjects derivatives that are not widgets, for example QAction (used for shortcut / accelerators). * '''wxQtSignalHandler< wxWindow >:''' allows emitting wx events for Qt events & signals. This should be used used for all QObjects derivatives that are not widgets, for example QAction (used for shortcut / accelerators).
* '''wxQtEventSignalHandler< QWidget, wxWindow >:''' derived from `wxQtSignalHandler`, also handles basic events (change, focus, mouse, keyboard, paint, close, etc.). This should be used for all QWidget derivatives (controls, top level windows, etc.) * '''wxQtEventSignalHandler< QWidget, wxWindow >:''' derived from `wxQtSignalHandler`, also handles basic events (change, focus, mouse, keyboard, paint, close, etc.). This should be used for all QWidget derivatives (controls, top level windows, etc.)
### Delete later ### Delete later
Both templates also have some safety checks to avoid invalid spurious access to deleted wx objects (using a special pointer to the wx instance stored in the Qt object, that is reseted to NULL when the wx counterpart is marked to deletion). Both templates also have some safety checks to avoid invalid spurious access to deleted wx objects (using a special pointer to the wx instance stored in the Qt object, that is reseted to NULL when the wx counterpart is marked to deletion).
This is due that in some situations, Qt object could still be referenced in the Qt event queue, so it cannot be removed immediately. This is due that in some situations, Qt object could still be referenced in the Qt event queue, so it cannot be removed immediately.
'''Important:''' Currently wxQT is using Qt's '''deleteLater''' method to avoid this kind of issues. '''Important:''' Currently wxQT is using Qt's '''deleteLater''' method to avoid this kind of issues.
Please, don't use delete directly except you're confident it will not cause faults or other issues. Please, don't use delete directly except you're confident it will not cause faults or other issues.
Note that no public wxWidget class should be derived directly from QWidget as they could have different lifespans and other implications to run time type systems (RTTI). Note that no public wxWidget class should be derived directly from QWidget as they could have different lifespans and other implications to run time type systems (RTTI).
Some QObjects are even owned by Qt (for example: menubar, statusbar) and some parents (ie. `QTabWidget`) cannot be deleted immediately in some circumstances (they would cause segmentation faults due spurious events / signals caused by the children destruction if not correctly handled as explained previously) Some QObjects are even owned by Qt (for example: menubar, statusbar) and some parents (ie. `QTabWidget`) cannot be deleted immediately in some circumstances (they would cause segmentation faults due spurious events / signals caused by the children destruction if not correctly handled as explained previously)
For more information about the deletion issues, see [deleteLater](https://github.com/reingart/wxWidgets/wiki/WxQtDeleteLaterNotes ) notes and [wx-dev thread](https://groups.google.com/d/msg/wx-dev/H0Xc9aQzaH4/crjFDPsEA0cJ) discussion. For more information about the deletion issues, see [deleteLater](https://github.com/reingart/wxWidgets/wiki/WxQtDeleteLaterNotes ) notes and [wx-dev thread](https://groups.google.com/d/msg/wx-dev/H0Xc9aQzaH4/crjFDPsEA0cJ) discussion.

138
docs/qt/install.txt → docs/qt/install.md
View File

@@ -1,6 +1,8 @@
wxWidgets for Qt installation wxWidgets for Qt installation {#plat_qt_install}
----------------------------- -----------------------------
[TOC]
IMPORTANT NOTE: IMPORTANT NOTE:
If you experience problems installing, please re-read these If you experience problems installing, please re-read these
@@ -13,19 +15,23 @@ IMPORTANT NOTE:
using (including the beta) and what compiler on what system. One using (including the beta) and what compiler on what system. One
example: wxQt 3.1.0, GCC 4.8.1, Ubuntu 14.04 example: wxQt 3.1.0, GCC 4.8.1, Ubuntu 14.04
* The simplest case Installation {#qt_install}
============
The simplest case {#qt_simple}
------------------- -------------------
If you compile wxWidgets on Linux for the first time and don't like to read If you compile wxWidgets on Linux for the first time and don't like to read
install instructions just do (in the base dir): install instructions just do (in the base dir):
> mkdir buildqt > mkdir buildqt
> cd buildqt > cd buildqt
> ../configure --with-qt > ../configure --with-qt
> make > make
> su <type root password> > su <type root password>
> make install > make install
> ldconfig > ldconfig
[if you get "ldconfig: command not found", try using "/sbin/ldconfig"] [if you get "ldconfig: command not found", try using "/sbin/ldconfig"]
If you don't do the 'make install' part, you can still use the libraries from If you don't do the 'make install' part, you can still use the libraries from
@@ -33,65 +39,65 @@ the buildgtk directory, but they may not be available to other users.
If you want to remove wxWidgets on Unix you can do this: If you want to remove wxWidgets on Unix you can do this:
> su <type root password> > su <type root password>
> make uninstall > make uninstall
> ldconfig > ldconfig
* The simplest errors The simplest errors {#qt_error_simple}
--------------------- ---------------------
For any configure errors: please look at config.log file which was generated For any configure errors: please look at config.log file which was generated
during configure run, it usually contains some useful information. during configure run, it usually contains some useful information.
configure reports, that you don't have Qt installed although you are very configure reports, that you don't have Qt installed although you are very
sure you have. Well, you have installed it, but you also have another sure you have. Well, you have installed it, but you also have another
version of the Qt installed, which you may need to remove. Or maybe you version of the Qt installed, which you may need to remove. Or maybe you
installed it in a non-default location and configure can't find it there, installed it in a non-default location and configure can't find it there,
so please check that your PATH variable includes the path to the correct so please check that your PATH variable includes the path to the correct
qtconfig/pkg-config. Also check that your LD_LIBRARY_PATH or equivalent qtconfig/pkg-config. Also check that your LD_LIBRARY_PATH or equivalent
variable contains the path to Qt libraries if they were installed in a variable contains the path to Qt libraries if they were installed in a
non-default location. non-default location.
* The simplest program The simplest program {#qt_simple_app}
---------------------- ----------------------
Now create your super-application myfoo.cpp and compile anywhere with Now create your super-application myfoo.cpp and compile anywhere with
g++ myfoo.cpp `wx-config --libs --cxxflags` -o myfoo g++ myfoo.cpp `wx-config --libs --cxxflags` -o myfoo
* GUI libraries GUI libraries {#qt_libs_ui}
--------------- ---------------
wxWidgets/Qt requires the Qt library to be installed on your system. It has wxWidgets/Qt requires the Qt library to be installed on your system. It has
to be a stable version, preferably Qt 5.2.1 or later. to be a stable version, preferably Qt 5.2.1 or later.
* Building wxQT on Ubuntu Building wxQT on Ubuntu {#qt_build_ubuntu}
------------------------- -------------------------
Install latest Qt5 packages (qt5-default). To build unit tests, libcppunit-dev Install latest Qt5 packages (qt5-default). To build unit tests, libcppunit-dev
is required. You will need to install other dependencies to compile wxWidgets is required. You will need to install other dependencies to compile wxWidgets
depending on the features you'll want to use (build-essential libjpeg-dev depending on the features you'll want to use (build-essential libjpeg-dev
libtiff5-dev ubuntu-restricted-extras freeglut3 freeglut3-dev libsdl1.2-dev libtiff5-dev ubuntu-restricted-extras freeglut3 freeglut3-dev libsdl1.2-dev
libgstreamer-plugins-base0.10-dev) libgstreamer-plugins-base0.10-dev)
Then create a build directory, configure and compile: Then create a build directory, configure and compile:
mkdir bldqt5 mkdir bldqt5
cd bldqt5 cd bldqt5
../configure --with-qt --enable-debug ../configure --with-qt --enable-debug
make make
make samples make samples
If everything is ok, you can do the make install as specified before. If everything is ok, you can do the make install as specified before.
Optionally, you can build and run Unit Tests: Optionally, you can build and run Unit Tests:
cd tests cd tests
make make
./test_gui ./test_gui
* Building wxQT, using qt-unified-XXX-online installer Building wxQT, using qt-unified-XXX-online installer {#qt_build}
------------------------------------------------------ ------------------------------------------------------
Download qt-unified-XXX-online installer from the qt website. Download qt-unified-XXX-online installer from the qt website.
@@ -100,56 +106,59 @@ restriction as above).
The same build instructions apply, except that you need to explicitly pass The same build instructions apply, except that you need to explicitly pass
to configure the Qt dir of the build intended to use as QT5_CUSTOM_DIR, i.e. to configure the Qt dir of the build intended to use as QT5_CUSTOM_DIR, i.e.
# for Linux: for Linux:
../configure --with-qt --enable-debug QT5_CUSTOM_DIR=~/Qt/5.11.0/gcc_64
# for Windows (ran from Git Bash, or any other Unix-like shell): ../configure --with-qt --enable-debug QT5_CUSTOM_DIR=~/Qt/5.11.0/gcc_64
# (the syntax for the drive in the path is required by ar and ld)
../configure --with-qt --enable-debug QT5_CUSTOM_DIR=c:/Qt/5.11.0/mingw53_32
* Building wxGT on Android for Windows (ran from Git Bash, or any other Unix-like shell):
(the syntax for the drive in the path is required by ar and ld)
../configure --with-qt --enable-debug QT5_CUSTOM_DIR=c:/Qt/5.11.0/mingw53_32
Building wxGT on Android {#qt_android}
-------------------------- --------------------------
Download Android Native Development Kit (NDK), tandalone Android Software Download Android Native Development Kit (NDK), tandalone Android Software
Development Kit (SDK), install them and perform the following instructions to Development Kit (SDK), install them and perform the following instructions to
prepare the cross-compilation tool-chain to (change NDK and other paths): prepare the cross-compilation tool-chain to (change NDK and other paths):
NDK=~/src/android-ndk-r9d NDK=~/src/android-ndk-r9d
SDK=~/src/android-sdk-linux SDK=~/src/android-sdk-linux
export ANDROID_NDK_ROOT=$NDK export ANDROID_NDK_ROOT=$NDK
$NDK/build/tools/make-standalone-toolchain.sh \ $NDK/build/tools/make-standalone-toolchain.sh \
--toolchain=arm-linux-androideabi-4.8 --platform=android-9 \ --toolchain=arm-linux-androideabi-4.8 --platform=android-9 \
--install-dir=/tmp/ndk --install-dir=/tmp/ndk
export PATH=/tmp/ndk/bin:$PATH export PATH=/tmp/ndk/bin:$PATH
export CC=arm-linux-androideabi-gcc export CC=arm-linux-androideabi-gcc
export CXX=arm-linux-androideabi-g++ export CXX=arm-linux-androideabi-g++
Also, you'll need to download the Qt library bundle that matches your operating Also, you'll need to download the Qt library bundle that matches your operating
system installed package (5.2.1 in this case installed in ~/src/qt, you'll need system installed package (5.2.1 in this case installed in ~/src/qt, you'll need
the android_armv5/ android_armv7/ android_x86/ pre-compiled folders to the android_armv5/ android_armv7/ android_x86/ pre-compiled folders to
cross-compile for that architectures) cross-compile for that architectures)
Then, create a build directory (under the wxWidgets folder), configure for Then, create a build directory (under the wxWidgets folder), configure for
Andrid (disable currently unsupported/uneeded features) and run make: Andrid (disable currently unsupported/uneeded features) and run make:
cd ~/src/wxWidgets cd ~/src/wxWidgets
mkdir bldqt5droid mkdir bldqt5droid
cd bldqt5droid cd bldqt5droid
../configure --with-qt --enable-debug --build=x86_64-unknown-linux-gnu \ ../configure --with-qt --enable-debug --build=x86_64-unknown-linux-gnu \
--host=arm-linux-androideabi --disable-compat28 --disable-shared \ --host=arm-linux-androideabi --disable-compat28 --disable-shared \
--disable-arttango --enable-image --disable-dragimage --disable-sockets \ --disable-arttango --enable-image --disable-dragimage --disable-sockets \
--with-libtiff=no --without-opengl --disable-baseevtloop --disable-utf8 --with-libtiff=no --without-opengl --disable-baseevtloop --disable-utf8
make make
You can now compile and link your app against this build, and finally You can now compile and link your app against this build, and finally
package it for Android using standard APK tools. package it for Android using standard APK tools.
* Create your configuration Create your configuration {#qt_config}
--------------------------- ---------------------------
Usage: Usage:
./configure options ./configure options
If you want to use system's C and C++ compiler, If you want to use system's C and C++ compiler,
@@ -168,13 +177,13 @@ subdirectory of your wxWidgets installation) as this allows you to
have multiple configurations (for example, debug and release or GTK have multiple configurations (for example, debug and release or GTK
and Motif) simultaneously. and Motif) simultaneously.
* Feature Options Feature Options {#qt_feature_options}
----------------- -----------------
When producing an executable that is linked statically with wxQt When producing an executable that is linked statically with wxQt
you'll be surprised at its immense size. This can sometimes be you'll be surprised at its immense size. This can sometimes be
drastically reduced by removing features from wxWidgets that drastically reduced by removing features from wxWidgets that
are not used in your program. are not used in your program.
Please see the output of "./configure --help" for comprehensive list Please see the output of "./configure --help" for comprehensive list
of all configurable options. of all configurable options.
@@ -182,10 +191,3 @@ of all configurable options.
Apart from disabling certain features you can very often "strip" Apart from disabling certain features you can very often "strip"
the program of its debugging information resulting in a significant the program of its debugging information resulting in a significant
reduction in size. reduction in size.
----------------------
In the hope that it will be useful,
The wxWidgets Team