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 <gerald@wireshark.org>

1 files changed, 101 insertions, 5 deletions

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.