1 /* This file is part of the Linux Trace Toolkit Graphic User Interface
2 * Copyright (C) 2003-2004 Xiangxiu Yang, Mathieu Desnoyers
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License Version 2 as
6 * published by the Free Software Foundation;
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
20 This file is what every viewer plugin writer should refer to.
25 A viewer plugin is, before anything, a plugin. As a dynamically loadable
26 module, it thus has an init and a destroy function called whenever it is
27 loaded/initialized and unloaded/destroyed. A graphical module depends on
28 lttvwindow for construction of its viewer instances. In order to achieve this,
29 it must register its constructor function to the main window along with
30 button description or text menu entry description. A module keeps a list of
31 every viewer that currently sits in memory so it can destroy them before the
32 module gets unloaded/destroyed.
35 Viewer Instance Related API
37 The lifetime of a viewer is as follows. The viewer constructor function is
38 called each time an instance view is created (one subwindow of this viewer
39 type is created by the user either by clicking on the menu item or the button
40 corresponding to the viewer). Thereafter, the viewer gets hooks called for
41 different purposes by the window containing it. These hooks are detailed
42 below. It also has to deal with GTK Events. Finally, it can be destructed by
43 having its top level widget unreferenced by the main window or by any
44 GTK Event causing a "destroy-event" signal on the its top widget. Another
45 possible way for it do be destroyed is if the module gets unloaded. The module
46 unload function will have to emit a "destroy" signal on each top level widget
47 of all instances of its viewers.
50 Notices from Main Window
52 time_window : This is the time interval visible on the viewer's tab. Every
53 viewer that cares about being synchronised by respect to the
54 time with other viewers should register to this notification.
55 They should redraw all or part of their display when this occurs.
57 traceset : This notification is called whenever a trace is added/removed
58 from the traceset. As it affects all the data displayed by the
59 viewer, it sould redraw itself totally.
61 filter : FIXME : describe..
63 current_time: Being able to zoom nearer a specific time or highlight a specific
64 time on every viewer in synchronicity implies that the viewer
65 has to shown a visual sign over the drawing or select an event
66 when it receives this notice. It should also inform the main
67 window with the appropriate report API function when a user
68 selects a specific time as being the current time.
70 dividor : This notice links the positions of the horizontal dividors
71 between the graphic display zone of every viewer and their Y axis,
72 typically showing processes, cpus, ...
75 FIXME : Add background computation explanation here
76 background_init: prepare for background computation (comes after show_end).
77 process_trace for background: done in small chunks in gtk_idle, hooks called.
78 background_end: remove the hooks and perhaps update the window.
81 Reporting Changes to the Main Window
83 In most cases, the enclosing window knows about updates such as described in the
84 Notification section higher. There are a few cases, however, where updates are
85 caused by actions known by a view instance. For example, clicking in a view may
86 update the current time; all viewers within the same window must be told about
87 the new current time to change the currently highlighted time point. A viewer
88 reports such events by calling lttvwindow_report_current_time on its lttvwindow.
89 The lttvwindow will consequently call current_time_notify for each of its
93 Available report methods are :
95 lttvwindow_report_status : reports the text of the status bar.
96 lttvwindow_report_time_window : reports the new time window.
97 lttvwindow_report_current_time : reports the new current time.
98 lttvwindow_report_dividor : reports the new horizontal dividor's position.
99 lttvwindow_report_focus : One on the widgets in the viewer has the keyboard's
104 Requesting Events to Main Window
106 Events can be requested by passing a EventsRequest structure to the main window.
107 They will be delivered later when the next g_idle functions will be called.
108 Event delivery is done by calling the middle hook for this event ID, or the
111 EventsRequest consists in
112 - a start timestamp or position
113 - a end timestamp and/or position and/or number of events to read
114 - hook lists to call for traceset/trace/tracefile begin and end, and for each
117 The main window will deliver events for every EventRequests it has pending
118 through an algorithm that guarantee that all events requested, and only them,
119 will be delivered to the viewer between the call of the tracefile_begin hooks
120 and the call of the tracefile_end hooks.
129 GTK is quite different from the other graphical toolkits around there. The main
130 difference resides in that there are many X Windows inside one GtkWindow,
131 instead of just one. That means that X events are delivered by the glib main
132 loop directly to the widget corresponding to the GdkWindow affected by the X
135 Event delivery to a widget emits a signal on that widget. Then, if a handler
136 is connected to this widget's signal, it will be executed. There are default
137 handlers for signals, connected at class instantiation time. There is also
138 the possibility to connect other handlers to these signals, which is what
139 should be done in most cases when a viewer needs to interact with X in any
144 Signal emission and propagation is described there :
146 http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
148 For further information on the GTK main loop (now a wrapper over glib main loop)
151 http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
152 http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
155 For documentation on event handling in GTK/GDK, see :
157 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
158 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
161 Signals can be connected to handlers, emitted, propagated, blocked,
164 http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
171 Provides the exposed region in the GdkEventExpose structure.
173 There are two ways of dealing with exposures. The first one is to directly draw
174 on the screen and the second one is to draw in a pixmap buffer, and then to
175 update the screen when necessary.
177 In the first case, the expose event will be responsible for registering hooks to
178 process_traceset and require time intervals to the main window. So, in this
179 scenario, if a part of the screen is damaged, the trace has to be read to
182 In the second case, with a pixmap buffer, the expose handler is only responsible
183 of showing the pixmap buffer on the screen. If the pixmap buffer has never
184 been filled with a drawing, the expose handler may ask for it to be filled.
186 It can add dotted lines and such visual effects to enhance the user's
190 FIXME : explain other important events
198 * \brief API used by the graphical viewers to interact with their top window.
200 * Main window (lttvwindow module) is the place to contain and display viewers.
201 * Viewers (lttv plugins) interact with main window through this API.
202 * This header file should be included in each graphic module.
208 #include <lttv/hook.h>
209 #include <lttvwindow/common.h>
210 #include <lttv/stats.h>
211 //FIXME (not ready yet) #include <lttv/filter.h>
214 /* Module Related API */
217 /* constructor a the viewer */
218 //FIXME explain LttvTracesetSelector and key
219 typedef GtkWidget
* (*lttvwindow_viewer_constructor
)
220 (MainWindow
* main_window
, LttvTracesetSelector
* s
, char *key
);
224 * Function to register a view constructor so that main window can generate
225 * a toolbar item for the viewer in order to generate a new instance easily.
227 * It should be called by init function of the module.
229 * @param pixmap Image shown on the toolbar item.
230 * @param tooltip tooltip of the toolbar item.
231 * @param view_constructor constructor of the viewer.
234 void lttvwindow_register_toolbar
237 lttvwindow_viewer_constructor view_constructor
);
241 * Function to unregister the viewer's constructor, release the space
242 * occupied by pixmap, tooltip and constructor of the viewer.
244 * It will be called when a module is unloaded.
246 * @param view_constructor constructor of the viewer.
249 void lttvwindow_unregister_toolbar
250 (lttvwindow_viewer_constructor view_constructor
);
254 * Function to register a view constructor so that main window can generate
255 * a menu item for the viewer in order to generate a new instance easily.
257 * It will be called by init function of the module.
259 * @param menu_path path of the menu item.
260 * @param menu_text text of the menu item.
261 * @param view_constructor constructor of the viewer.
264 void lttvwindow_register_menu(char *menu_path
,
266 lttvwindow_viewer_constructor view_constructor
);
270 * Function to unregister the viewer's constructor, release the space
271 * occupied by menu_path, menu_text and constructor of the viewer.
273 * It will be called when a module is unloaded.
275 * @param view_constructor constructor of the viewer.
278 void lttvwindow_unregister_menu(lttvwindow_viewer_constructor view_constructor
);
282 /* Viewer Instance Related API */
285 * Structure used as hook_data for the time_window_notify hook.
287 typedef struct _TimeWindowNotifyData
{
288 TimeWindow
*new_time_window
;
289 TimeWindow
*old_time_window
;
290 } TimeWindowNotifyData
;
294 * Function to register a hook function that will be called by the main window
295 * when the time interval needs to be updated.
297 * This register function is typically called by the constructor of the viewer.
299 * @param main_win the main window the viewer belongs to.
300 * @param hook hook that sould be called by the main window when the time
301 * interval changes. This hook function takes a
302 * TimeWindowNotifyData* as call_data.
303 * @param hook_data hook data associated with the hook function. It will
304 * be typically a pointer to the viewer's data structure.
307 void lttvwindow_register_time_window_notify(MainWindow
*main_win
,
313 * Function to unregister the time_window notification hook.
315 * This unregister function is typically called by the destructor of the viewer.
317 * @param main_win the main window the viewer belongs to.
318 * @param hook hook that sould be called by the main window when the time
319 * interval changes. This hook function takes a
320 * TimeWindowNotifyData* as call_data.
321 * @param hook_data hook data associated with the hook function. It will
322 * be typically a pointer to the viewer's data structure.
325 void lttvwindow_unregister_time_window_notify(MainWindow
*main_win
,
331 * Function to register a hook function that will be called by the main window
332 * when the traceset is changed. That means that the viewer must redraw
333 * itself completely or check if it's affected by the particular change to the
336 * This register function is typically called by the constructor of the viewer.
338 * @param main_win the main window the viewer belongs to.
339 * @param hook hook that should be called whenever a change to the traceset
340 * occurs. The call_data of this hook is a NULL pointer.
341 * @param hook_data hook data associated with the hook function. It will
342 * be typically a pointer to the viewer's data structure.
345 void lttvwindow_register_traceset_notify(MainWindow
*main_win
,
351 * Function to unregister the traceset_notify hook.
353 * @param main_win the main window the viewer belongs to.
354 * @param hook hook that should be called whenever a change to the traceset
355 * occurs. The call_data of this hook is a NULL pointer.
356 * @param hook_data hook data associated with the hook function. It will
357 * be typically a pointer to the viewer's data structure.
360 void lttvwindow_unregister_traceset_notify(MainWindow
*main_win
,
366 * Function to register a hook function for a viewer to set/update its
369 * FIXME : Add information about what a filter is as seen from a viewer and how
372 * This register function is typically called by the constructor of the viewer.
374 * @param main_win the main window the viewer belongs to.
375 * @param hook hook function called by the main window when a filter change
377 * @param hook_data hook data associated with the hook function. It will
378 * be typically a pointer to the viewer's data structure.
381 void lttvwindow_register_filter_notify(MainWindow
*main_win
,
387 * Function to unregister a viewer's hook function which is used to
388 * set/update the filter of the viewer.
390 * This unregistration is called by the destructor of the viewer.
392 * @param main_win the main window the viewer belongs to.
393 * @param hook hook function called by the main window when a filter change
395 * @param hook_data hook data associated with the hook function. It will
396 * be typically a pointer to the viewer's data structure.
399 void lttvwindow_unregister_filter_notify(MainWindow
* main_win
,
405 * Function to register a hook function for a viewer to set/update its
408 * @param main_win the main window the viewer belongs to.
409 * @param hook hook function of the viewer that updates the current time. The
410 * call_data is a LttTime* representing the new current time.
411 * @param hook_data hook data associated with the hook function. It will
412 * be typically a pointer to the viewer's data structure.
415 void lttvwindow_register_current_time_notify(MainWindow
*main_win
,
421 * Function to unregister a viewer's hook function which is used to
422 * set/update the current time of the viewer.
423 * @param main_win the main window the viewer belongs to.
424 * @param hook hook function of the viewer that updates the current time. The
425 * call_data is a LttTime* representing the new current time.
426 * @param hook_data hook data associated with the hook function. It will
427 * be typically a pointer to the viewer's data structure.
430 void lttvwindow_unregister_current_time_notify(MainWindow
*main_win
,
436 * Function to register a hook function for a viewer to set/update the
437 * dividor of the hpane. It provides a way to make the horizontal
438 * dividors of all the viewers linked together.
440 * @param main_win the main window the viewer belongs to.
441 * @param hook hook function of the viewer that will be called whenever a
442 * dividor changes in another viewer. The call_data of this hook
443 * is a gint*. The value of the integer is the new position of the
445 * @param hook_data hook data associated with the hook function. It will
446 * be typically a pointer to the viewer's data structure.
449 void lttvwindow_register_dividor(MainWindow
*main_win
,
455 * Function to unregister a viewer's hook function which is used to
456 * set/update hpane's dividor of the viewer.
458 * @param main_win the main window the viewer belongs to.
459 * @param hook hook function of the viewer that will be called whenever a
460 * dividor changes in another viewer. The call_data of this hook
461 * is a gint*. The value of the integer is the new position of the
463 * @param hook_data hook data associated with the hook function. It will
464 * be typically a pointer to the viewer's data structure.
467 void lttvwindow_unregister_dividor(MainWindow
*main_win
,
474 * This method reports the information to show on the status bar in the
477 * @param main_win the main window the viewer belongs to.
478 * @param info the message which will be shown in the status bar.
481 void lttvwindow_report_status(MainWindow
*main_win
, const char *info
);
485 * Function to set the time interval of the current tab.a
487 * @param main_win the main window the viewer belongs to.
488 * @param time_interval pointer to the time interval value.
491 void lttvwindow_report_time_window(MainWindow
*main_win
,
492 const TimeWindow
*time_window
);
495 * Function to set the current time/event of the current tab.
496 * It will be called by a viewer's signal handle associated with
497 * the button-release-event signal
498 * @param main_win the main window the viewer belongs to.
499 * @param time a pointer where time is stored.
502 void lttvwindow_report_current_time(MainWindow
*main_win
,
503 const LttTime
*time
);
507 * Function to set the position of the hpane's dividor (viewer).
508 * It will typically be called by a viewer's signal handle associated
509 * with the motion_notify_event event/signal.
511 * @param main_win the main window the viewer belongs to.
512 * @param position position of the hpane's dividor.
515 void lttvwindow_report_dividor(MainWindow
*main_win
, gint position
);
518 * Function to set the focused viewer of the tab.
519 * It will be called by a viewer's signal handle associated with
520 * the grab_focus signal of all widgets in the viewer.
522 * @param main_win the main window the viewer belongs to.
523 * @param top_widget the top widget containing all the other widgets of the
526 void lttvwindow_report_focus(MainWindow
*main_win
,
527 GtkWidget
*top_widget
);
531 /* Structure sent to the time request hook */
532 /* Value considered as empty */
533 typedef struct _EventsRequest
{
534 LttTime start_time
, /* Unset : { 0, 0 } */
535 LttvTracesetContextPosition start_position
, /* Unset : num_traces = 0 */
536 LttTime end_time
, /* Unset : { 0, 0 } */
537 guint num_events
, /* Unset : G_MAXUINT */
538 LttvTracesetContextPosition end_position
, /* Unset : num_traces = 0 */
539 LttvHooksById
*before_traceset
, /* Unset : NULL */
540 LttvHooksById
*before_trace
, /* Unset : NULL */
541 LttvHooksById
*before_tracefile
, /* Unset : NULL */
542 LttvHooksById
*middle
, /* Unset : NULL */
543 LttvHooksById
*after_tracefile
, /* Unset : NULL */
544 LttvHooksById
*after_trace
, /* Unset : NULL */
545 LttvHooksById
*after_traceset
/* Unset : NULL */
550 * Function to request data in a specific time interval to the main window. The
551 * time request servicing is differed until the glib idle functions are
554 * The viewer has to provide hooks that should be associated with the event
557 * Either start time or start position must be defined in a EventRequest
558 * structure for it to be valid.
560 * end_time, end_position and num_events can all be defined. The first one
561 * to occur will be used as end criterion.
563 * @param main_win the main window the viewer belongs to.
564 * @param events_requested the structure of request from.
567 void lttvwindow_events_request(MainWindow
*main_win
,
568 EventsRequest events_request
);
571 * Function to get the life span of the traceset
573 * @param main_win the main window the viewer belongs to.
574 * @return pointer to a time interval : the life span of the traceset.
577 const TimeInterval
*lttvwindow_get_time_span(MainWindow
*main_win
);
580 * Function to get the current time window of the current tab.
582 * @param main_win the main window the viewer belongs to.
583 * @return a pointer to the current tab's time interval.
586 const TimeWindow
*lttvwindow_get_time_window(MainWindow
*main_win
);
590 * Function to get the current time of the current tab.
592 * @param main_win the main window the viewer belongs to.
593 * @return a pointer to the current tab's current time.
596 const LttTime
*lttvwindow_get_current_time(MainWindow
*main_win
);
600 * Function to get the filter of the current tab.
601 * @param main_win, the main window the viewer belongs to.
602 * @param filter, a pointer to a filter.
606 typedef void lttv_filter
;
608 const lttv_filter
*lttvwindow_get_filter(MainWindow
*main_win
);
612 * Function to get the stats of the traceset
613 * It must be non const so the viewer can modify it.
614 * FIXME : a set/get pair of functions would be more appropriate here.
615 * @param main_win the main window the viewer belongs to.
616 * @return A pointer to Traceset statistics.
619 LttvTracesetStats
* lttvwindow_get_traceset_stats(MainWindow
*main_win
);
622 * Function to get the context of the traceset
623 * It must be non const so the viewer can add and remove hooks from it.
624 * @param main_win the main window the viewer belongs to.
625 * @return Context of the current tab.
629 LttvTracesetContext
* lttvwindow_get_traceset_context(MainWindow
*main_win
);