diff options
| -rw-r--r-- | doc/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/README.qt | 215 | ||||
| -rw-r--r-- | docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc | 141 |
3 files changed, 111 insertions, 246 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 2c9cd5c34b..fe160bdc90 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -301,7 +301,6 @@ EXTRA_DIST = \ README.idl2wrs \ README.packaging \ README.plugins \ - README.qt \ README.regression \ README.request_response_tracking\ README.stats_tree \ diff --git a/doc/README.qt b/doc/README.qt deleted file mode 100644 index d1c268de1c..0000000000 --- a/doc/README.qt +++ /dev/null @@ -1,215 +0,0 @@ -0. Abstract - -Wireshark's user interface is showing its age. While GTK+ is wonderful on -Linux and BSD its low-tier status on Windows and even-lower-tier status on OS -X makes it hard to deliver a good product to users on those platforms. - -The Qt port is an attempt at an updated UI which will better serve our users -and let us add features more easily. - - -1. Getting up and running - -The Qt interface for Wireshark should compile out of the box on Windows, OS -X, and Linux using Qt 4.7 or later (including Qt 5) and Visual C++, gcc/g++, -and clang/clang++. The Qt UI is continuously built and tested at -https://buildbot.wireshark.org/trunk/waterfall . - -There are several ways of building the Qt UI: - -1) Qt Creator + CMake (recommended if adding features): - - Open the top-level CMakeLists.txt within Qt Creator. It should ask you to - choose a build location. Do so. It should then ask you to run CMake. Fill in - any desired build arguments (e.g. "-D CMAKE_BUILD_TYPE=Debug" or - "-D ENABLE_GTK3=OFF") and click the "Run CMake" button. When that - completes select "Build → Open Build and Run Kit Selector..." and make - sure wireshark is selected. - - Note that Qt Creator uses output created by the CodeBlocks generator. If - you run CMake outside of Qt Creator you should use the "CodeBlocks - Unix - Makefiles" or "CodeBlocks - NMake Makefiles" generators, otherwise Qt - Creator will prompt you to re-run CMake. - -2) CMake: - - Qt (BUILD_wireshark) is enabled by default. Use the "cmake" command to - configure a normal out-of-tree or in-tree build, e.g. - - mkdir cmakebuild - cd cmakebuild - cmake - make - - Note that CMake builds an application bundle (Wireshark.app) on OS X - by default. Use the option "-DENABLE_APPLICATION_BUNDLE=OFF" to create a - traditional UNIX/POSIX build. - -3) Autotools: - - Qt (--with-qt) is enabled by default. - -1.1 Prerequisites - -Before compiling you need the Qt SDK and Qt Creator. - -1.1.1 OS X - -Download the latest Qt Library + Qt Creator from -http://www.qt.io/download-open-source/. Qt 5.2 and later include -Qt Mac Extras (http://doc.qt.io/qt-5/qtmacextras-index.html), which -provides a better look and feel. - -Build the top-level directory using CMake or autotools (see section -"Getting up and running" above). - -1.1.2 Windows - -Download the Qt online installer from http://www.qt.io/download-open-source/ -and run it. Install a version of Qt that matches your compiler, e.g. -"msvc2013 64-bit OpenGL". Install Qt Creator as well. Wireshark doesn't -require anything beyond that. - -1.1.2.1 Qt Creator - -Before compiling in Qt Creator select "Projects" in the left toolbar, -select "Build Settings" and do the following: - -- In "Edit build configuration" make sure the "Release" build is selected. - (The "Debug" build won't work unless Wireshark is recompiled to link with a "debug" - the "debug" C runtime library (using /MDd)). - -- Make sure "Qt version" matches your version of Visual Studio. -- Make sure "Tool chain" matches your Visual C++ version. - -If you require plugin support select "Run Settings" and add -"WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1" to the Run Environment. - -XXX: (WMeier): I've not had too much satisfaction using the "native Windows debugger" (CDB ?) - accessed via Qt Creator. (In fact, a web search turns up some fairly negative comments - about the debugger. I've successfully (and pretty easily) been able to use the - Visual Studio debugger; See below under "Command Line". - ToDo: Investigate "Qt Visual Studio AddIn": - http://developer.qt.nokia.com/wiki/QtVSAddin#6112edd2e39a1695c242723d5c764aae - -1.1.2.2 Command Line - -- [Create and] Switch to a working dir to be used for .obj files, etc for Wireshark-qt compilation - -- Use CMake to create Windows Makefile and compile (see README.cmake) - -- Run: - <working-dir>\wireshark-qt-debug - -- Debug (with Visual Studio debugger) - Start Visual Studio; - File ! Open ! Project/Solution ! .../<working-dir>/wireshark-qt-debug/wireshark.exe - (Using Solution Explorer ! Properties ! Environment to - add PATH=C:\Qt\4.8.0\bin;%PATH% will probably be required). - ... Debug in the usual manner - - -1.1.3 Linux - -Install the Qt libraries and Qt Creator via your package manager or from -http://qt-project.org/downloads/. On Debian, Ubuntu, and other Debian -derivatives, the "qt-sdk" (and qttools5-dev when use Qt5) meta-package -should provide everything you need. - -Build the top-level directory using CMake or autotools (see section -"Getting up and running" above). - -1.1.4 Other UN*Xes - -For the *BSDs, if the ports collection/packages collection has Qt, -install the Qt libraries and Qt Creator via packages. - -For Solaris, install the Qt libraries and Qt Creator via OpenCSW or, for -Solaris 11, the Image Packaging System. - -Otherwise, download the source from http://qt-project.org/downloads/ and -compile and install it. - -Build the top-level directory using CMake or autotools (see section -"Getting up and running" above). - -1.2 Other tools - -GammaRay lets you inspect the internals of a running Qt application -similar to Spy++ on Windows. - -http://www.kdab.com/kdab-products/gammaray/ - -2. Going forward - -DO NOT simply port things over. Much of the GTK+ interface reflects historical -UI conventions and API restrictions which are either no longer relevant or have -been superseded. Every feature, window, and element should be re-thought. When -porting a feature, consider the following: - -- Workflow. Excessive navigation and gratuitous dialogs should be avoided or - reduced. For example, the two GTK+ flow graph dialogs have been combined into - one in Qt. Many alert dialogs have been replaced with status bar messages. - -- Feedback. Most of the Qt dialogs provide a "hint" area near the bottom which - shows useful information. For example, the "Follow Stream" dialog shows the - packet corresponding to the text under the mouse. The profile management - dialog shows a clickable path to the current profile. - -2.1 Coding guidelines - -Moved to the Developer's Guide: - -https://www.wireshark.org/docs/wsdg_html_chunked/ChUIQt.html - - -2.2 Changes - -- The display filter entry has been significantly reworked. - -- The welcome screen has been reworked. The interface list includes sparklines - -- "Go to packet" pops up a text entry in the main window instead of a separate dialog. - -- Preferences are complete, and are arguably more useful than the GTK+ version. - An "Advanced" preference pane exists, which lets you edit everything. They use - the proper menu placement and keyboard shortcut on OS X. - -- Some dialogs (file sets, profiles, and UATs) provide a link to filesystem paths - where appropriate. - -3. Translations (i18n) - -3.1 Make translation - -Qt makes translating the Wireshark UI into different languages easy. - -- Add your translation (ui/qt/wireshark_XX.ts) in ui/qt/Makefile.am and ui/qt/CMakeLists.txt -- Please add flag (image) for your language in images/languages/XX.svg and image/languages/languages.qrc -- Run "lupdate ui/qt -ts ui/qt/wireshark_XX.ts" to generate/update your translation file. -- Translate with Qt Linguist (in console: "linguist ui/qt/wireshark_XX.ts") -- Do a test build and make sure the generated wireshark_XX.qm binary file is included. -- Push your translation to Gerrit for review ("git push"). - -Alternatively you can only put your QM and flag files in "languages" directory in -Wireshark user configuration directory (~/.wireshark/languages/ on unix) - -More information about Qt Linguist -http://qt-project.org/doc/qt-4.8/linguist-manual.html - -3.2 Translate ! - -You can now directly translate with Transifex Website -https://www.transifex.com/projects/p/wireshark/ - -Every week, translation is automatically resynced with the source code through the following steps -* pull ts from Transifex -* lupdate ts file -* push and commit on Gerrit -* push ts on Transifex - -4 Developing - -Moved to the Developer's Guide: - -https://www.wireshark.org/docs/wsdg_html_chunked/ChUIQt.html diff --git a/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc index a62412a780..6870b289c7 100644 --- a/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc @@ -16,22 +16,22 @@ file loading and saving, capturing, etc.) and the frontend (the user interface). The following frontends are currently maintained by the Wireshark development team: -* Wireshark, Qt based (Wireshark 1.11 and newer) +* Wireshark, Qt based -* Wireshark, GTK 2.x based +* Wireshark, GTK{plus} 2.x based -* Wireshark, GTK 3.x based (Wireshark 1.10 and newer) +* Wireshark, GTK{plus} 3.x based * TShark, console based There are other Wireshark frontends which are not developed nor maintained by the Wireshark development team: -* Packetyzer (Win32 native interface, written in Delphi and released -under the GPL, see: http://www.paglo.com/opensource/packetyzer[]) +* Packetyzer. Native Windows interface, written in Delphi and released +under the GPL. Not actively maintained. https://sourceforge.net/projects/packetyzer/[] -* hethereal (web based frontend, not actively maintained and not -finished) +* hethereal Web interface. Not actively maintained and not +finished. This chapter is focused on the Wireshark frontend, and especially on the Qt interface. @@ -45,9 +45,52 @@ the core (QtCore) and user interface (QtWidgets) modules, it also supports a number of other modules for specialized application development, such as networking (QtNetwork) and web browsing (QtWebKit). -At the time of this writing (February 2015) we are in the process of porting the -main Wireshark application to Qt. The sections below provide an overview of the -application and tips for Qt development in our environment. +At the time of this writing (September 2016) most of the main Wireshark +application has been ported to Qt. The sections below provide an +overview of the application and tips for Qt development in our +environment. + +==== User Experience Considerations + +When creating or modifying Wireshark try to make sure that it will work +well on Windows, macOS, and Linux. See <<ChUIGUIDocs>> for details. +Additionally, try to keep the following in mind: + +*Workflow*. Excessive navigation and gratuitous dialogs should be +avoided or reduced. For example, the two GTK+ flow graph dialogs have +been combined into one in Qt. Many alert dialogs have been replaced with +status bar messages. Statistics dialogs are displayed immediately +instead of requiring that options be specified. + +*Discoverability and feedback*. Most users don't like to read +documentation and instead prefer to learn an application as they use it. +Providing feedback increases your sense of control and awareness, and +makes the application more enjoyable to use. Most of the Qt dialogs +provide a ``hint'' area near the bottom which shows useful information. +For example, the ``Follow Stream'' dialog shows the packet corresponding +to the text under the mouse. The profile management dialog shows a +clickable path to the current profile. The main welcome screen shows +live interface traffic. Most dialogs have a context menu that shows +keyboard shortcuts. + +==== Qt Creator + +Qt Creator is a full-featured IDE and user interface editor. It makes +adding new UI features much easier. It doesn't work well on Windows at +the present time, so it's recommended that you use it on macOS or Linux. + +To edit and build Wireshark using Qt Cretor, open the top-level +'CMakeLists.txt' within Qt Creator. It should ask you to choose a build +location. Do so. It should then ask you to run CMake. Fill in any +desired build arguments (e.g. "-D CMAKE_BUILD_TYPE=Debug" or "-D +ENABLE_GTK3=OFF") and click the ``Run CMake'' button. When that +completes select ``Build → Open Build and Run Kit Selector...'' and make +sure 'wireshark' is selected. + +Note that Qt Creator uses output created by CMake's *CodeBlocks* +generator. If you run CMake outside of Qt Creator you should use the +``CodeBlocks - Unix Makefiles'' generator, otherwise Qt Creator will +prompt you to re-run CMake. ==== Source Code Overview @@ -159,29 +202,60 @@ dynamically then it is ok to use `tr()`. In most cases you should handle the changeEvent in order to catch `QEvent::LanguageChange`. -==== Other Issues +Qt makes translating the Wireshark UI into different languages easy. To add a new +translation, do the following: + +- Add your translation ('ui/qt/wireshark_XX.ts') to 'ui/qt/Makefile.am' and 'ui/qt/CMakeLists.txt' +- (Recommended) Add a flag image for your language in 'images/languages/XX.svg'. Update 'image/languages/languages.qrc' accordingly. +- Run `lupdate ui/qt -ts ui/qt/wireshark_XX.ts` to generate/update your translation file. +- Translate with Qt Linguist: `linguist ui/qt/wireshark_XX.ts`. +- Do a test build and make sure the generated 'wireshark_XX.qm' binary file is included. +- Push your translation to Gerrit for review. See <<ChSrcContribute>> for details. + +Alternatively you can put your QM and flag files in the 'languages' +directory in the Wireshark user configuration directory +('~/.wireshark/languages/' on UNIX). + +For more information about Qt Linguist see +http://qt-project.org/doc/qt-4.8/linguist-manual.html[its manual]. + +You can also manage translations online with +https://www.transifex.com/projects/p/wireshark/[Transifex]. + +Each week translations are automatically synchronized with the source code through the following steps: +* pull ts from Transifex +* lupdate ts file +* push and commit on Gerrit +* push ts on Transifex + + +==== Other Issues and Information The main window has many QActions which are shared with child widgets. See 'ui/qt/proto_tree.cpp' for an example of this. +http://www.kdab.com/kdab-products/gammaray/[GammaRay] lets you inspect +the internals of a running Qt application similar to Spy{plus}{plus} on Windows. + [[ChUIGTK]] === The GTK library -.We're switching to Qt +.We have switched to Qt [NOTE] ==== -This chapter describes the state of our stable release, which is based on GTK+. -A major effort is underway to migrate Wireshark to Qt. If you would like to add -a new interface feature you should use it and not GTK+. +Wireshark's default interface uses Qt. If you would like to add a new +interface feature you should use it and not GTK{plus}. +The documentation below is primarily historical. ==== -Wireshark was initially based on the GTK toolkit. See http://www.gtk.org[] for -details. GTK is designed to hide the details of the underlying GUI in a platform -independent way. As GTK is intended to be a multiplatform tool, there are some -drawbacks, as the result is a somewhat "non native" look and feel. +Wireshark was initially based on the GTK{plus} toolkit. See +http://www.gtk.org[] for details. GTK{plus} is designed to hide the +details of the underlying GUI in a platform independent way. As GTK is +intended to be a multiplatform tool, there are some drawbacks, as the +result is a somewhat "non native" look and feel. -GTK is available for many different platforms including, but not limited to: +GTK{plus} is available for many different platforms including, but not limited to: Unix/Linux, OS X and Win32. It's the foundation of the famous GNOME desktop, so the future development of GTK should be certain. GTK is implemented in plain C (as is Wireshark itself), and available under the LGPL (Lesser General Public @@ -191,7 +265,7 @@ There are other similar toolkits like wxWidgets which could also be used for Wireshark. There's no "one and only" reason for or against any of these toolkits. However, the decision towards GTK was made a long time ago :-) -As of 2013 there are two major GTK versions available: +There are two major GTK versions available: [[ChUIGTK2x]] @@ -265,19 +339,23 @@ for a better way. [[ChUIGUIDocs]] -=== GUI Reference documents +=== Human Interface Reference Documents -Although the GUI development of Wireshark is platform independent, the -Wireshark development team tries to -follow the GNOME Human Interface Guidelines (HIG) where appropriate. -This is the case, because both GNOME and Wireshark are based on the GTK+ -toolkit and the GNOME HIG is excellently written and easy to understand. +Wireshark runs on a number of platforms, primarily Windows, macOS, and +Linux. It should conform to the Windows, macOS, GNOME, and KDE human +interface guidelines as much as possible. Unfortunately, creating a +feature that works well across these platforms can sometimes be a +juggling act since the human interface guidelines for each platform +often contradict one another. If you run into trouble you can ask the +_wireshark-dev_ mailing list as well as the User Experience Stack +Exchange listed below. -For further reference, see the following documents: +For further reference, see the following: * Android Design: -http://developer.android.com/design/index.html[] (Wireshark doesn't have a -mobile frontend but there is still useful information here) +http://developer.android.com/design/index.html[]. Wireshark doesn't have +a mobile frontend (not yet, at least) but there is still useful +information here. * GNOME Human Interface Guidelines: http://library.gnome.org/devel/hig-book/stable/[] @@ -291,6 +369,9 @@ https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/ * Design apps for the Windows desktop: http://msdn.microsoft.com/en-us/library/Aa511258.aspx[] +* User Experience Stack Exchange: +https://ux.stackexchange.com/[] + [[ChUIGTKDialogs]] === Adding/Extending Dialogs |