diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 56e567fd2e..79e80eb90d 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -296,6 +296,7 @@ INPUT = mainpages \ ../ios \ ../msw \ ../osx \ + ../qt \ ../../interface INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.h *.md diff --git a/docs/doxygen/mainpages/platdetails.h b/docs/doxygen/mainpages/platdetails.h index 8d0a799201..4826fd1ce9 100644 --- a/docs/doxygen/mainpages/platdetails.h +++ b/docs/doxygen/mainpages/platdetails.h @@ -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 diff --git a/docs/qt/architecture.md b/docs/qt/architecture.md index 557de91312..5804db42ac 100644 --- a/docs/qt/architecture.md +++ b/docs/qt/architecture.md @@ -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. diff --git a/docs/qt/install.txt b/docs/qt/install.md similarity index 67% rename from docs/qt/install.txt rename to docs/qt/install.md index f53c602b8c..293999385a 100644 --- a/docs/qt/install.txt +++ b/docs/qt/install.md @@ -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 -> make install -> ldconfig + > mkdir buildqt + > cd buildqt + > ../configure --with-qt + > make + > su + > 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 -> make uninstall -> ldconfig + > su + > 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 -