Integrate QT documentation into doxygen
This commit is contained in:
Tobias Taschner
@@ -296,6 +296,7 @@ INPUT = mainpages \
|
||||
../ios \
|
||||
../msw \
|
||||
../osx \
|
||||
../qt \
|
||||
../../interface
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS = *.h *.md
|
||||
|
||||
@@ -167,7 +167,9 @@ wxWindowBase::GetDefaultBorder(), returning wxBORDER_NONE.
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# wxQt Architecture
|
||||
# wxQt Architecture {#plat_qt_architecture}
|
||||
|
||||
## Internals
|
||||
|
||||
@@ -7,11 +7,11 @@ wxQT uses the same techniques like other ports to wrap the Qt toolkit classes in
|
||||
### 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'''.
|
||||
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.
|
||||
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).
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
* '''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.)
|
||||
|
||||
### 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.
|
||||
|
||||
'''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.
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
wxWidgets for Qt installation
|
||||
wxWidgets for Qt installation {#plat_qt_install}
|
||||
-----------------------------
|
||||
|
||||
[TOC]
|
||||
|
||||
IMPORTANT NOTE:
|
||||
|
||||
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
|
||||
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
|
||||
install instructions just do (in the base dir):
|
||||
|
||||
> mkdir buildqt
|
||||
> cd buildqt
|
||||
> ../configure --with-qt
|
||||
> make
|
||||
> su <type root password>
|
||||
> make install
|
||||
> ldconfig
|
||||
> mkdir buildqt
|
||||
> cd buildqt
|
||||
> ../configure --with-qt
|
||||
> make
|
||||
> su <type root password>
|
||||
> make install
|
||||
> 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
|
||||
@@ -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:
|
||||
|
||||
> su <type root password>
|
||||
> make uninstall
|
||||
> ldconfig
|
||||
> su <type root password>
|
||||
> make uninstall
|
||||
> ldconfig
|
||||
|
||||
* The simplest errors
|
||||
The simplest errors {#qt_error_simple}
|
||||
---------------------
|
||||
|
||||
For any configure errors: please look at config.log file which was generated
|
||||
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
|
||||
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,
|
||||
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
|
||||
variable contains the path to Qt libraries if they were installed in a
|
||||
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,
|
||||
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
|
||||
variable contains the path to Qt libraries if they were installed in a
|
||||
non-default location.
|
||||
|
||||
* The simplest program
|
||||
The simplest program {#qt_simple_app}
|
||||
----------------------
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
libgstreamer-plugins-base0.10-dev)
|
||||
|
||||
|
||||
Then create a build directory, configure and compile:
|
||||
|
||||
mkdir bldqt5
|
||||
cd bldqt5
|
||||
../configure --with-qt --enable-debug
|
||||
make
|
||||
make samples
|
||||
mkdir bldqt5
|
||||
cd bldqt5
|
||||
../configure --with-qt --enable-debug
|
||||
make
|
||||
make samples
|
||||
|
||||
If everything is ok, you can do the make install as specified before.
|
||||
|
||||
Optionally, you can build and run Unit Tests:
|
||||
|
||||
cd tests
|
||||
make
|
||||
./test_gui
|
||||
cd tests
|
||||
make
|
||||
./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.
|
||||
@@ -100,56 +106,59 @@ restriction as above).
|
||||
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.
|
||||
|
||||
# for Linux:
|
||||
../configure --with-qt --enable-debug QT5_CUSTOM_DIR=~/Qt/5.11.0/gcc_64
|
||||
for Linux:
|
||||
|
||||
# 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
|
||||
../configure --with-qt --enable-debug QT5_CUSTOM_DIR=~/Qt/5.11.0/gcc_64
|
||||
|
||||
* 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
|
||||
Development Kit (SDK), install them and perform the following instructions to
|
||||
prepare the cross-compilation tool-chain to (change NDK and other paths):
|
||||
|
||||
NDK=~/src/android-ndk-r9d
|
||||
SDK=~/src/android-sdk-linux
|
||||
export ANDROID_NDK_ROOT=$NDK
|
||||
$NDK/build/tools/make-standalone-toolchain.sh \
|
||||
--toolchain=arm-linux-androideabi-4.8 --platform=android-9 \
|
||||
--install-dir=/tmp/ndk
|
||||
NDK=~/src/android-ndk-r9d
|
||||
SDK=~/src/android-sdk-linux
|
||||
export ANDROID_NDK_ROOT=$NDK
|
||||
$NDK/build/tools/make-standalone-toolchain.sh \
|
||||
--toolchain=arm-linux-androideabi-4.8 --platform=android-9 \
|
||||
--install-dir=/tmp/ndk
|
||||
|
||||
export PATH=/tmp/ndk/bin:$PATH
|
||||
export CC=arm-linux-androideabi-gcc
|
||||
export CXX=arm-linux-androideabi-g++
|
||||
export PATH=/tmp/ndk/bin:$PATH
|
||||
export CC=arm-linux-androideabi-gcc
|
||||
export CXX=arm-linux-androideabi-g++
|
||||
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
cd ~/src/wxWidgets
|
||||
mkdir bldqt5droid
|
||||
cd bldqt5droid
|
||||
../configure --with-qt --enable-debug --build=x86_64-unknown-linux-gnu \
|
||||
--host=arm-linux-androideabi --disable-compat28 --disable-shared \
|
||||
--disable-arttango --enable-image --disable-dragimage --disable-sockets \
|
||||
--with-libtiff=no --without-opengl --disable-baseevtloop --disable-utf8
|
||||
make
|
||||
cd ~/src/wxWidgets
|
||||
mkdir bldqt5droid
|
||||
cd bldqt5droid
|
||||
../configure --with-qt --enable-debug --build=x86_64-unknown-linux-gnu \
|
||||
--host=arm-linux-androideabi --disable-compat28 --disable-shared \
|
||||
--disable-arttango --enable-image --disable-dragimage --disable-sockets \
|
||||
--with-libtiff=no --without-opengl --disable-baseevtloop --disable-utf8
|
||||
make
|
||||
|
||||
You can now compile and link your app against this build, and finally
|
||||
package it for Android using standard APK tools.
|
||||
|
||||
* Create your configuration
|
||||
Create your configuration {#qt_config}
|
||||
---------------------------
|
||||
|
||||
Usage:
|
||||
|
||||
./configure options
|
||||
|
||||
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
|
||||
and Motif) simultaneously.
|
||||
|
||||
* Feature Options
|
||||
Feature Options {#qt_feature_options}
|
||||
-----------------
|
||||
|
||||
When producing an executable that is linked statically with wxQt
|
||||
you'll be surprised at its immense size. This can sometimes be
|
||||
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
|
||||
of all configurable options.
|
||||
@@ -182,10 +191,3 @@ of all configurable options.
|
||||
Apart from disabling certain features you can very often "strip"
|
||||
the program of its debugging information resulting in a significant
|
||||
reduction in size.
|
||||
|
||||
----------------------
|
||||
|
||||
In the hope that it will be useful,
|
||||
|
||||
The wxWidgets Team
|
||||
|
||||
Reference in New Issue
Block a user