forked from osmocom/wireshark
b7f5f3171d
svn path=/trunk/; revision=31125
315 lines
10 KiB
XML
315 lines
10 KiB
XML
<!-- WSDG Chapter User Interface -->
|
|
<!-- $Id$ -->
|
|
|
|
<chapter id="ChapterUserInterface">
|
|
<title>User Interface</title>
|
|
|
|
<section id="ChUIIntro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
The following frontends are currently maintained by the Wireshark
|
|
development team:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Wireshark, GTK 2.x based
|
|
</para></listitem>
|
|
<listitem><para>
|
|
TShark, console based
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Wireshark, GTK 1.x based (was removed with the Wireshark 1.2.0 release)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
There exist other Wireshark frontends, not developed nor
|
|
maintained by the Wireshark development team:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Packetyzer (Win32 native interface, written in Delphi and released
|
|
under the GPL, see:
|
|
<ulink url="http://www.paglo.com/opensource/packetyzer"/>)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
hethereal (web based frontend, not actively maintained and not
|
|
finished)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
This chapter is focused on the Wireshark frontend, and especially on
|
|
the GTK specific things.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChUIGTK">
|
|
<title>The GTK library</title>
|
|
<para>
|
|
Wireshark is based on the GTK toolkit, see: <ulink url="http://www.gtk.org"/>
|
|
for details. GTK is designed to hide the details of the underlying GUI in
|
|
a platform independent way. As this is appreciated for a
|
|
multiplatform tool, this has some drawbacks, as it will result in a
|
|
somewhat "non native" look and feel.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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 :-)
|
|
</para>
|
|
<para>
|
|
At the time this document is written there are two major GTK versions
|
|
available:
|
|
</para>
|
|
|
|
|
|
<section id="ChUIGTK1x">
|
|
<title>GTK Version 1.x</title>
|
|
<para>
|
|
Please note: After the creation of the 1.0 branch further development
|
|
removed support for GTK 1.x!
|
|
</para>
|
|
<para>
|
|
GTK 1.x was the first major release. Today there are 1.2.x and 1.3.x
|
|
versions "in the wild", with only very limited differences in the API.
|
|
</para>
|
|
<para>
|
|
Advantages (compared to GTK 2.x):
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
available on a lot of different platforms
|
|
</para></listitem>
|
|
<listitem><para>
|
|
very stable as it's matured for quite a while now
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
Disadvantages:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
the look and feel is a bit old-fashioned
|
|
</para></listitem>
|
|
<listitem><para>
|
|
not recommended for future developments (last GTK 1.x release in 2004)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
GTK 1.x depends on the following libraries:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
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.)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
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.)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
GTK 1.x is working on GLib 1.x (typical for Unix like systems) or 2.x
|
|
(typical for Win32 like systems).
|
|
</para>
|
|
<para>
|
|
XXX: include Wireshark GTK1 screenshot
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="ChUIGTK2x">
|
|
<title>GTK Version 2.x</title>
|
|
<para>
|
|
Advantages (compared to GTK 1.x):
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
nice look and feel (compared to version 1.x)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
recommended for future developments
|
|
</para></listitem>
|
|
<listitem><para>
|
|
stable (in productive code for years now)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
Disadvantages:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
not available on all platforms (compared to version 1.x)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
more dependencies compared to 1.x, see below
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
GTK 2.x depends on the following libraries:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
GObject (Object library. Basis for GTK and others)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
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.)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
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.)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
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.)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
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.)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
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.)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
XXX: include Wireshark GTK2 screenshot
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChUIGTKCompat">
|
|
<title>Compatibility GTK versions</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChUIGTKWeb">
|
|
<title>GTK resources on the web</title>
|
|
<para>
|
|
You can find several resources about GTK.
|
|
</para>
|
|
<para>
|
|
First of all, have a look at: <ulink url="http://www.gtk.org"/> 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: <ulink url="http://library.gnome.org/devel/gtk/stable/"/>.
|
|
</para>
|
|
<para>
|
|
Several mailing lists are available about GTK development, see <ulink
|
|
url="http://mail.gnome.org/mailman/listinfo"/>, the gtk-app-devel-list
|
|
may be your friend.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="ChUIGUIDocs">
|
|
<title>GUI Reference documents</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
For further reference, see the following documents:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
GNOME Human Interface Guidelines at:
|
|
<ulink url="http://library.gnome.org/devel/hig-book/stable/"/>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
KDE user interface related documents at:
|
|
<ulink url="http://developer.kde.org/documentation/standards/kde/style/basics/index.html"/>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Win32 styleguides available at:
|
|
<ulink url="http://msdn.microsoft.com/en-us/library/aa511258.aspx"/>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChUIGTKDialogs">
|
|
<title>Adding/Extending Dialogs</title>
|
|
<para>
|
|
This is usually the main area for contributing new user interface features.
|
|
</para>
|
|
<para>
|
|
XXX: add the various functions from gtk/dlg_utils.h
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChUIGTKWidgetNamings">
|
|
<title>Widget naming</title>
|
|
<para>
|
|
It seems to be common sense to name the widgets with some
|
|
descriptive trailing characters, like:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
xy_lb = gtk_label_new();
|
|
</para></listitem>
|
|
<listitem><para>
|
|
xy_cb = gtk_checkbox_new();
|
|
</para></listitem>
|
|
<listitem><para>
|
|
XXX: add more examples
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
However, this schema isn't used at all places inside the code.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="ChUIGTKPitfalls">
|
|
<title>Common GTK programming pitfalls</title>
|
|
<para>
|
|
There are some common pitfalls in GTK programming.
|
|
</para>
|
|
|
|
<section id="ChUIGTKShowAll">
|
|
<title>Usage of gtk_widget_show() / gtk_widget_show_all()</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
<!-- End of WSDG Chapter User Interface -->
|