From d2aa2c610dc91963c4be0f088fa3fd690d4a2a48 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Thu, 12 Feb 2015 12:33:24 -0800 Subject: WSDG: Start adding Qt material. Move some text from README.qt to the Developer's Guide. Add an overview. Change-Id: Ia20ed837939e34871b157566c38cd0c6e590bc38 Reviewed-on: https://code.wireshark.org/review/7087 Reviewed-by: Gerald Combs --- .../wsdg_src/WSDG_chapter_userinterface.asciidoc | 106 ++++++++++++++++++++- 1 file changed, 101 insertions(+), 5 deletions(-) (limited to 'docbook/wsdg_src') diff --git a/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc index 1a9eb30d30..4226034a58 100644 --- a/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc @@ -16,12 +16,12 @@ 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, GTK 2.x based * Wireshark, GTK 3.x based (Wireshark 1.10 and newer) -* Wireshark, Qt based (Wireshark 1.11 and newer) - * TShark, console based There are other Wireshark frontends which are not developed nor maintained by @@ -34,7 +34,103 @@ under the GPL, see: http://www.paglo.com/opensource/packetyzer[]) finished) This chapter is focused on the Wireshark frontend, and especially on -the GTK interface. +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). + +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. + +==== Source Code Overview + +Wireshark's `main` entry point is in 'wireshark-qt.cpp'. Command-line arguments +are processed there and the main application class (`WiresharkApplication`) +instance is created there along with the main window. + +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'. + +Most of the modules in 'ui/qt' are dialogs. Although we follow Qt naming +conventions for class names, we follow our own conventions by separating file +name components with underscores. For example, ColoringRulesDialog is defined in +'coloring_rules_dialog.cpp', 'coloring_rules_dialog.h', and +'coloring_rules_dialog.ui'. + +General-purpose dialogs are subclasses of `QDialog`. Dialogs that rely on the +current capture file can sublcass `WiresharkDialog`, which provides methods and +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 + +The code in 'ui/qt' directory uses three APIs: Qt (which uses +InterCapConvention), GLib (which uses underscore_convention), and the Wireshark +API (which also uses underscore_convention). As a general rule Wireshark's Qt +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. + +===== Strings + +If you're using GLib string functions or plain old C character array idioms in +Qt-only code you're probably doing something wrong. QStrings are generally +*much* safer and easier to use. They also make translations easier. + +If you need to pass strings between Qt and GLib you can use a number +of convenience routines which are defined in 'ui/qt/qt_ui_utils.h'. + +If you're calling a function that returns wmem-allocated memory it might make +more sense to add a wrapper function to 'qt_ui_utils' than to call wmem_free in +your code. + +===== Mixing C and C++ + +Sometimes we have to call C++ functions from one of Wireshark's C callbacks and +pass C++ objects to or from C. Tap listeners are a common example. The C++ FAQ +link:$$http://www.parashift.com/c++-faq/mixing-c-and-cpp.html$$:[describes how to do this +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()`. + +However, please avoid using `tr()` for static strings and define them in '*.ui' +files instead. `tr()` on manually created objects like `QMenu` are not +automatically retranslated and must instead be manually translated using +`changeEvent()` and `retranslateUi()`. See 'summary_dialog.[ch]' for an example +of this. + +NOTE: If your object life is short and your components are (re)created +dynamically then it is ok to to use `tr()`. + +In most cases you should handle the changeEvent in order to catch +`QEvent::LanguageChange`. + +==== Other Issues + +The main window has many QActions which are shared with child widgets. See +'ui/qt/proto_tree.cpp' for an example of this. [[ChUIGTK]] @@ -48,8 +144,8 @@ 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 is 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 +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. -- cgit v1.2.3