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
