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 - streamline the rest.
24 A viewer plugin is, before anything, a plugin. It thus has an init and
25 a destroy function called whenever it is loaded/initialized and
26 unloaded/destroyed. A viewer depends on lttvwindow and thus uses its init and
27 destroy functions to register viewer related hooks defined in this file.
29 The lifetime of a viewer is as follows. The viewer constructor function is
30 called each time an instance view is created (one subwindow of this viewer
31 type is created by the user). Thereafter, the viewer gets hooks called for
32 different purposes by the window containing it. These hooks are detailed
35 show: called initially once the trace, position and time window are known.
36 Do the drawing or register hooks
37 process_trace for show: hooks called
38 show_end: remove the hooks
40 background_init: prepare for background computation (comes after show_end).
41 process_trace for background: done in small chunks in gtk_idle, hooks called.
42 background_end: remove the hooks and perhaps update the window.
44 update: called when the windows is exposed/resized, the time window is changed,
45 the current time is changed or the traceset is changed (different
46 traceset or traces added/removed. Redraw or register hooks.
47 process_trace for update: hooks called
48 update_end: remove the hooks.
50 There may be different versions of update functions for the different cases,
51 or the type of update may be described in an argument. The expose method
52 normally provides the exposed region. This should be used to register hooks
53 to process_traceset but also tell about the time interval for which it is
54 required. Then, a expose_end will be required to remove the hooks and finish
55 the display as needed.
57 In most cases, the enclosing window knows about updates such as a new trace
58 added to a traceset, time window updates caused by scrolling and even
59 expose events. There are a few cases, however, where updates are caused by
60 actions known by a view instance. For example, clicking in a view may update
61 the current time; all viewers within the same window must be told about the
62 new current time to change the currently highlighted time point. A viewer
63 reports such events by calling report_update on its lttvwindow. The lttvwindow
64 will thereafter call update for each of its contained viewers.
67 Things that can happen to a viewer:
75 ?? Reshape, damage as gtk methods ??
77 Things that a viewer can do:
93 * \brief API used by the graphical viewers to interact with their top window.
95 * Main window (gui module) is the place to contain and display viewers.
96 * Viewers (lttv plugins) interacte with main window through this API and
98 * This header file should be included in each graphic module.
99 * This library is used by graphical modules to interact with the
106 #include <lttv/hook.h>
107 #include <lttvwindow/common.h>
108 #include <lttv/stats.h>
109 #include <lttv/filter.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 lttvwindow_viewer_register_toolbar(char ** pixmap
, char *tooltip
, lttvwindow_viewer_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 lttvwindow_viewer_unregister_toolbar(lttvwindow_viewer_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 lttvwindow_viewer_register_menu(char *menu_path
, char *menu_text
, lttvwindow_viewer_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 lttvwindow_viewer_unregister_menu(lttvwindow_viewer_constructor view_constructor
);
158 * Function to register a hook function for a viewer to update its
160 * This register function is typically called by the constructor of the viewer.
161 * @param hook hook function of the viewer. Takes a TimeInterval* as call_data.
162 * @param hook_data hook data associated with the hook function.
163 * @param main_win the main window the viewer belongs to.
166 void lttvwindow_viewer_register_time_window_notify(MainWindow
* main_win
,
167 LttvHook hook
, gpointer hook_data
);
171 * Function to unregister a viewer's hook function which is used to
172 * set/update the time interval of the viewer.
173 * This unregister function is typically called by the destructor of the viewer.
174 * @param hook hook function of the viewer. Takes a TimeInterval as call_data.
175 * @param hook_data hook data associated with the hook function.
176 * @param main_win the main window the viewer belongs to.
179 void lttvwindow_viewer_unregister_time_window_notify(MainWindow
* main_win
,
180 LttvHook hook
, gpointer hook_data
);
184 * Function to register a hook function for a viewer to set/update its
186 * This register function is typically called by the constructor of the viewer.
187 * @param hook hook function of the viewer.
188 * @param hook_data hook data associated with the hook function.
189 * @param main_win the main window the viewer belongs to.
192 void lttvwindow_viewer_register_traceset_notify(MainWindow
* main_win
,
193 LttvHook hook
, gpointer hook_data
);
197 * Function to unregister a viewer's hook function which is used to
198 * set/update the traceset of the viewer.
199 * @param hook hook function of the viewer.
200 * @param hook_data hook data associated with the hook function.
201 * @param main_win the main window the viewer belongs to.
204 void lttvwindow_viewer_unregister_traceset_notify(MainWindow
* main_win
,
205 LttvHook hook
, gpointer hook_data
);
209 * Function to register a hook function for a viewer to set/update its
211 * This register function is typically called by the constructor of the viewer.
212 * @param hook hook function of the viewer.
213 * @param hook_data hook data associated with the hook function.
214 * @param main_win the main window the viewer belongs to.
217 void lttvwindow_viewer_register_filter_notify(MainWindow
*main_win
,
218 LttvHook hook
, gpointer hook_data
);
222 * Function to unregister a viewer's hook function which is used to
223 * set/update the filter of the viewer.
224 * This unregistration is called by the destructor of the viewer.
225 * @param hook hook function of the viewer.
226 * @param hook_data hook data associated with the hook function.
227 * @param main_win the main window the viewer belongs to.
230 void lttvwindow_viewer_unregister_filter_notify(LttvHook hook
, gpointer hook_data
,
231 MainWindow
* main_win
);
235 * Function to register a hook function for a viewer to set/update its
237 * @param hook hook function of the viewer.
238 * @param hook_data hook data associated with the hook function.
239 * @param main_win the main window the viewer belongs to.
242 void lttvwindow_viewer_register_current_time_notify(MainWindow
*main_win
,
243 LttvHook hook
, gpointer hook_data
);
247 * Function to unregister a viewer's hook function which is used to
248 * set/update the current time of the viewer.
249 * @param hook hook function of the viewer.
250 * @param hook_data hook data associated with the hook function.
251 * @param main_win the main window the viewer belongs to.
254 void lttvwindow_viewer_unregister_current_time_notify(MainWindow
* main_win
,
255 LttvHook hook
, gpointer hook_data
);
259 * Function to register a hook function for a viewer to show
261 * @param hook hook function of the viewer.
262 * @param hook_data hook data associated with the hook function.
263 * @param main_win the main window the viewer belongs to.
266 void lttvwindow_viewer_register_show(MainWindow
*main_win
,
267 LttvHook hook
, gpointer hook_data
);
271 * Function to unregister a viewer's hook function which is used to
272 * show the content of the viewer.
273 * @param hook hook function of the viewer.
274 * @param hook_data hook data associated with the hook function.
275 * @param main_win the main window the viewer belongs to.
278 void lttvwindow_viewer_unregister_show(MainWindow
* main_win
,
279 LttvHook hook
, gpointer hook_data
);
289 * Update the status bar whenever something changed in the viewer.
290 * @param main_win the main window the viewer belongs to.
291 * @param info the message which will be shown in the status bar.
294 void lttvwindow_viewer_report_status(MainWindow
*main_win
, char *info
);
298 * Function to set the time interval of the current tab.
299 * It will be called by a viewer's signal handle associated with
300 * the move_slider signal
301 * @param main_win the main window the viewer belongs to.
302 * @param time_interval a pointer where time interval is stored.
305 void lttvwindow_viewer_report_time_window(MainWindow
*main_win
, TimeWindow
*time_window
);
308 * Function to set the current time/event of the current tab.
309 * It will be called by a viewer's signal handle associated with
310 * the button-release-event signal
311 * @param main_win the main window the viewer belongs to.
312 * @param time a pointer where time is stored.
315 void lttvwindow_viewer_report_current_time(MainWindow
*main_win
, LttTime
*time
);
319 * Function to set the position of the hpane's dividor (viewer).
320 * It will be called by a viewer's signal handle associated with
321 * the motion_notify_event event/signal
322 * @param main_win the main window the viewer belongs to.
323 * @param position position of the hpane's dividor.
326 void lttvwindow_viewer_report_dividor(MainWindow
*main_win
, gint position
);
329 * Function to redraw each viewer belonging to the current tab, when a traceset
330 * change has been made by the viewer.
331 * @param main_win the main window the viewer belongs to.
333 // FIXME : should never be directly changed by a viewer.
334 //void lttvwindow_viewer_report_traceset(MainWindow * main_win);
338 * Function to show each viewer in the current tab.
339 * It will be called by main window after it called process_traceset
340 * @param main_win the main window the viewer belongs to.
342 //FIXME : not an API function, belongs to the main window.
343 //void lttvwindow_viewer_report_show(MainWindow *main_win);
347 * Function to set the focused pane (viewer).
348 * It will be called by a viewer's signal handle associated with
349 * the grab_focus signal
350 * @param main_win the main window the viewer belongs to.
351 * @param paned a pointer to a pane where the viewer is contained.
353 //FIXME : can we do this through normal GTK signals ?
354 //void set_focused_pane(MainWindow *main_win, gpointer paned);
358 * Function to register a hook function for a viewer to set/update the
359 * dividor of the hpane. It provides a way to make the horizontal
360 * dividors of all the viewers linked together.
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 lttvwindow_viewer_register_dividor(MainWindow
*main_win
,
367 LttvHook hook
, gpointer hook_data
);
371 * Function to unregister a viewer's hook function which is used to
372 * set/update hpane's dividor of the viewer.
373 * @param hook hook function of the viewer.
374 * @param hook_data hook data associated with the hook function.
375 * @param main_win the main window the viewer belongs to.
378 void lttvwindow_viewer_unregister_dividor(MainWindow
*main_win
,
379 LttvHook hook
, gpointer hook_data
);
383 * Function to get the life span of the traceset
384 * @param main_win the main window the viewer belongs to.
385 * @param start start time of the traceset.
386 * @param end end time of the traceset.
389 const TimeInterval
*lttvwindow_viewer_get_time_span(MainWindow
*main_win
);
392 * Function to get the current time window of the current tab.
393 * @param main_win the main window the viewer belongs to.
394 * @param time_interval a pointer where time interval will be stored.
397 const TimeWindow
*lttvwindow_viewer_get_time_window(MainWindow
*main_win
);
401 * Function to get the current time/event of the current tab.
402 * @param main_win the main window the viewer belongs to.
403 * @param time a pointer where time will be stored.
406 const LttTime
*lttvwindow_viewer_get_current_time(MainWindow
*main_win
);
409 * Function to get the traceset from the current tab.
410 * @param main_win the main window the viewer belongs to.
411 * @param traceset a pointer to a traceset.
414 const LttvTraceset
*lttvwindow_viewer_get_traceset(MainWindow
*main_win
);
418 * Function to get the filter of the current tab.
419 * @param main_win, the main window the viewer belongs to.
420 * @param filter, a pointer to a filter.
423 const lttv_filter
*lttvwindow_viewer_get_filter(MainWindow
*main_win
);
427 * Function to get the stats of the traceset
428 * @param main_win the main window the viewer belongs to.
431 LttvTracesetStats
* lttvwindow_viewer_get_traceset_stats(MainWindow
*main_win
);
433 LttvTracesetContext
* lttvwindow_viewer_get_traceset_context(MainWindow
*main_win
);