--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<HTML
+><HEAD
+><TITLE
+>How to handle events and use the graphical trace reading service</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
+REL="HOME"
+TITLE="Linux Trace Toolkit Viewer Developer Guide"
+HREF="index.html"><LINK
+REL="UP"
+TITLE="Linux Trace Toolkit Viewer Graphical Module Tutorial"
+HREF="c67.html"><LINK
+REL="PREVIOUS"
+TITLE="How to request background computation"
+HREF="x81.html"></HEAD
+><BODY
+CLASS="sect1"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>Linux Trace Toolkit Viewer Developer Guide</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="x81.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 3. Linux Trace Toolkit Viewer Graphical Module Tutorial</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+> </TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="sect1"
+><H1
+CLASS="sect1"
+><A
+NAME="AEN84"
+>3.5. How to handle events and use the graphical trace reading service</A
+></H1
+><P
+> The events that are delivered by the main window are defined in
+lttvwindow/lttvwindow.h. Let's describe them and their use in details. Remember
+that you can refer to the control flow viewer module as an example.
+</P
+><DIV
+CLASS="sect2"
+><H2
+CLASS="sect2"
+><A
+NAME="AEN87"
+>3.5.1. Module Related API</A
+></H2
+><P
+> A viewer plugin is, before anything, a plugin. As a dynamically loadable
+module, it thus has an init and a destroy function called whenever it is
+loaded/initialized and unloaded/destroyed. A graphical module depends on
+lttvwindow for construction of its viewer instances. In order to achieve
+this, it must register its constructor function to the main window along
+with button description or text menu entry description. A module keeps
+a list of every viewer that currently sits in memory so it can destroy
+them before the module gets unloaded/destroyed.
+</P
+><P
+> The contructor registration to the main windows adds button and menu
+entry to each main window, thus allowing instanciation of viewers.
+</P
+></DIV
+><DIV
+CLASS="sect2"
+><H2
+CLASS="sect2"
+><A
+NAME="AEN91"
+>3.5.2. Main Window</A
+></H2
+><P
+> The main window is a container that offers menus, buttons and a
+notebook. Some of those menus and buttons are part of the core of the
+main window, others are dynamically added and removed when modules are
+loaded/unloaded.
+</P
+><P
+> The notebook contains as much tabs as wanted. Each tab is linked with
+a set of traces (traceset). Each trace contains many tracefiles (one
+per cpu). A trace corresponds to a kernel being traced. A traceset
+corresponds to many traces read together. The time span of a traceset
+goes from the earliest start of all the traces to the latest end of all
+the traces.
+</P
+><P
+> Inside each tab are added the viewers. When they interact with the main
+window through the lttvwindow API, they affect the other viewers located
+in the same tab as they are.
+</P
+><P
+> The insertion of many viewers in a tab permits a quick look at all the
+information wanted in a glance. The main window does merge the read
+requests from all the viewers in the same tab in a way that every viewer
+will get exactly the events it asked for, while the event reading loop
+and state update are shared. It improves performance of events delivery
+to the viewers.
+</P
+></DIV
+><DIV
+CLASS="sect2"
+><H2
+CLASS="sect2"
+><A
+NAME="AEN97"
+>3.5.3. Viewer Instance Related API</A
+></H2
+><P
+> The lifetime of a viewer is as follows. The viewer constructor function
+is called each time an instance view is created (one subwindow of this
+viewer type is created by the user either by clicking on the menu item
+or the button corresponding to the viewer). Thereafter, the viewer gets
+hooks called for different purposes by the window containing it. These
+hooks are detailed below. It also has to deal with GTK Events. Finally,
+it can be destructed by having its top level widget unreferenced by the
+main window or by any GTK Event causing a "destroy-event" signal on the
+its top widget. Another possible way for it do be destroyed is if the
+module gets unloaded. The module unload function will have to emit a
+"destroy" signal on each top level widget of all instances of its viewers.
+</P
+></DIV
+><DIV
+CLASS="sect2"
+><H2
+CLASS="sect2"
+><A
+NAME="AEN100"
+>3.5.4. Notices from Main Window</A
+></H2
+><P
+></P
+><DIV
+CLASS="variablelist"
+><DL
+><DT
+>time_window</DT
+><DD
+><P
+>This is the time interval visible on the viewer's tab. Every
+ viewer that cares about being synchronised by respect to the
+ time with other viewers should register to this notification.
+ They should redraw all or part of their display when this
+ occurs.</P
+></DD
+><DT
+>traceset</DT
+><DD
+><P
+>This notification is called whenever a trace is added/removed
+ from the traceset. As it affects all the data displayed by the
+ viewer, it sould redraw itself totally.</P
+></DD
+><DT
+>filter</DT
+><DD
+><P
+>This feature has not been implemented yet.</P
+></DD
+><DT
+>current_time</DT
+><DD
+><P
+>Being able to zoom nearer a specific time or highlight a specific
+ time on every viewer in synchronicity implies that the viewer
+ has to shown a visual sign over the drawing or select an event
+ when it receives this notice. It should also inform the main
+ window with the appropriate report API function when a user
+ selects a specific time as being the current time.</P
+></DD
+><DT
+>dividor</DT
+><DD
+><P
+>This notice links the positions of the horizontal dividors
+ between the graphic display zone of every viewer and their Y axis,
+ typically showing processes, cpus, ...</P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="sect2"
+><H2
+CLASS="sect2"
+><A
+NAME="AEN123"
+>3.5.5. Reporting Changes to the Main Window</A
+></H2
+><P
+> In most cases, the enclosing window knows about updates such as described
+in the Notification section higher. There are a few cases, however, where
+updates are caused by actions known by a view instance. For example,
+clicking in a view may update the current time; all viewers within
+the same window must be told about the new current time to change the
+currently highlighted time point. A viewer reports such events by calling
+lttvwindow_report_current_time on its lttvwindow. The lttvwindow will
+consequently call current_time_notify for each of its contained viewers.
+</P
+><P
+> Available report methods are :
+<P
+></P
+><UL
+><LI
+><P
+> lttvwindow_report_time_window : reports the new time window.
+</P
+></LI
+><LI
+><P
+> lttvwindow_report_current_time : reports the new current time.
+</P
+></LI
+><LI
+><P
+> lttvwindow_report_dividor : reports the new horizontal dividor's position.
+</P
+></LI
+></UL
+>
+</P
+></DIV
+><DIV
+CLASS="sect2"
+><H2
+CLASS="sect2"
+><A
+NAME="AEN134"
+>3.5.6. Requesting Events to Main Window</A
+></H2
+><P
+> Events can be requested by passing a EventsRequest structure to the main
+window. They will be delivered later when the next g_idle functions
+will be called. Event delivery is done by calling the event hook for
+this event ID, or the main event hooks. A pointer to the EventsRequest
+structure is passed as hook_data to the event hooks of the viewers.
+</P
+><P
+> EventsRequest consists in
+<P
+></P
+><UL
+><LI
+><P
+> a pointer to the viewer specific data structure
+</P
+></LI
+><LI
+><P
+> a start timestamp or position
+</P
+></LI
+><LI
+><P
+> a stop_flag, ending the read process when set to TRUE
+</P
+></LI
+><LI
+><P
+> a end timestamp and/or position and/or number of events to read
+</P
+></LI
+><LI
+><P
+> hook lists to call for traceset/trace/tracefile begin and end, and for each
+ event (event hooks and event_by_id hooks).
+</P
+></LI
+></UL
+>
+</P
+><P
+> The main window will deliver events for every EventRequests it has
+pending through an algorithm that guarantee that all events requested,
+and only them, will be delivered to the viewer between the call of the
+tracefile_begin hooks and the call of the tracefile_end hooks.
+</P
+><P
+> If a viewer wants to stop the event request at a certain point inside the
+event hooks, it has to set the stop_flag to TRUE and return TRUE from the
+hook function. Then return value will stop the process traceset. Then,
+the main window will look for the stop_flag and remove the EventRequests
+from its lists, calling the process_traceset_end for this request (it
+removes hooks from the context and calls the after hooks).
+</P
+><P
+> It no stop_flag is risen, the end timestamp, end position or number
+of events to read has to be reached to determine the end of the
+request. Otherwise, the end of traceset does determine it.
+</P
+></DIV
+><DIV
+CLASS="sect2"
+><H2
+CLASS="sect2"
+><A
+NAME="AEN152"
+>3.5.7. GTK Events</A
+></H2
+><DIV
+CLASS="sect3"
+><H3
+CLASS="sect3"
+><A
+NAME="AEN154"
+>3.5.7.1. Events and Signals</A
+></H3
+><P
+> GTK is quite different from the other graphical toolkits around
+there. The main difference resides in that there are many X Windows
+inside one GtkWindow, instead of just one. That means that X events are
+delivered by the glib main loop directly to the widget corresponding to
+the GdkWindow affected by the X event.
+</P
+><P
+> Event delivery to a widget emits a signal on that widget. Then, if a
+handler is connected to this widget's signal, it will be executed. There
+are default handlers for signals, connected at class instantiation
+time. There is also the possibility to connect other handlers to these
+signals, which is what should be done in most cases when a viewer needs
+to interact with X in any way.
+</P
+><P
+> Signal emission and propagation is described there :
+
+<P
+></P
+><UL
+><LI
+><P
+> http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
+</P
+></LI
+></UL
+>
+</P
+><P
+> For further information on the GTK main loop (now a wrapper over glib main loop)
+see :
+
+<P
+></P
+><UL
+><LI
+><P
+> http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
+</P
+></LI
+><LI
+><P
+> http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
+</P
+></LI
+></UL
+>
+</P
+><P
+> For documentation on event handling in GTK/GDK, see :
+
+<P
+></P
+><UL
+><LI
+><P
+> http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
+</P
+></LI
+><LI
+><P
+> http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
+</P
+></LI
+></UL
+>
+</P
+><P
+> Signals can be connected to handlers, emitted, propagated, blocked,
+stopped. See :
+
+<P
+></P
+><UL
+><LI
+><P
+> http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
+</P
+></LI
+></UL
+>
+</P
+></DIV
+><DIV
+CLASS="sect3"
+><H3
+CLASS="sect3"
+><A
+NAME="AEN178"
+>3.5.7.2. The "expose_event"</A
+></H3
+><P
+> Provides the exposed region in the GdkEventExpose structure.
+</P
+><P
+> There are two ways of dealing with exposures. The first one is to directly
+draw on the screen and the second one is to draw in a pixmap buffer,
+and then to update the screen when necessary.
+</P
+><P
+> In the first case, the expose event will be responsible for registering
+hooks to process_traceset and require time intervals to the main
+window. So, in this scenario, if a part of the screen is damaged, the
+trace has to be read to redraw the screen.
+</P
+><P
+> In the second case, with a pixmap buffer, the expose handler is only
+responsible of showing the pixmap buffer on the screen. If the pixmap
+buffer has never been filled with a drawing, the expose handler may ask
+for it to be filled.
+</P
+><P
+> The interest of using events request to the main window instead of reading
+the events directly from the trace comes from the fact that the main
+window does merge requests from the different viewers in the same tab so
+that the read loop and the state update is shared. As viewers will, in
+the common scenario, request the same events, only one pass through the
+trace that will call the right hooks for the right intervals will be done.
+</P
+><P
+> When the traceset read is over for a events request, the traceset_end
+hook is called. It has the responsibility of finishing the drawing if
+some parts still need to be drawn and to show it on the screen (if the
+viewer uses a pixmap buffer).
+</P
+><P
+> It can add dotted lines and such visual effects to enhance the user's
+experience.
+</P
+></DIV
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="x81.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="index.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+> </TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>How to request background computation</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="c67.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+> </TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / lttv.git / blobdiff