doc/README.qt

   1 0. Abstract
   2
   3 Wireshark's user interface is showing its age. While GTK+ is wonderful on
   4 Linux and BSD its low-tier status on Windows and even-lower-tier status on OS
   5 X makes it hard to deliver a good product to users on those platforms.
   6
   7 The Qt port is an attempt at an updated UI which will better serve our users
   8 and let us add features more easily.
   9
  10
  11 1. Getting up and running
  12
  13 The Qt interface for Wireshark has been compiled and tested on Mac OS X 10.8
  14 (XCode LLVM/clang), Windows 7 x86 (Visual C++ 2010), and Ubuntu 12.04 (gcc).
  15 Compilation via Qt Creator and via the command line compilation using QMake and
  16 make or nmake should work.
  17
  18 There are several ways of building qtshark:
  19
  20 1) Qt Creator + CMake:
  21
  22    Open the top-level CMakeLists.txt within Qt Creator. It should ask you to
  23    choose a build location. Do so. It should then ask you to run CMake. Fill in
  24    any desired build arguments (e.g. "-D CMAKE_BUILD_TYPE:STRING=Debug" or
  25    "-D ENABLE_GTK3:BOOL=OFF") and click the "Run CMake" button. When that
  26    completes select "Build → Open Build and Run Kit Selector..." and make
  27    sure wireshark is selected.
  28
  29 2) CMake:
  30
  31    Qt (BUILD_wireshark) is enabled by default. Use the "cmake" command to
  32    configure a normal out-of-tree or in-tree build, e.g.
  33
  34     mkdir cmakebuild
  35     cd cmakebuild
  36     cmake
  37     make
  38
  39    Note that CMake builds an application bundle (Wireshark.app) on Mac OS X
  40    by default. Use the option "-DENABLE_APPLICATION_BUNDLE=OFF" to create a
  41    traditional UNIX/POSIX build.
  42
  43 3) Autotools:
  44
  45    Qt (--with-qt) is enabled by default.
  46
  47 4) Qt Creator + QtShark.pro:
  48
  49    NOTE: The bulk of Wireshark isn't a qmake project and the ui/qt directory is
  50    loosely coupled with the rest of the codebase. When the CMake environment
  51    matures to a sufficient state QtShark.pro will probably be removed.
  52
  53 Work is in progress on this.)
  54
  55 1.1 Prerequisites
  56
  57 Before compiling you need the Qt SDK and Qt Creator.
  58
  59 1.1.1 OS X
  60
  61 Download the latest Qt Library + Qt Creator (currently 5.3) from
  62 http://qt-project.org/downloads/ and install it. For a more native
  63 look and feel you should also install Qt Mac Extras:
  64
  65     git clone http://qt.gitorious.org/qt/qtmacextras.git
  66     cd qtmacextras
  67     /path/to/qt5/qmake qtmacextras.pro
  68     make
  69     make -n install
  70     # Make sure install output looks sensible
  71     make install
  72
  73 This may or may not work for you; see
  74
  75     https://bugreports.qt-project.org/browse/QTBUG-32594
  76
  77 1.1.2 Windows
  78
  79 The default Qt SDK libraries are built using MinGW, which isn't supported for
  80 Wireshark. Instead of downloading the Qt SDK all-in-one package, download the Qt
  81 Libraries package from http://qt-project.org/downloads/ that matches your
  82 compiler (VS 2010 or VS 2012) and Qt Creator for Windows.
  83
  84 Settings in config.nmake are passed to the Qt environment via
  85 ui/qt/config.pri. This file should be created automatically when you
  86 compile Wireshark in the top-level source directory. You can create it by
  87 hand by running "nmake -f Makefile.nmake ui\qt\config.pri".
  88
  89 Qt Creator can be used to compile and run Wireshark.  Alternatively qmake
  90 and nmake at the cmd line can be used.
  91
  92 The Windows Qt version of Wireshark will be compiled and linked with
  93 essentially the same options as that used when building the Gtk version of
  94 Wireshark.
  95
  96 1.1.2.1 Qt Creator
  97
  98 Before compiling in Qt Creator select "Projects" in the left toolbar,
  99 select "Build Settings" and do the following:
 100
 101 - In "Edit build configuration" make sure the "Release" build is selected.
 102   (The "Debug" build won't work unless Wireshark is recompiled to link with a "debug"
 103    the "debug" C runtime library (using /MDd). See ui\qt\QtShark.pro for details).
 104
 105 - Make sure "Qt version" matches your version of Visual Studio.
 106 - Make sure "Tool chain" matches your Visual C++ version.
 107
 108 If you require plugin support select "Run Settings" and add
 109 "WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1" to the Run Environment.
 110
 111 XXX: (WMeier): I've not had too much satisfaction using the "native Windows debugger" (CDB ?)
 112      accessed via Qt Creator. (In fact, a web search turns up some fairly negative comments
 113      about the debugger. I've successfully (and pretty easily) been able to use the
 114      Visual Studio debugger; See below under "Command Line".
 115      ToDo: Investigate "Qt Visual Studio AddIn":
 116            http://developer.qt.nokia.com/wiki/QtVSAddin#6112edd2e39a1695c242723d5c764aae
 117
 118 1.1.2.2 Command Line
 119
 120 - Setup environment:
 121     c:\qt\4.8.0\bin\qtvars.bat [vsvars]     ;;; optional 'vsvars' to also setup VC env vars
 122
 123 - [Create and] Switch to a working dir to be used for .obj files, etc for Wireshark-qt compilation
 124
 125 - Use qmake to create Windows Makefile (based upon info in ui\qt\QtShark.pro and config.pri)
 126     qmake -o Makefile.nmake ..\..\ui\qt\QtShark.pro
 127                                   ;; (Only needs to be run once;
 128                                   ;; nmake -f Makefile.nmake  will redo qmake if any
 129                                   ;; dependendencies (e.g., QtShark.pro) change.
 130
 131 - Compile & Build
 132     nmake -f Makefile.nmake       ;; qtshark.exe + all DLL's will be in <working-dir>\wireshark-qt-debug
 133 - Run:
 134     <working-dir>\wireshark-qt-debug
 135
 136 - Debug (with Visual Studio debugger)
 137     Start Visual Studio;
 138     File ! Open ! Project/Solution  ! .../<working-dir>/wireshark-qt-debug/qtshark.exe
 139     (Using  Solution Explorer ! Properties ! Environment to
 140      add PATH=C:\Qt\4.8.0\bin;%PATH% will pobably be required).
 141     ... Debug in the usual manner
 142
 143
 144 1.1.3 Linux
 145
 146 Install the Qt libraries and Qt Creator via your package manager or from
 147 http://qt-project.org/downloads/. On Debian and Ubuntu the "qt-sdk" (and qttools5-dev when use Qt5) meta-package
 148 should provide everything you need. Build the top-level directory using CMake
 149 (see section "Using cmake" above). As an alternative do an in-tree build without
 150 QT and then inside ui/qt/ do "qtcreate QtShark.pro".
 151
 152 1.2 Other tools
 153
 154 GammaRay lets you inspect the internals of a running Qt application
 155 similar to Spy++ on Windows.
 156
 157 http://www.kdab.com/kdab-products/gammaray/
 158
 159 2. Going forward
 160
 161 DO NOT simply port things over. Much of the GTK+ interface reflects historical
 162 UI conventions and API restrictions which are either no longer relevant or have
 163 been superseded. Every feature, window, and element should be re-thought. When
 164 porting a feature, consider the following:
 165
 166 - Workflow. Excessive navigation and gratuitous dialogs should be avoided or
 167   reduced. For example, the two GTK+ flow graph dialogs have been combined into
 168   one in Qt. Many alert dialogs have been replaced with status bar messages.
 169
 170 - Feedback. Most of the Qt dialogs provide a "hint" area near the bottom which
 171   shows useful information. For example, the "Follow Stream" dialog shows the
 172   packet corresponding to the text under the mouse. The profile management
 173   dialog shows a clickable path to the current profile.
 174
 175 2.1 Coding guidelines
 176
 177 2.1.1 Name conventions
 178
 179 Most of the code in the ui/qt directory uses three APIs: Qt (which uses
 180 InterCapConvention), GLib (which uses underscore_convention), and the
 181 Wireshark API (which also uses underscore_convention). As a general rule
 182 Wireshark's Qt code uses InterCapConvention for class names,
 183 interCapConvention for methods, and underscore_convention for variables,
 184 with a trailing underscore for member variables.
 185
 186 2.1.2 Class layout
 187
 188 Dialogs that work with capture file information shouldn't close just
 189 because the capture file closes. I.e. they should receive the
 190 setCaptureFile signal and react accordingly.
 191
 192 In most cases you should handle the changeEvent in order to catch
 193 QEvent::LanguageChange.
 194
 195 2.1.3 Strings
 196
 197 If you're using GLib string functions or plain old C character array idioms in
 198 Qt-only code you're probably doing something wrong. QStrings are generally
 199 *much* safer and easier to use. They also make translations easier.
 200
 201 If you need to pass strings between Qt and GLib you can use qstring_strdup
 202 gchar_free_to_qstring, which are defined in ui/qt/qt_ui_utils.h.
 203
 204 If you're calling a function that returns wmem-allocated memory it might make
 205 more sense to add a wrapper function to qt_ui_utils than to call wmem_free in
 206 your code.
 207
 208 2.1.4 Mixing C and C++
 209
 210 Sometimes we have to call C++ functions from one of Wireshark's C callbacks and
 211 pass C++ objects to or from C. The C++ FAQ describes how to do this safely:
 212
 213 http://www.parashift.com/c++-faq/mixing-c-and-cpp.html
 214
 215 2.2 Changes
 216
 217 - The display filter entry has been significantly reworked.
 218
 219 - The welcome screen has been reworked. The interface list includes sparklines
 220
 221 - "Go to packet" pops up a text entry in the main window instead of a separate dialog.
 222
 223 - Preferences are complete, and are arguably more useful than the GTK+ version.
 224   An "Advanced" preference pane exists, which lets you edit everything. They use
 225   the proper menu placement and keyboard shortcut on OS X.
 226
 227 - Some dialogs (file sets, profiles, and UATs) provide a link to filesystem paths
 228   where appropriate.
 229
 230 3. Translations (i18n)
 231
 232 3.1 Make translation
 233
 234 Qt makes translating the Wireshark UI into different languages easy.
 235
 236 - Add your translation (ui/qt/wireshark_XX.ts) in ui/qt/Wireshark.pro, ui/qt/i18n.qrc,
 237     ui/qt/Makefile.common and ui/qt/CMakeLists.txt
 238 - Please add flag (image) for your language in images/languages/XX.svg and image/languages/languages.qrc
 239 - Run "lupdate ui/qt/Wireshark.pro" to generate/update your translation file.
 240   or "lupdate ui/qt -ts ui/qt/wireshark_XX.ts" for specified translation
 241 - Translate with Qt Linguist (in console: "linguist ui/qt/wireshark_XX.ts")
 242 - Run "lrelease Wireshark.pro" or
 243   "lrelease ui/qt/wireshark_XX.ts -qm ui/qt/wireshark_XX.qm" to create/update wireshark_XX.qm file.
 244 - Push your translation to Gerrit for review ("git push").
 245
 246 Alternatively you can only put your QM and flag files in "languages" directory in
 247 Wireshark user configuration directory (~/.wireshark/languages/ on unix)
 248
 249 More information about Qt Linguist
 250 http://qt-project.org/doc/qt-4.8/linguist-manual.html
 251
 252 3.2 Developing
 253
 254 - Please avoid tr() in code, try add any strings in *.ui files; tr() on manually
 255   created object (like QMenu) are not automatically retranslated, so you must
 256   add a couple of code to manually translate them
 257   NOTE: if your object life is short, so any time when your component needs to be shown
 258   it is (re)created then it is ok to have tr() in code
 259 - For creating submenu in context menu please follow solution from ui/qt/proto_tree.cpp
 260 - Some new windows need also to override changeEvent() and do retranslateUi() like
 261   summary_dialog.[ch] does