docbook/wsdg_src/WSDG_chapter_userinterface.xml

   1 <!-- WSDG Chapter User Interface -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterUserInterface">
   5   <title>User Interface</title>
   6
   7   <section id="ChUIIntro">
   8         <title>Introduction</title>
   9         <para>
  10         Wireshark can be "logically" separated into the backend (dissecting of
  11         protocols, file load/save, capturing, ...) and the frontend (the user
  12         interface). However, there's currently no clear separation between
  13         these two parts (no clear API definition), but this might change in the
  14         future.
  15         </para>
  16         <para>
  17         The following frontends are currently maintained by the Wireshark
  18         development team:
  19         <itemizedlist>
  20           <listitem><para>
  21           Wireshark, GTK 2.x based
  22           </para></listitem>
  23           <listitem><para>
  24           TShark, console based
  25           </para></listitem>
  26           <listitem><para>
  27           Wireshark, GTK 1.x based (was removed with the Wireshark 1.2.0 release)
  28           </para></listitem>
  29         </itemizedlist>
  30         There exist other Wireshark frontends, not developed nor
  31         maintained by the Wireshark development team:
  32         <itemizedlist>
  33           <listitem><para>
  34           Packetyzer (Win32 native interface, written in Delphi and released
  35           under the GPL, see:
  36           <ulink url="http://www.paglo.com/opensource/packetyzer"/>)
  37           </para></listitem>
  38           <listitem><para>
  39           hethereal (web based frontend, not actively maintained and not
  40           finished)
  41           </para></listitem>
  42         </itemizedlist>
  43         This chapter is focused on the Wireshark frontend, and especially on
  44         the GTK specific things.
  45         </para>
  46   </section>
  47
  48         <section id="ChUIGTK">
  49         <title>The GTK library</title>
  50         <para>
  51         Wireshark is based on the GTK toolkit, see: <ulink url="http://www.gtk.org"/>
  52         for details. GTK is designed to hide the details of the underlying GUI in
  53         a platform independent way. As this is appreciated for a
  54         multiplatform tool, this has some drawbacks, as it will result in a
  55         somewhat "non native" look and feel.
  56         </para>
  57         <para>
  58         GTK is available for a lot of different platforms including, but not
  59         limited to: Unix/Linux, Mac OS X and Win32. It's the foundation of
  60         the famous GNOME desktop, so the future development of GTK should be
  61         certain.
  62         GTK is implemented in plain C (as is Wireshark itself), and available under
  63         the LGPL (Lesser General Public License), being free to used by
  64         commercial and noncommercial applications.
  65         </para>
  66         <para>
  67         There are other similar toolkits like Qt, wxwidgets, ..., which could
  68         also be used for Wireshark. There's no "one and only" reason for or against
  69         any of these toolkits. However, the decision towards GTK was made a
  70         long time ago :-)
  71         </para>
  72         <para>
  73         At the time this document is written there are two major GTK versions
  74         available:
  75         </para>
  76
  77
  78         <section id="ChUIGTK1x">
  79         <title>GTK Version 1.x</title>
  80         <para>
  81         Please note: After the creation of the 1.0 branch further development
  82         removed support for GTK 1.x!
  83         </para>
  84         <para>
  85         GTK 1.x was the first major release. Today there are 1.2.x and 1.3.x
  86         versions "in the wild", with only very limited differences in the API.
  87         </para>
  88         <para>
  89         Advantages (compared to GTK 2.x):
  90         <itemizedlist>
  91           <listitem><para>
  92           available on a lot of different platforms
  93           </para></listitem>
  94           <listitem><para>
  95           very stable as it's matured for quite a while now
  96           </para></listitem>
  97         </itemizedlist>
  98         Disadvantages:
  99         <itemizedlist>
 100           <listitem><para>
 101           the look and feel is a bit old-fashioned
 102           </para></listitem>
 103           <listitem><para>
 104           not recommended for future developments (last GTK 1.x release in 2004)
 105           </para></listitem>
 106         </itemizedlist>
 107         GTK 1.x depends on the following libraries:
 108         <itemizedlist>
 109           <listitem><para>
 110           GDK (GDK is the abstraction layer
 111           that allows GTK+ to support multiple
 112           windowing systems. GDK provides drawing and window system facilities
 113           on X11, Windows, and the Linux framebuffer device.)
 114           </para></listitem>
 115           <listitem><para>
 116           GLib (A general-purpose utility
 117           library, not specific to graphical user interfaces.
 118           GLib provides many useful data types, macros, type conversions,
 119           string utilities, file utilities, a main loop abstraction, and so on.)
 120           </para></listitem>
 121         </itemizedlist>
 122         GTK 1.x is working on GLib 1.x (typical for Unix like systems) or 2.x
 123         (typical for Win32 like systems).
 124         </para>
 125         <para>
 126         XXX: include Wireshark GTK1 screenshot
 127         </para>
 128         </section>
 129
 130
 131         <section id="ChUIGTK2x">
 132         <title>GTK Version 2.x</title>
 133         <para>
 134         Advantages (compared to GTK 1.x):
 135         <itemizedlist>
 136           <listitem><para>
 137           nice look and feel (compared to version 1.x)
 138           </para></listitem>
 139           <listitem><para>
 140           recommended for future developments
 141           </para></listitem>
 142           <listitem><para>
 143           stable (in productive code for years now)
 144           </para></listitem>
 145         </itemizedlist>
 146         Disadvantages:
 147         <itemizedlist>
 148           <listitem><para>
 149           not available on all platforms (compared to version 1.x)
 150           </para></listitem>
 151           <listitem><para>
 152           more dependencies compared to 1.x, see below
 153           </para></listitem>
 154         </itemizedlist>
 155         GTK 2.x depends on the following libraries:
 156         <itemizedlist>
 157           <listitem><para>
 158           GObject (Object library. Basis for GTK and others)
 159           </para></listitem>
 160           <listitem><para>
 161           GLib (A general-purpose utility
 162           library, not specific to graphical user interfaces.
 163           GLib provides many useful data types, macros, type conversions,
 164           string utilities, file utilities, a main loop abstraction, and so on.)
 165           </para></listitem>
 166           <listitem><para>
 167           Pango (Pango is a library for internationalized text handling. It centers
 168           around the #PangoLayout object, representing a paragraph of text.
 169           Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and
 170           other widgets that display text.)
 171           </para></listitem>
 172           <listitem><para>
 173           ATK (ATK is the Accessibility Toolkit. It provides a set of generic
 174           interfaces allowing accessibility technologies to interact with a
 175           graphical user interface. For example, a screen reader uses ATK to
 176           discover the text in an interface and read it to blind users. GTK+
 177           widgets have built-in support for accessibility using the ATK
 178           framework.)
 179           </para></listitem>
 180           <listitem><para>
 181           GdkPixbuf (This is a small library which allows you to create #GdkPixbuf
 182           ("pixel buffer") objects from image data or image files. Use a
 183           #GdkPixbuf in combination with #GtkImage to display images.)
 184           </para></listitem>
 185           <listitem><para>
 186           GDK (GDK is the abstraction layer that allows GTK+ to support multiple
 187           windowing systems. GDK provides drawing and window system facilities
 188           on X11, Windows, and the Linux framebuffer device.)
 189           </para></listitem>
 190         </itemizedlist>
 191         XXX: include Wireshark GTK2 screenshot
 192         </para>
 193         </section>
 194
 195         <section id="ChUIGTKCompat">
 196         <title>Compatibility GTK versions</title>
 197         <para>
 198         The GTK library itself defines some values which makes it easy to
 199         distinguish between the versions, e.g.:
 200         GTK_MAJOR_VERSION and GTK_MINOR_VERSION
 201         will be set to the GTK version at compile time inside the gtkversion.h header.
 202         </para>
 203         </section>
 204
 205         <section id="ChUIGTKWeb">
 206         <title>GTK resources on the web</title>
 207         <para>
 208         You can find several resources about GTK.
 209         </para>
 210         <para>
 211         First of all, have a look at: <ulink url="http://www.gtk.org"/> as this
 212         will be the first place to look at. If you want to develop GTK related
 213         things for Wireshark, the most important place might be the GTK API
 214         documentation at: <ulink url="http://library.gnome.org/devel/gtk/stable/"/>.
 215         </para>
 216         <para>
 217         Several mailing lists are available about GTK development, see <ulink
 218         url="http://mail.gnome.org/mailman/listinfo"/>, the gtk-app-devel-list
 219         may be your friend.
 220         </para>
 221   <para>
 222         As it's often done wrong: You should post a mail to *help* the developers
 223         there instead of only complaining. Posting such a thing like "I don't like
 224         your dialog, it looks ugly" won't be of much help. You might think about
 225         what you dislike and describe why you dislike it and provide a suggestion
 226         for a better way.
 227         </para>
 228         </section>
 229
 230         </section>
 231
 232         <section id="ChUIGUIDocs">
 233         <title>GUI Reference documents</title>
 234         <para>
 235         Although the GUI development of Wireshark is platform independent, the
 236         Wireshark development team tries to
 237         follow the GNOME Human Interface Guidelines (HIG) where appropriate.
 238         This is the case, because both GNOME and Wireshark are based on the GTK+
 239         toolkit and the GNOME HIG is excellently written and easy to understand.
 240         </para>
 241         <para>
 242         For further reference, see the following documents:
 243         <itemizedlist>
 244           <listitem><para>
 245           GNOME Human Interface Guidelines at:
 246           <ulink url="http://library.gnome.org/devel/hig-book/stable/"/>
 247           </para></listitem>
 248           <listitem><para>
 249           KDE user interface related documents at:
 250           <ulink url="http://developer.kde.org/documentation/standards/kde/style/basics/index.html"/>
 251           </para></listitem>
 252           <listitem><para>
 253           Win32 styleguides available at:
 254           <ulink url="http://msdn.microsoft.com/en-us/library/aa511258.aspx"/>
 255           </para></listitem>
 256         </itemizedlist>
 257         </para>
 258         </section>
 259
 260   <section id="ChUIGTKDialogs">
 261         <title>Adding/Extending Dialogs</title>
 262         <para>
 263         This is usually the main area for contributing new user interface features.
 264         </para>
 265         <para>
 266         XXX: add the various functions from gtk/dlg_utils.h
 267         </para>
 268   </section>
 269
 270   <section id="ChUIGTKWidgetNamings">
 271         <title>Widget naming</title>
 272         <para>
 273         It seems to be common sense to name the widgets with some
 274         descriptive trailing characters, like:
 275         <itemizedlist>
 276           <listitem><para>
 277           xy_lb = gtk_label_new();
 278           </para></listitem>
 279           <listitem><para>
 280           xy_cb = gtk_checkbox_new();
 281           </para></listitem>
 282           <listitem><para>
 283           XXX: add more examples
 284           </para></listitem>
 285         </itemizedlist>
 286         However, this schema isn't used at all places inside the code.
 287         </para>
 288   </section>
 289
 290
 291   <section id="ChUIGTKPitfalls">
 292         <title>Common GTK programming pitfalls</title>
 293         <para>
 294         There are some common pitfalls in GTK programming.
 295         </para>
 296
 297         <section id="ChUIGTKShowAll">
 298         <title>Usage of gtk_widget_show() / gtk_widget_show_all()</title>
 299         <para>
 300         When a GTK widget is created it will be hidden by default. In order to
 301         show it, a call to gtk_widget_show() has to be done.
 302         </para>
 303         <para>
 304         It isn't necessary to do this for each and every widget created. A call
 305         to gtk_widget_show_all() on the parent of all the widgets in question
 306         (e.g. a dialog window) can be done, so all of its child widgets will
 307         be shown too.
 308         </para>
 309         </section>
 310
 311   </section>
 312
 313 </chapter>
 314 <!-- End of WSDG Chapter User Interface -->