docbook/wsdg_src/WSDG_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" seperated into the backend (dissecting of
  11         protocols, file load/save, capturing, ...) and the frontend (the user
  12         interface). However, there's currently no clear seperation 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 1.x based
  22           </para></listitem>
  23           <listitem><para>
  24           Wireshark, GTK 2.x based
  25           </para></listitem>
  26           <listitem><para>
  27           TShark, console based
  28           </para></listitem>
  29         </itemizedlist>
  30         There are other Wireshark frontends existing, not developped 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.networkchemistry.com/products/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 focussed 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
  53         details. GTK is designed to hide the details of the underlying GUI in
  54         a platform independant way. As this is appreciated for a
  55         multiplatform tool, this has some drawbacks, as it will result in a
  56         somewhat "non native" look and feel. For example: on Win32, the "File
  57         open" dialog of Wireshark looks very different compared to the native
  58         Win32 dialog the Win32 users are used to see.
  59         </para>
  60         <para>
  61         GTK is available for a lot of different platforms including, but not
  62         limited, to: Unix/Linux, Mac OS X and Win32. It's the foundation of
  63         the famous GNOME desktop, so the future development of GTK should be
  64         certain.
  65         GTK is implemented in plain C (as Wireshark itself), and available under
  66         the LGPL (Lesser General Public License), being free to used by
  67         commercial and noncommercial applications.
  68         </para>
  69         <para>
  70         There are other similar toolkits like Qt, wxwidgets, ..., which could
  71         also
  72         be used for Wireshark. There's no "one and only" reason for or against
  73         any of these toolkits. However, the decision towards GTK was made a
  74         long time ago :-)
  75         </para>
  76         <para>
  77         At the time this document is written there are two major GTK versions
  78         available:
  79         </para>
  80
  81
  82         <section id="ChUIGTK1x">
  83         <title>GTK Version 1.x</title>
  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 limitted 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 oldfashioned
 102           </para></listitem>
 103           <listitem><para>
 104           not recommended for future developments
 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         </itemizedlist>
 143         Disadvantages:
 144         <itemizedlist>
 145           <listitem><para>
 146           not available on all platforms (compared to version 1.x)
 147           </para></listitem>
 148           <listitem><para>
 149           maybe a bit less stable compared to version 1.x (but should be
 150           production stable too)
 151           </para></listitem>
 152           <listitem><para>
 153           more dependencies compared to 1.x, see below
 154           </para></listitem>
 155         </itemizedlist>
 156         GTK 2.x depends on the following libraries:
 157         <itemizedlist>
 158           <listitem><para>
 159           GObject (Object library. Basis for GTK and others)
 160           </para></listitem>
 161           <listitem><para>
 162           GLib (A general-purpose utility
 163           library, not specific to graphical user interfaces.
 164           GLib provides many useful data types, macros, type conversions,
 165           string utilities, file utilities, a main loop abstraction, and so on.)
 166           </para></listitem>
 167           <listitem><para>
 168           Pango (Pango is a library for internationalized text handling. It centers
 169           around the #PangoLayout object, representing a paragraph of text.
 170           Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and
 171           other widgets that display text.)
 172           </para></listitem>
 173           <listitem><para>
 174           ATK (ATK is the Accessibility Toolkit. It provides a set of generic
 175           interfaces allowing accessibility technologies to interact with a
 176           graphical user interface. For example, a screen reader uses ATK to
 177           discover the text in an interface and read it to blind users. GTK+
 178           widgets have built-in support for accessibility using the ATK
 179           framework.)
 180           </para></listitem>
 181           <listitem><para>
 182           GdkPixbuf (This is a small library which allows you to create #GdkPixbuf
 183           ("pixel buffer") objects from image data or image files. Use a
 184           #GdkPixbuf in combination with #GtkImage to display images.)
 185           </para></listitem>
 186           <listitem><para>
 187           GDK (GDK is the abstraction layer that allows GTK+ to support multiple
 188           windowing systems. GDK provides drawing and window system facilities
 189           on X11, Windows, and the Linux framebuffer device.)
 190           </para></listitem>
 191         </itemizedlist>
 192         XXX: include Wireshark GTK2 screenshot
 193         </para>
 194         </section>
 195
 196         <section id="ChUIGTKCompat">
 197         <title>Compatibility between 1.x and 2.x</title>
 198         <para>
 199         The GTK library itself defines some values which makes it easy to
 200         distinguish between the versions, e.g.:
 201         GTK_MAJOR_VERSION GTK_MINOR_VERSION
 202         will be set to the GTK version at compile time somewhere inside the
 203         gtk.h headers.
 204         </para>
 205         <para>
 206         There are some common compatibility issues in Wireshark between the two
 207         versions.
 208         </para>
 209         <para>
 210         Most of them (the more simple ones) are collected in
 211         gtk/compat_macros.h and can be used in an version independant manner.
 212         </para>
 213         <para>
 214         However, there are major differences between the two versions, making
 215         it necessary to distinct between them, like:
 216         <programlisting>
 217 <![CDATA[
 218 #if GTK_MAJOR_VERSION >= 2
 219    ...
 220 #else
 221    ...
 222 #endif]]>
 223 </programlisting>
 224         </para>
 225         </section>
 226
 227         <section id="ChUIGTKWeb">
 228         <title>GTK resources on the web</title>
 229         <para>
 230         You can find several resources about GTK.
 231         </para>
 232         <para>
 233         First of all, have a look at: <ulink url="http://www.gtk.org"/> as this
 234         will be the first place to look at. If you want to develop GTK related
 235         things for Wireshark, the most important place might
 236         be the GTK API documentation at: <ulink url="http://gtk.org/api/"/>.
 237         </para>
 238         <para>
 239         Several mailing lists are available about GTK development, see <ulink
 240         url="http://gtk.org/mailinglists.html"/>, the gtk-app-devel-list
 241         may be you friend.
 242         </para>
 243         <para>
 244         Theres no Win32 specific GTK mailing list. If you want to post
 245         a Win32 specific problem (e.g. a problem in the GtkFileChooser dialog)
 246         and you are sure that it's really Win32 specific, you
 247         could send it to GIMPwin-users at <ulink
 248         url="http://www.gimp.org/mail_lists.html"/>.
 249         </para>
 250         <para>
 251         As it's often done wrong: You should post a mail to *help* the developers
 252         there instead of only complaining. Posting such a thing like "I don't like
 253         your dialog, it looks ugly" won't be much helpful. You might think about
 254         what you dislike and describe why you dislike it and a suggestion for a
 255         better way.
 256         </para>
 257         </section>
 258
 259         </section>
 260
 261         <section id="ChUIGUIDocs">
 262         <title>GUI Reference documents</title>
 263         <para>
 264         Although the GUI development of Wireshark is platform independant, the
 265         Wireshark development team tries to
 266         follow the GNOME Human Interface Guidelines (HIG) where appropriate.
 267         This is the case, because both GNOME and Wireshark are based on the GTK+
 268         toolkit and the GNOME HIG is excellently written and easy to understand.
 269         </para>
 270         <para>
 271         For further reference, see the following documents:
 272         <itemizedlist>
 273           <listitem><para>
 274           GNOME Human Interface Guidelines at:
 275           <ulink url="http://developer.gnome.org/projects/gup/hig/"/>
 276           </para></listitem>
 277           <listitem><para>
 278           KDE user interface related documents at:
 279           <ulink url="http://developer.kde.org/documentation/library/ui.html"/>
 280           </para></listitem>
 281           <listitem><para>
 282           Win32 XXX - where are good Win32 styleguides available?
 283           </para></listitem>
 284         </itemizedlist>
 285         </para>
 286         </section>
 287
 288   <section id="ChUIGTKDialogs">
 289         <title>Adding/Extending Dialogs</title>
 290         <para>
 291         This is usually the main area for contributing new user interface features.
 292         </para>
 293         <para>
 294         XXX: add the various functions from gtk/dlg_utils.h
 295         </para>
 296   </section>
 297
 298   <section id="ChUIGTKWidgetNamings">
 299         <title>Widget naming</title>
 300         <para>
 301         It seems to become common sense, to name the widgets with some
 302         descriptive trailing, like:
 303         <itemizedlist>
 304           <listitem><para>
 305           xy_lb = gtk_label_new();
 306           </para></listitem>
 307           <listitem><para>
 308           xy_cb = gtk_checkbox_new();
 309           </para></listitem>
 310           <listitem><para>
 311           XXX: add more examples
 312           </para></listitem>
 313         </itemizedlist>
 314         However, this schema isn't used at all places inside the code.
 315         </para>
 316   </section>
 317
 318
 319   <section id="ChUIGTKPitfalls">
 320         <title>Common GTK programming pitfalls</title>
 321         <para>
 322         There are some common pitfalls in GTK programming.
 323         </para>
 324
 325         <section id="ChUIGTKShowAll">
 326         <title>Usage of gtk_widget_show() / gtk_widget_show_all()</title>
 327         <para>
 328         When a GTK widget is created it will be hidden by default. In order to
 329         show it, a call to gtk_widget_show() has to be done.
 330         </para>
 331         <para>
 332         It isn't necessary to do this for each and every widget created. A call
 333         to
 334         gtk_widget_show_all() on the parent of all the widgets in question
 335         (e.g. a dialog window) can be done, so all of it's child widgets will
 336         be shown too.
 337         </para>
 338         </section>
 339
 340   </section>
 341
 342 </chapter>
 343 <!-- End of WSDG Chapter User Interface -->