2018-02-05 16:59:45 +00:00
|
|
|
|
// WSDG Chapter User Interface
|
2015-11-21 16:08:28 +00:00
|
|
|
|
|
2014-02-06 17:16:33 +00:00
|
|
|
|
[[ChapterUserInterface]]
|
|
|
|
|
|
|
|
|
|
== User Interface
|
|
|
|
|
|
|
|
|
|
[[ChUIIntro]]
|
|
|
|
|
|
|
|
|
|
=== Introduction
|
|
|
|
|
|
|
|
|
|
Wireshark can be logically separated into the backend (dissecting protocols,
|
|
|
|
|
file loading and saving, capturing, etc.) and the frontend (the user interface).
|
|
|
|
|
|
|
|
|
|
The following frontends are currently maintained by the Wireshark
|
|
|
|
|
development team:
|
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
* Wireshark, Qt based
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
2014-02-06 17:16:33 +00:00
|
|
|
|
* TShark, console based
|
|
|
|
|
|
|
|
|
|
This chapter is focused on the Wireshark frontend, and especially on
|
2015-02-12 20:33:24 +00:00
|
|
|
|
the Qt interface.
|
|
|
|
|
|
|
|
|
|
[[ChUIQt]]
|
|
|
|
|
|
|
|
|
|
=== The Qt Application Framework
|
|
|
|
|
|
|
|
|
|
Qt is a cross-platform application development framework. While we mainly use
|
|
|
|
|
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).
|
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
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
|
2018-04-09 04:11:26 +00:00
|
|
|
|
avoided or reduced. For example, compared to the legacy UI many alert
|
|
|
|
|
dialogs have been replaced with status bar messages. Statistics dialogs
|
|
|
|
|
are displayed immediately instead of requiring that options be
|
|
|
|
|
specified.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
|
|
|
|
|
*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
|
2018-02-04 23:15:02 +00:00
|
|
|
|
provide a “hint” area near the bottom which shows useful information.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
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
|
2018-02-04 23:15:02 +00:00
|
|
|
|
the present time, so it’s recommended that you use it on macOS or Linux.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
|
|
|
|
|
To edit and build Wireshark using Qt Cretor, open the top-level
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_CMakeLists.txt_ within Qt Creator. It should ask you to choose a build
|
2016-09-19 22:05:18 +00:00
|
|
|
|
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
|
2018-04-09 04:11:26 +00:00
|
|
|
|
ENABLE_CCACHE=ON") and click the ``Run CMake'' button. When that
|
2016-09-19 22:05:18 +00:00
|
|
|
|
completes select ``Build → Open Build and Run Kit Selector...'' and make
|
2018-02-04 19:39:56 +00:00
|
|
|
|
sure _wireshark_ is selected.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
Note that Qt Creator uses output created by CMake’s *CodeBlocks*
|
2016-09-19 22:05:18 +00:00
|
|
|
|
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.
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
|
|
|
|
==== Source Code Overview
|
|
|
|
|
|
2018-06-07 20:04:38 +00:00
|
|
|
|
Wireshark’s `main` entry point is in _ui/qt/main.cpp_. Command-line arguments
|
2015-02-12 20:33:24 +00:00
|
|
|
|
are processed there and the main application class (`WiresharkApplication`)
|
|
|
|
|
instance is created there along with the main window.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
The main window along with the rest of the application resides in _ui/qt_. Due
|
|
|
|
|
to its size the main window code is split into two modules, _main_window.cpp_
|
|
|
|
|
and _main_window_slots.cpp_.
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
Most of the modules in _ui/qt_ are dialogs. Although we follow Qt naming
|
2015-02-12 20:33:24 +00:00
|
|
|
|
conventions for class names, we follow our own conventions by separating file
|
|
|
|
|
name components with underscores. For example, ColoringRulesDialog is defined in
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_coloring_rules_dialog.cpp_, _coloring_rules_dialog.h_, and
|
|
|
|
|
_coloring_rules_dialog.ui_.
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
|
|
|
|
General-purpose dialogs are subclasses of `QDialog`. Dialogs that rely on the
|
2015-11-21 16:08:28 +00:00
|
|
|
|
current capture file can subclass `WiresharkDialog`, which provides methods and
|
2015-02-12 20:33:24 +00:00
|
|
|
|
members that make it easier to access the capture file and to keep the dialog
|
|
|
|
|
open when the capture file closes.
|
|
|
|
|
|
|
|
|
|
==== Coding Practices and Naming Conventions
|
|
|
|
|
|
|
|
|
|
===== Names
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
The code in _ui/qt_ directory uses three APIs: Qt (which uses
|
2015-02-12 20:33:24 +00:00
|
|
|
|
InterCapConvention), GLib (which uses underscore_convention), and the Wireshark
|
2018-02-04 23:15:02 +00:00
|
|
|
|
API (which also uses underscore_convention). As a general rule Wireshark’s Qt
|
2015-02-12 20:33:24 +00:00
|
|
|
|
code uses InterCapConvention for class names, interCapConvention for methods,
|
|
|
|
|
and underscore_convention for variables, with a trailing_underscore_ for member
|
|
|
|
|
variables.
|
|
|
|
|
|
|
|
|
|
===== Dialogs
|
|
|
|
|
|
|
|
|
|
Dialogs that work with capture file information shouldn't close just because the
|
|
|
|
|
capture file closes. Subclassing `WiresharkDialog` as described above can make
|
|
|
|
|
it easier to persist across capture files.
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
When you create a window with a row of standard “OK” and “Close” buttons at
|
2015-02-13 19:18:30 +00:00
|
|
|
|
the bottom using Qt Creator you will end up with a subclass of QDialog. This is
|
2018-02-04 23:15:02 +00:00
|
|
|
|
fine for traditional modal dialogs, but many times the “dialog” needs to behave
|
2015-02-13 19:18:30 +00:00
|
|
|
|
like a QWindow instead.
|
|
|
|
|
|
|
|
|
|
Modal dialogs should be constructed with `QDialog(parent)`. Modeless dialogs
|
|
|
|
|
(windows) should be constructed with `QDialog(NULL, Qt::Window)`. Other
|
|
|
|
|
combinations (particularly `QDialog(parent, Qt::Window)`) can lead to odd and
|
|
|
|
|
inconsistent behavior. Again, subclassing `WiresharkDialog` will take care of
|
|
|
|
|
this for you.
|
|
|
|
|
|
2015-02-17 20:35:07 +00:00
|
|
|
|
Most of the dialogs in ui/qt share many similarities, including method names,
|
|
|
|
|
widget names, and behavior. Most dialogs should have the following, although
|
2018-02-04 23:15:02 +00:00
|
|
|
|
it’s not strictly required:
|
2015-02-17 20:35:07 +00:00
|
|
|
|
|
|
|
|
|
- An `updateWidgets()` method, which enables and disables widgets depending on
|
|
|
|
|
the current state and constraints of the dialog. For example, the Coloring
|
2016-11-01 21:35:29 +00:00
|
|
|
|
Rules dialog disables the *Save* button if the user has entered an
|
2015-02-17 20:35:07 +00:00
|
|
|
|
invalid display filter.
|
|
|
|
|
- A `hintLabel()` widget subclassed from `QLabel` or `ElidedLabel`, placed just
|
|
|
|
|
above the dialog button box. The hint label provides guidance and feedback to
|
|
|
|
|
the user.
|
|
|
|
|
- A context menu (`ctx_menu_`) for additional actions not present in the
|
|
|
|
|
button box.
|
|
|
|
|
- If the dialog box contains a `QTreeWidget` you might want to add your own
|
|
|
|
|
`QTreeWidgetItem` subclass with the following methods:
|
|
|
|
|
`drawData()`:: Draws column data with any needed formatting.
|
|
|
|
|
`colData()`:: Returns the data for each column as a `QVariant`. Used for
|
|
|
|
|
copying as CSV, YAML, etc.
|
|
|
|
|
`operator<()`:: Allows sorting columns based on their raw data.
|
|
|
|
|
|
2015-02-12 20:33:24 +00:00
|
|
|
|
===== Strings
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
Wireshark’s C code and GLib use UTF-8 encoded character arrays. Qt
|
2017-12-14 18:29:48 +00:00
|
|
|
|
(specifically QString) uses UTF-16. You can convert a `char *` to a
|
|
|
|
|
`QString` using simple assignment. You can convert a `QString` to a
|
|
|
|
|
`const char *` using `qUtf8Printable`.
|
|
|
|
|
|
|
|
|
|
If you're using GLib string functions or plain old C character array
|
|
|
|
|
idioms in Qt-only code you're probably doing something wrong,
|
|
|
|
|
particularly if you're manually allocating and releasing memory.
|
|
|
|
|
QStrings are generally *much* safer and easier to use. They also make
|
|
|
|
|
translations easier.
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
|
|
|
|
If you need to pass strings between Qt and GLib you can use a number
|
2018-02-04 19:39:56 +00:00
|
|
|
|
of convenience routines which are defined in _ui/qt/qt_ui_utils.h_.
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
|
|
|
|
If you're calling a function that returns wmem-allocated memory it might make
|
2018-02-04 19:39:56 +00:00
|
|
|
|
more sense to add a wrapper function to _qt_ui_utils_ than to call wmem_free in
|
2015-02-12 20:33:24 +00:00
|
|
|
|
your code.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
===== Mixing C and {cpp}
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
Sometimes we have to call {cpp} functions from one of
|
2018-02-04 23:15:02 +00:00
|
|
|
|
Wireshark’s C callbacks and pass {cpp} objects to or from C. Tap
|
2018-02-04 19:39:56 +00:00
|
|
|
|
listeners are a common example. The {cpp} FAQ link:http://www.
|
|
|
|
|
parashift.com/c++-faq/mixing-c-and-cpp.html:[describes how to do this
|
2015-02-12 20:33:24 +00:00
|
|
|
|
safely].
|
|
|
|
|
|
|
|
|
|
Tapping usually involves declaring static methods for callbacks, passing `this`
|
|
|
|
|
as the tap data.
|
|
|
|
|
|
|
|
|
|
===== Internationalization and Translation
|
|
|
|
|
|
|
|
|
|
Qt provides a convenient method for translating text: `Qobject::tr()`,
|
|
|
|
|
usually available as `tr()`.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
However, please avoid using `tr()` for static strings and define them in _*.ui_
|
2015-02-12 20:33:24 +00:00
|
|
|
|
files instead. `tr()` on manually created objects like `QMenu` are not
|
|
|
|
|
automatically retranslated and must instead be manually translated using
|
2018-02-04 19:39:56 +00:00
|
|
|
|
`changeEvent()` and `retranslateUi()`. See _summary_dialog.[ch]_ for an example
|
2015-02-12 20:33:24 +00:00
|
|
|
|
of this.
|
|
|
|
|
|
|
|
|
|
NOTE: If your object life is short and your components are (re)created
|
2015-11-21 16:08:28 +00:00
|
|
|
|
dynamically then it is ok to use `tr()`.
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
|
|
|
|
In most cases you should handle the changeEvent in order to catch
|
|
|
|
|
`QEvent::LanguageChange`.
|
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
Qt makes translating the Wireshark UI into different languages easy. To add a new
|
|
|
|
|
translation, do the following:
|
|
|
|
|
|
2018-04-15 21:40:36 +00:00
|
|
|
|
- Add your translation (_ui/qt/wireshark_XX.ts_) to _ui/qt/CMakeLists.txt_
|
2018-02-04 19:39:56 +00:00
|
|
|
|
- (Recommended) Add a flag image for your language in _images/languages/XX.svg_. Update _image/languages/languages.qrc_ accordingly.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
- 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`.
|
2018-02-04 19:39:56 +00:00
|
|
|
|
- Do a test build and make sure the generated _wireshark_XX.qm_ binary file is included.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
- Push your translation to Gerrit for review. See <<ChSrcContribute>> for details.
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
Alternatively you can put your QM and flag files in the _languages_
|
2016-09-19 22:05:18 +00:00
|
|
|
|
directory in the Wireshark user configuration directory
|
2018-02-04 19:39:56 +00:00
|
|
|
|
(_$XDG_CONFIG_HOME/wireshark/languages/_ or _$HOME/.wireshark/languages/_ on
|
2017-03-03 11:39:14 +00:00
|
|
|
|
UNIX).
|
2016-09-19 22:05:18 +00:00
|
|
|
|
|
|
|
|
|
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].
|
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
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
|
2016-09-19 22:05:18 +00:00
|
|
|
|
|
2016-11-25 17:42:26 +00:00
|
|
|
|
===== Colors
|
|
|
|
|
|
|
|
|
|
Qt provides a number of colors via the http://doc.qt.io/qt-5/qpalette.html[QPalette]
|
|
|
|
|
class. Use this class when you need a standard color provided by the
|
|
|
|
|
underlying operating system.
|
|
|
|
|
|
|
|
|
|
Wireshark uses an extended version of the
|
|
|
|
|
http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines[Tango Color Palette]
|
|
|
|
|
for many interface elements that require custom colors. This includes the
|
|
|
|
|
I/O graphs, sequence diagrams, and RTP streams. Please use this palette
|
|
|
|
|
(defined in `tango_colors.h` and the *ColorUtils* class) if *QPalette*
|
|
|
|
|
doesn't meet your needs.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
|
|
|
|
|
==== Other Issues and Information
|
2015-02-12 20:33:24 +00:00
|
|
|
|
|
|
|
|
|
The main window has many QActions which are shared with child widgets. See
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_ui/qt/proto_tree.cpp_ for an example of this.
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
http://www.kdab.com/kdab-products/gammaray/[GammaRay] lets you inspect
|
2016-09-23 22:51:44 +00:00
|
|
|
|
the internals of a running Qt application similar to $$Spy++$$ on Windows.
|
2016-09-19 22:05:18 +00:00
|
|
|
|
|
2014-02-06 17:16:33 +00:00
|
|
|
|
[[ChUIGUIDocs]]
|
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
=== Human Interface Reference Documents
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
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.
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
For further reference, see the following:
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
|
|
|
|
* Android Design:
|
2018-10-12 19:11:06 +00:00
|
|
|
|
https://developer.android.com/design/[]. Wireshark doesn't have
|
2016-09-19 22:05:18 +00:00
|
|
|
|
a mobile frontend (not yet, at least) but there is still useful
|
|
|
|
|
information here.
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
|
|
|
|
* GNOME Human Interface Guidelines:
|
2018-10-12 19:11:06 +00:00
|
|
|
|
https://developer.gnome.org/hig/stable/[]
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
2018-10-12 19:11:06 +00:00
|
|
|
|
* KDE Human Interface Guidelines:
|
|
|
|
|
https://hig.kde.org[]
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
2017-03-01 21:58:16 +00:00
|
|
|
|
* macOS Human Interface Guidelines:
|
2018-10-12 19:11:06 +00:00
|
|
|
|
https://developer.apple.com/design/human-interface-guidelines/macos/overview/themes/[]
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
2018-10-12 19:11:06 +00:00
|
|
|
|
* Design guidelines for the Windows desktop:
|
|
|
|
|
https://docs.microsoft.com/en-us/windows/desktop/uxguide/guidelines[]
|
2014-02-06 17:16:33 +00:00
|
|
|
|
|
2016-09-19 22:05:18 +00:00
|
|
|
|
* User Experience Stack Exchange:
|
|
|
|
|
https://ux.stackexchange.com/[]
|
|
|
|
|
|
2018-02-05 16:59:45 +00:00
|
|
|
|
// End of WSDG Chapter User Interface
|