1 /* This file is part of the Linux Trace Toolkit viewer
2 * Copyright (C) 2003-2004 Xiangxiu Yang
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.
22 - Remove the _api functions which add nothing
23 - streamline the rest.
25 A viewer plugin is, before anything, a plugin. It thus has an init and
26 a destroy function called whenever it is loaded/initialized and
27 unloaded/destroyed. A viewer depends on lttvwindow and thus uses its init and
28 destroy functions to register viewer related hooks defined in this file.
30 The lifetime of a viewer is as follows. The viewer constructor function is
31 called each time an instance view is created (one subwindow of this viewer
32 type is created by the user). Thereafter, the viewer gets hooks called for
33 different purposes by the window containing it. These hooks are detailed
36 show: called initially once the trace, position and time window are known.
37 Do the drawing or register hooks
38 process_trace for show: hooks called
39 show_end: remove the hooks
41 background_init: prepare for background computation (comes after show_end).
42 process_trace for background: done in small chunks in gtk_idle, hooks called.
43 background_end: remove the hooks and perhaps update the window.
45 update: called when the windows is exposed/resized, the time window is changed,
46 the current time is changed or the traceset is changed (different
47 traceset or traces added/removed. Redraw or register hooks.
48 process_trace for update: hooks called
49 update_end: remove the hooks.
51 There may be different versions of update functions for the different cases,
52 or the type of update may be described in an argument. The expose method
53 normally provides the exposed region. This should be used to register hooks
54 to process_traceset but also tell about the time interval for which it is
55 required. Then, a expose_end will be required to remove the hooks and finish
56 the display as needed.
58 In most cases, the enclosing window knows about updates such as a new trace
59 added to a traceset, time window updates caused by scrolling and even
60 expose events. There are a few cases, however, where updates are caused by
61 actions known by a view instance. For example, clicking in a view may update
62 the current time; all viewers within the same window must be told about the
63 new current time to change the currently highlighted time point. A viewer
64 reports such events by calling report_update on its lttvwindow. The lttvwindow
65 will thereafter call update for each of its contained viewers.
68 Things that can happen to a viewer:
76 ?? Reshape, damage as gtk methods ??
78 Things that a viewer can do:
94 * \brief API used by the graphical viewers to interact with their top window.
96 * Main window (gui module) is the place to contain and display viewers.
97 * Viewers (lttv plugins) interacte with main window through this API and
99 * This header file should be included in each graphic module.
100 * This library is used by graphical modules to interact with the
107 #include <lttv/hook.h>
108 #include <lttvwindow/common.h>
109 #include <lttv/stats.h>
112 * Function to register a view constructor so that main window can generate
113 * a toolbar item for the viewer in order to generate a new instance easily.
114 * It will be called by init function of the module.
115 * @param ButtonPixmap image shown on the toolbar item.
116 * @param tooltip tooltip of the toolbar item.
117 * @param view_constructor constructor of the viewer.
120 void toolbar_item_reg(char ** pixmap
, char *tooltip
, lttv_constructor view_constructor
);
124 * Function to unregister the viewer's constructor, release the space
125 * occupied by pixmap, tooltip and constructor of the viewer.
126 * It will be called when a module is unloaded.
127 * @param view_constructor constructor of the viewer which is used as
128 * a reference to find out where the pixmap and tooltip are.
131 void toolbar_item_unreg(lttv_constructor view_constructor
);
135 * Function to register a view constructor so that main window can generate
136 * a menu item for the viewer in order to generate a new instance easily.
137 * It will be called by init function of the module.
138 * @param menu_path path of the menu item.
139 * @param menu_text text of the menu item.
140 * @param view_constructor constructor of the viewer.
143 void menu_item_reg(char *menu_path
, char *menu_text
, lttv_constructor view_constructor
);
147 * Function to unregister the viewer's constructor, release the space
148 * occupied by menu_path, menu_text and constructor of the viewer.
149 * It will be called when a module is unloaded.
150 * @param view_constructor constructor of the viewer which is used as
151 * a reference to find out where the menu_path and menu_text are.
154 void menu_item_unreg(lttv_constructor view_constructor
);
158 * Update the status bar whenever something changed in the viewer.
159 * @param main_win the main window the viewer belongs to.
160 * @param info the message which will be shown in the status bar.
163 void update_status(MainWindow
*main_win
, char *info
);
167 * Function to get the current time window of the current tab.
168 * It will be called by a viewer's hook function to update the
169 * time window of the viewer and also be called by the constructor
171 * @param main_win the main window the viewer belongs to.
172 * @param time_interval a pointer where time interval will be stored.
175 void get_time_window(MainWindow
*main_win
, TimeWindow
*time_window
);
179 * Function to set the time interval of the current tab.
180 * It will be called by a viewer's signal handle associated with
181 * the move_slider signal
182 * @param main_win the main window the viewer belongs to.
183 * @param time_interval a pointer where time interval is stored.
186 void set_time_window(MainWindow
*main_win
, TimeWindow
*time_window
);
189 * Function to get the current time/event of the current tab.
190 * It will be called by a viewer's hook function to update the
191 * current time/event of the viewer.
192 * @param main_win the main window the viewer belongs to.
193 * @param time a pointer where time will be stored.
196 void get_current_time(MainWindow
*main_win
, LttTime
*time
);
200 * Function to set the current time/event of the current tab.
201 * It will be called by a viewer's signal handle associated with
202 * the button-release-event signal
203 * @param main_win the main window the viewer belongs to.
204 * @param time a pointer where time is stored.
207 void set_current_time(MainWindow
*main_win
, LttTime
*time
);
211 * Function to get the traceset from the current tab.
212 * It will be called by the constructor of the viewer and also be
213 * called by a hook funtion of the viewer to update its traceset.
214 * @param main_win the main window the viewer belongs to.
215 * @param traceset a pointer to a traceset.
218 //void get_traceset(MainWindow *main_win, Traceset *traceset);
222 * Function to get the filter of the current tab.
223 * It will be called by the constructor of the viewer and also be
224 * called by a hook funtion of the viewer to update its filter.
225 * @param main_win, the main window the viewer belongs to.
226 * @param filter, a pointer to a filter.
229 //void get_filter(MainWindow *main_win, Filter *filter);
233 * Function to register a hook function for a viewer to set/update its
235 * It will be called by the constructor of the viewer.
236 * @param hook hook function of the viewer. Takes a TimeInterval* as call_data.
237 * @param hook_data hook data associated with the hook function.
238 * @param main_win the main window the viewer belongs to.
241 void reg_update_time_window(LttvHook hook
, gpointer hook_data
,
242 MainWindow
* main_win
);
246 * Function to unregister a viewer's hook function which is used to
247 * set/update the time interval of the viewer.
248 * It will be called by the destructor of the viewer.
249 * @param hook hook function of the viewer. Takes a TimeInterval as call_data.
250 * @param hook_data hook data associated with the hook function.
251 * @param main_win the main window the viewer belongs to.
254 void unreg_update_time_window(LttvHook hook
, gpointer hook_data
,
255 MainWindow
* main_win
);
259 * Function to register a hook function for a viewer to set/update its
261 * It will be called by the constructor of the viewer.
262 * @param hook hook function of the viewer.
263 * @param hook_data hook data associated with the hook function.
264 * @param main_win the main window the viewer belongs to.
267 void reg_update_traceset(LttvHook hook
, gpointer hook_data
,
268 MainWindow
* main_win
);
272 * Function to unregister a viewer's hook function which is used to
273 * set/update the traceset of the viewer.
274 * It will be called by the destructor of the viewer.
275 * @param hook hook function of the viewer.
276 * @param hook_data hook data associated with the hook function.
277 * @param main_win the main window the viewer belongs to.
280 void unreg_update_traceset(LttvHook hook
, gpointer hook_data
,
281 MainWindow
* main_win
);
285 * Function to redraw each viewer belonging to the current tab
286 * @param main_win the main window the viewer belongs to.
289 void update_traceset(MainWindow
* main_win
);
293 * Function to register a hook function for a viewer to set/update its
295 * It will be called by the constructor of the viewer.
296 * @param hook hook function of the viewer.
297 * @param hook_data hook data associated with the hook function.
298 * @param main_win the main window the viewer belongs to.
301 void reg_update_filter(LttvHook hook
, gpointer hook_data
,
302 MainWindow
*main_win
);
306 * Function to unregister a viewer's hook function which is used to
307 * set/update the filter of the viewer.
308 * It will be called by the destructor of the viewer.
309 * @param hook hook function of the viewer.
310 * @param hook_data hook data associated with the hook function.
311 * @param main_win the main window the viewer belongs to.
314 void unreg_update_filter(LttvHook hook
, gpointer hook_data
,
315 MainWindow
* main_win
);
319 * Function to register a hook function for a viewer to set/update its
321 * It will be called by the constructor of the viewer.
322 * @param hook hook function of the viewer.
323 * @param hook_data hook data associated with the hook function.
324 * @param main_win the main window the viewer belongs to.
327 void reg_update_current_time(LttvHook hook
, gpointer hook_data
,
328 MainWindow
*main_win
);
332 * Function to unregister a viewer's hook function which is used to
333 * set/update the current time of the viewer.
334 * It will be called by the destructor of the viewer.
335 * @param hook hook function of the viewer.
336 * @param hook_data hook data associated with the hook function.
337 * @param main_win the main window the viewer belongs to.
340 void unreg_update_current_time(LttvHook hook
, gpointer hook_data
,
341 MainWindow
* main_win
);
345 * Function to register a hook function for a viewer to show
346 *the content of the viewer.
347 * It will be called by the constructor of the viewer.
348 * @param hook hook function of the viewer.
349 * @param hook_data hook data associated with the hook function.
350 * @param main_win the main window the viewer belongs to.
353 void reg_show_viewer(LttvHook hook
, gpointer hook_data
,
354 MainWindow
*main_win
);
358 * Function to unregister a viewer's hook function which is used to
359 * show the content of the viewer..
360 * It will be called by the destructor of the viewer.
361 * @param hook hook function of the viewer.
362 * @param hook_data hook data associated with the hook function.
363 * @param main_win the main window the viewer belongs to.
366 void unreg_show_viewer(LttvHook hook
, gpointer hook_data
,
367 MainWindow
* main_win
);
371 * Function to show each viewer in the current tab.
372 * It will be called by main window after it called process_traceset
373 * @param main_win the main window the viewer belongs to.
376 void show_viewer(MainWindow
*main_win
);
380 * Function to set the focused pane (viewer).
381 * It will be called by a viewer's signal handle associated with
382 * the grab_focus signal
383 * @param main_win the main window the viewer belongs to.
384 * @param paned a pointer to a pane where the viewer is contained.
387 void set_focused_pane(MainWindow
*main_win
, gpointer paned
);
391 * Function to register a hook function for a viewer to set/update the
392 * dividor of the hpane.
393 * It will be called by the constructor of the viewer.
394 * @param hook hook function of the viewer.
395 * @param hook_data hook data associated with the hook function.
396 * @param main_win the main window the viewer belongs to.
399 void reg_update_dividor(LttvHook hook
, gpointer hook_data
,
400 MainWindow
*main_win
);
404 * Function to unregister a viewer's hook function which is used to
405 * set/update hpane's dividor of the viewer.
406 * It will be called by the destructor of the viewer.
407 * @param hook hook function of the viewer.
408 * @param hook_data hook data associated with the hook function.
409 * @param main_win the main window the viewer belongs to.
412 void unreg_update_dividor(LttvHook hook
, gpointer hook_data
,
413 MainWindow
*main_win
);
417 * Function to set the position of the hpane's dividor (viewer).
418 * It will be called by a viewer's signal handle associated with
419 * the motion_notify_event event/signal
420 * @param main_win the main window the viewer belongs to.
421 * @param position position of the hpane's dividor.
424 void set_hpane_dividor(MainWindow
*main_win
, gint position
);
428 CHECK These functions really should not appear here. Directr calls would
429 be OK unless there is a linker problem.
432 * Function to process traceset. It will call lttv_process_trace,
433 * each view will call this api to get events.
434 * @param main_win the main window the viewer belongs to.
435 * @param start the start time of the first event to be processed.
436 * @param end the end time of the last event to be processed.
439 void process_traceset_api(MainWindow
*main_win
, LttTime start
,
440 LttTime end
, unsigned maxNumEvents
);
444 * Function to add hooks into the context of a traceset,
445 * before reading events from traceset, viewer will call this api to
447 * @param main_win the main window the viewer belongs to.
448 * @param LttvHooks hooks to be registered.
451 void context_add_hooks_api(MainWindow
*main_win
,
452 LttvHooks
*before_traceset
,
453 LttvHooks
*after_traceset
,
454 LttvHooks
*check_trace
,
455 LttvHooks
*before_trace
,
456 LttvHooks
*after_trace
,
457 LttvHooks
*check_tracefile
,
458 LttvHooks
*before_tracefile
,
459 LttvHooks
*after_tracefile
,
460 LttvHooks
*check_event
,
461 LttvHooks
*before_event
,
462 LttvHooks
*after_event
);
466 * Function to remove hooks from the context of a traceset,
467 * before reading events from traceset, viewer will call this api to
469 * @param main_win the main window the viewer belongs to.
470 * @param LttvHooks hooks to be registered.
473 void context_remove_hooks_api(MainWindow
*main_win
,
474 LttvHooks
*before_traceset
,
475 LttvHooks
*after_traceset
,
476 LttvHooks
*check_trace
,
477 LttvHooks
*before_trace
,
478 LttvHooks
*after_trace
,
479 LttvHooks
*check_tracefile
,
480 LttvHooks
*before_tracefile
,
481 LttvHooks
*after_tracefile
,
482 LttvHooks
*check_event
,
483 LttvHooks
*before_event
,
484 LttvHooks
*after_event
);
488 * Function to get the life span of the traceset
489 * @param main_win the main window the viewer belongs to.
490 * @param start start time of the traceset.
491 * @param end end time of the traceset.
494 void get_traceset_time_span(MainWindow
*main_win
, TimeInterval
*time_span
);
498 * Function to add/remove event hooks for state
499 * @param main_win the main window the viewer belongs to.
502 void state_add_event_hooks_api(MainWindow
*main_win
);
503 void state_remove_event_hooks_api(MainWindow
*main_win
);
507 * Function to add/remove event hooks for stats
508 * @param main_win the main window the viewer belongs to.
511 void stats_add_event_hooks_api(MainWindow
*main_win
);
512 void stats_remove_event_hooks_api(MainWindow
*main_win
);
516 * Function to get the stats of the traceset
517 * @param main_win the main window the viewer belongs to.
520 LttvTracesetStats
* get_traceset_stats_api(MainWindow
*main_win
);
522 LttvTracesetContext
* get_traceset_context(MainWindow
*main_win
);