From 1dc06a2681495b3bb2c75fc871f156f06b973260 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Thu, 6 Feb 2014 09:16:33 -0800 Subject: [PATCH] Convert the user interface chapter to AsciiDoc. Start mentioning Qt. Update and add HIG links. Change-Id: Iac984045b03a96862981d58ff63c9ee6bcdbbce8 Reviewed-on: https://code.wireshark.org/review/127 Tested-by: Wireshark Buildbot Reviewed-by: Gerald Combs --- docbook/CMakeLists.txt | 3 +- docbook/Makefile.common | 3 +- .../WSDG_chapter_userinterface.asciidoc | 210 +++++++++++++++ .../wsdg_src/WSDG_chapter_userinterface.xml | 254 ------------------ 4 files changed, 214 insertions(+), 256 deletions(-) create mode 100644 docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc delete mode 100644 docbook/wsdg_src/WSDG_chapter_userinterface.xml diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt index 2c03b72c2b..1431c00100 100644 --- a/docbook/CMakeLists.txt +++ b/docbook/CMakeLists.txt @@ -190,7 +190,7 @@ set(WSDG_FILES wsdg_generated_src/WSDG_chapter_quick_setup.xml wsdg_generated_src/WSDG_chapter_sources.xml wsdg_generated_src/WSDG_chapter_tools.xml - wsdg_src/WSDG_chapter_userinterface.xml + wsdg_generated_src/WSDG_chapter_userinterface.xml wsdg_generated_src/WSDG_chapter_works.xml wsdg_src/WSDG_meta_info.xml wsdg_generated_src/WSDG_preface.xml @@ -206,6 +206,7 @@ set(WSDG_ASCIIDOC_FILES wsdg_src/WSDG_chapter_quick_setup.asciidoc wsdg_src/WSDG_chapter_sources.asciidoc wsdg_src/WSDG_chapter_tools.asciidoc + wsdg_src/WSDG_chapter_userinterface.asciidoc wsdg_src/WSDG_chapter_works.asciidoc wsdg_src/WSDG_preface.asciidoc ) diff --git a/docbook/Makefile.common b/docbook/Makefile.common index c83c2a5874..362ce2a73a 100644 --- a/docbook/Makefile.common +++ b/docbook/Makefile.common @@ -167,7 +167,7 @@ WSDG_FILES = \ wsdg_src/WSDG_chapter_quick_setup.asciidoc \ wsdg_src/WSDG_chapter_sources.asciidoc \ wsdg_src/WSDG_chapter_tools.asciidoc \ - wsdg_src/WSDG_chapter_userinterface.xml \ + wsdg_src/WSDG_chapter_userinterface.asciidoc \ wsdg_src/WSDG_chapter_works.asciidoc \ wsdg_src/WSDG_meta_info.xml \ wsdg_src/WSDG_preface.asciidoc \ @@ -182,6 +182,7 @@ WSDG_GENERATED_SOURCE = \ wsdg_src/WSDG_chapter_quick_setup.xml \ wsdg_src/WSDG_chapter_sources.xml \ wsdg_src/WSDG_chapter_tools.xml \ + wsdg_src/WSDG_chapter_userinterface.xml \ wsdg_src/WSDG_chapter_works.xml \ wsdg_src/WSDG_preface.xml diff --git a/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc new file mode 100644 index 0000000000..1a9eb30d30 --- /dev/null +++ b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc @@ -0,0 +1,210 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[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: + +* 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 +the Wireshark development team: + +* Packetyzer (Win32 native interface, written in Delphi and released +under the GPL, see: http://www.paglo.com/opensource/packetyzer[]) + +* hethereal (web based frontend, not actively maintained and not +finished) + +This chapter is focused on the Wireshark frontend, and especially on +the GTK interface. + +[[ChUIGTK]] + +=== The GTK library + +.We're switching to Qt +[NOTE] +==== +This chapter describes the state of our stable release, which is based on GTK+. +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 +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. + +GTK is available for many different platforms including, but not limited to: +Unix/Linux, Mac OS X and Win32. It's the foundation of the famous GNOME desktop, +so the future development of GTK should be certain. GTK is implemented in plain +C (as is Wireshark itself), and available under the LGPL (Lesser General Public +License), making it free to used by commercial and noncommercial applications. + +There are other similar toolkits like wxWidgets which could also be used for +Wireshark. There's no "one and only" reason for or against any of these +toolkits. However, the decision towards GTK was made a long time ago :-) + +As of 2013 there are two major GTK versions available: + +[[ChUIGTK2x]] + +==== GTK Version 2.x + +GTK 2.x depends on the following libraries: + +* GObject (Object library. Basis for GTK and others) + +* GLib (A general-purpose utility library, not specific to graphical user + interfaces. GLib provides many useful data types, macros, type conversions, + string utilities, file utilities, a main loop abstraction, and so on.) + +* Pango (Pango is a library for internationalized text handling. It centers + around the PangoLayout object, representing a paragraph of text. Pango + provides the engine for GtkTextView, GtkLabel, GtkEntry, and other widgets + that display text.) + +* ATK (ATK is the Accessibility Toolkit. It provides a set of generic interfaces + allowing accessibility technologies to interact with a graphical user + interface. For example, a screen reader uses ATK to discover the text in an + interface and read it to blind users. GTK+ widgets have built-in support for + accessibility using the ATK framework.) + +* GdkPixbuf (This is a small library which allows you to create GdkPixbuf + ("pixel buffer") objects from image data or image files. Use a + GdkPixbuf in combination with GtkImage to display images.) + +* GDK (GDK is the abstraction layer that allows GTK+ to support multiple + windowing systems. GDK provides drawing and window system facilities on X11, + Windows, and the Linux framebuffer device.) + +[[ChUIGTK3x]] + +==== GTK Version 3.x + +Wireshark (as of version 1.10) has been ported to use the GTK3 library. + +GTK 3.x depends on the following libraries: + +(See GTK 2.x) + +[[ChUIGTKCompat]] + +==== Compatibility GTK versions + +The GTK library itself defines some values which makes it easy to distinguish +between the versions, e.g. +GTK_MAJOR_VERSION+ and +GTK_MINOR_VERSION+ will be +set to the GTK version at compile time inside the gtkversion.h header. + +[[ChUIGTKWeb]] + +==== GTK resources on the web + +You can find several resources about GTK. + +First of all, have a look at http://www.gtk.org[]. This +will be the first place to look at. If you want to develop GTK related +things for Wireshark, the most important place might be the GTK API +documentation at http://library.gnome.org/devel/gtk/stable/[]. + +Several mailing lists are available about GTK development, see +http://mail.gnome.org/mailman/listinfo[], the gtk-app-devel-list may be your +friend. + +As it's often done wrong: You should post a mail to *help* the developers +there instead of only complaining. Posting such a thing like "I don't like +your dialog, it looks ugly" won't be of much help. You might think about +what you dislike and describe why you dislike it and provide a suggestion +for a better way. + +[[ChUIGUIDocs]] + +=== GUI Reference documents + +Although the GUI development of Wireshark is platform independent, the +Wireshark development team tries to +follow the GNOME Human Interface Guidelines (HIG) where appropriate. +This is the case, because both GNOME and Wireshark are based on the GTK+ +toolkit and the GNOME HIG is excellently written and easy to understand. + +For further reference, see the following documents: + +* Android Design: +http://developer.android.com/design/index.html[] (Wireshark doesn't have a +mobile frontend but there is still useful information here) + +* GNOME Human Interface Guidelines: +http://library.gnome.org/devel/hig-book/stable/[] + +* The KDE Usability/HIG project: +http://techbase.kde.org/Projects/Usability/HIG[] + +* OS X Human Interface Guidelines: +https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/AppleHIGuidelines/Intro/Intro.html[] + +* Design apps for the Windows desktop: +http://msdn.microsoft.com/en-us/library/Aa511258.aspx[] + +[[ChUIGTKDialogs]] + +=== Adding/Extending Dialogs + +This is usually the main area for contributing new user interface features. + +XXX: add the various functions from gtk/dlg_utils.h + +[[ChUIGTKWidgetNamings]] + +=== Widget naming + +It seems to be common sense to name the widgets with some +descriptive trailing characters, like: + +* xy_lb = gtk_label_new(); + +* xy_cb = gtk_checkbox_new(); + +* XXX: add more examples + +However, this schema isn't used at all places inside the code. + +[[ChUIGTKPitfalls]] + +=== Common GTK programming pitfalls + +There are some common pitfalls in GTK programming. + +[[ChUIGTKShowAll]] + +==== Usage of gtk_widget_show() / gtk_widget_show_all() + +When a GTK widget is created it will be hidden by default. In order to +show it, a call to gtk_widget_show() has to be done. + + +It isn't necessary to do this for each and every widget created. A call +to gtk_widget_show_all() on the parent of all the widgets in question +(e.g. a dialog window) can be done, so all of its child widgets will +be shown too. + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ diff --git a/docbook/wsdg_src/WSDG_chapter_userinterface.xml b/docbook/wsdg_src/WSDG_chapter_userinterface.xml deleted file mode 100644 index 324d5b02b5..0000000000 --- a/docbook/wsdg_src/WSDG_chapter_userinterface.xml +++ /dev/null @@ -1,254 +0,0 @@ - - - - - User Interface - -
- Introduction - - Wireshark can be "logically" separated into the backend (dissecting of - protocols, file load/save, capturing, ...) and the frontend (the user - interface). However, there's currently no clear separation between - these two parts (no clear API definition), but this might change in the - future. - - - The following frontends are currently maintained by the Wireshark - development team: - - - Wireshark, GTK 2.x based - - - Wireshark, GTK 3.x based (Wireshark 1.10 and newer) - - - TShark, console based - - - There exist other Wireshark frontends, not developed nor - maintained by the Wireshark development team: - - - Packetyzer (Win32 native interface, written in Delphi and released - under the GPL, see: - ) - - - hethereal (web based frontend, not actively maintained and not - finished) - - - This chapter is focused on the Wireshark frontend, and especially on - the GTK specific things. - -
- -
- The GTK library - - Wireshark is based on the GTK toolkit, see: - 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. - - - GTK is available for a lot of different platforms including, but not - limited to: Unix/Linux, Mac OS X and Win32. It's the foundation of - the famous GNOME desktop, so the future development of GTK should be - certain. - GTK is implemented in plain C (as is Wireshark itself), and available under - the LGPL (Lesser General Public License), being free to used by - commercial and noncommercial applications. - - - There are other similar toolkits like Qt, wxwidgets, ..., which could - also be used for Wireshark. There's no "one and only" reason for or against - any of these toolkits. However, the decision towards GTK was made a - long time ago :-) - - - Currently [2013] there are two major GTK versions - available: - - - -
- GTK Version 2.x - - GTK 2.x depends on the following libraries: - - - GObject (Object library. Basis for GTK and others) - - - GLib (A general-purpose utility - library, not specific to graphical user interfaces. - GLib provides many useful data types, macros, type conversions, - string utilities, file utilities, a main loop abstraction, and so on.) - - - Pango (Pango is a library for internationalized text handling. It centers - around the #PangoLayout object, representing a paragraph of text. - Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and - other widgets that display text.) - - - ATK (ATK is the Accessibility Toolkit. It provides a set of generic - interfaces allowing accessibility technologies to interact with a - graphical user interface. For example, a screen reader uses ATK to - discover the text in an interface and read it to blind users. GTK+ - widgets have built-in support for accessibility using the ATK - framework.) - - - GdkPixbuf (This is a small library which allows you to create #GdkPixbuf - ("pixel buffer") objects from image data or image files. Use a - #GdkPixbuf in combination with #GtkImage to display images.) - - - GDK (GDK is the abstraction layer that allows GTK+ to support multiple - windowing systems. GDK provides drawing and window system facilities - on X11, Windows, and the Linux framebuffer device.) - - - -
- - -
- GTK Version 3.x - - Wireshark (as of version 1.10) has been ported to use the GTK3 library. - - - GTK 3.x depends on the following libraries: - - - (See GTK 2.x) - -
- - -
- Compatibility GTK versions - - The GTK library itself defines some values which makes it easy to - distinguish between the versions, e.g.: - GTK_MAJOR_VERSION and GTK_MINOR_VERSION - will be set to the GTK version at compile time inside the gtkversion.h header. - -
- -
- GTK resources on the web - - You can find several resources about GTK. - - - First of all, have a look at: as this - will be the first place to look at. If you want to develop GTK related - things for Wireshark, the most important place might be the GTK API - documentation at: . - - - Several mailing lists are available about GTK development, see , the gtk-app-devel-list - may be your friend. - - - As it's often done wrong: You should post a mail to *help* the developers - there instead of only complaining. Posting such a thing like "I don't like - your dialog, it looks ugly" won't be of much help. You might think about - what you dislike and describe why you dislike it and provide a suggestion - for a better way. - -
- -
- -
- GUI Reference documents - - Although the GUI development of Wireshark is platform independent, the - Wireshark development team tries to - follow the GNOME Human Interface Guidelines (HIG) where appropriate. - This is the case, because both GNOME and Wireshark are based on the GTK+ - toolkit and the GNOME HIG is excellently written and easy to understand. - - - For further reference, see the following documents: - - - GNOME Human Interface Guidelines at: - - - - KDE user interface related documents at: - - - - Win32 styleguides available at: - - - - -
- -
- Adding/Extending Dialogs - - This is usually the main area for contributing new user interface features. - - - XXX: add the various functions from gtk/dlg_utils.h - -
- -
- Widget naming - - It seems to be common sense to name the widgets with some - descriptive trailing characters, like: - - - xy_lb = gtk_label_new(); - - - xy_cb = gtk_checkbox_new(); - - - XXX: add more examples - - - However, this schema isn't used at all places inside the code. - -
- - -
- Common GTK programming pitfalls - - There are some common pitfalls in GTK programming. - - -
- Usage of gtk_widget_show() / gtk_widget_show_all() - - When a GTK widget is created it will be hidden by default. In order to - show it, a call to gtk_widget_show() has to be done. - - - It isn't necessary to do this for each and every widget created. A call - to gtk_widget_show_all() on the parent of all the widgets in question - (e.g. a dialog window) can be done, so all of its child widgets will - be shown too. - -
- -
- - -