ltt/branches/poly/lttv/modules/gui/lttvwindow/lttvwindow/viewer.h

   1 /* This file is part of the Linux Trace Toolkit viewer
   2  * Copyright (C) 2003-2004 Xiangxiu Yang
   3  *
   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;
   7  *
   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.
  12  *
  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,
  16  * MA 02111-1307, USA.
  17  */
  18
  19 /*
  20 This file is what every viewer plugin writer should refer to.
  21
  22 - streamline the rest.
  23
  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.
  28
  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
  33 below.
  34
  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
  39
  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.
  43
  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.
  49
  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.
  56
  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.
  65
  66
  67 Things that can happen to a viewer:
  68
  69 update_time_window
  70 update_current_time
  71 update_traceset
  72 update_filter
  73 show_viewer
  74 update_dividor
  75 ?? Reshape, damage as gtk methods ??
  76
  77 Things that a viewer can do:
  78
  79 update_status
  80 lttvwindow_report_time_window
  81 set_current_time
  82 update_traceset -> not actually
  83 update_filter -> not actually
  84 show_viewer -> makes no sense.
  85 set_focused_pane
  86 set_hpane_dividor
  87 */
  88
  89
  90
  91
  92 /*! \file viewer.h
  93  * \brief API used by the graphical viewers to interact with their top window.
  94  *
  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
  97  * events sent by gtk.
  98  * This header file should be included in each graphic module.
  99  * This library is used by graphical modules to interact with the
 100  * tracesetWindow.
 101  *
 102  */
 103
 104 #include <gtk/gtk.h>
 105 #include <ltt/ltt.h>
 106 #include <lttv/hook.h>
 107 #include <lttvwindow/common.h>
 108 #include <lttv/stats.h>
 109 //FIXME (not ready yet) #include <lttv/filter.h>
 110
 111 /**
 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.
 118  */
 119
 120 void lttvwindow_register_toolbar(char ** pixmap, char *tooltip, lttvwindow_viewer_constructor view_constructor);
 121
 122
 123 /**
 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.
 129  */
 130
 131 void lttvwindow_unregister_toolbar(lttvwindow_viewer_constructor view_constructor);
 132
 133
 134 /**
 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.
 141  */
 142
 143 void lttvwindow_register_menu(char *menu_path, char *menu_text, lttvwindow_viewer_constructor view_constructor);
 144
 145
 146 /**
 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.
 152  */
 153
 154 void lttvwindow_unregister_menu(lttvwindow_viewer_constructor view_constructor);
 155
 156
 157 /**
 158  * Function to register a hook function for a viewer to update its
 159  * time interval.
 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.
 164  */
 165
 166 typedef struct _TimeWindowNotifyData {
 167   TimeWindow *new_time_window;
 168   TimeWindow *old_time_window;
 169 } TimeWindowNotifyData;
 170
 171 void lttvwindow_register_time_window_notify(MainWindow * main_win,
 172     LttvHook hook, gpointer hook_data);
 173
 174
 175 /**
 176  * Function to unregister a viewer's hook function which is used to
 177  * set/update the time interval of the viewer.
 178  * This unregister function is typically called by the destructor of the viewer.
 179  * @param hook hook function of the viewer. Takes a TimeInterval as call_data.
 180  * @param hook_data hook data associated with the hook function.
 181  * @param main_win the main window the viewer belongs to.
 182  */
 183
 184 void lttvwindow_unregister_time_window_notify(MainWindow * main_win,
 185     LttvHook hook, gpointer hook_data);
 186
 187
 188 /**
 189  * Function to register a hook function for a viewer to set/update its
 190  * traceset.
 191  * This register function is typically called by the constructor of the viewer.
 192  * @param hook hook function of the viewer.
 193  * @param hook_data hook data associated with the hook function.
 194  * @param main_win the main window the viewer belongs to.
 195  */
 196
 197 void lttvwindow_register_traceset_notify(MainWindow * main_win,
 198     LttvHook hook, gpointer hook_data);
 199
 200
 201 /**
 202  * Function to unregister a viewer's hook function which is used to
 203  * set/update the traceset of the viewer.
 204  * @param hook hook function of the viewer.
 205  * @param hook_data hook data associated with the hook function.
 206  * @param main_win the main window the viewer belongs to.
 207  */
 208
 209 void lttvwindow_unregister_traceset_notify(MainWindow * main_win,
 210               LttvHook hook, gpointer hook_data);
 211
 212
 213 /**
 214  * Function to register a hook function for a viewer to set/update its
 215  * filter.
 216  * This register function is typically called by the constructor of the viewer.
 217  * @param hook hook function of the viewer.
 218  * @param hook_data hook data associated with the hook function.
 219  * @param main_win the main window the viewer belongs to.
 220  */
 221
 222 void lttvwindow_register_filter_notify(MainWindow *main_win,
 223       LttvHook hook, gpointer hook_data);
 224
 225
 226 /**
 227  * Function to unregister a viewer's hook function which is used to
 228  * set/update the filter of the viewer.
 229  * This unregistration is called by the destructor of the viewer.
 230  * @param hook hook function of the viewer.
 231  * @param hook_data hook data associated with the hook function.
 232  * @param main_win the main window the viewer belongs to.
 233  */
 234
 235 void lttvwindow_unregister_filter_notify(LttvHook hook,  gpointer hook_data,
 236                        MainWindow * main_win);
 237
 238
 239 /**
 240  * Function to register a hook function for a viewer to set/update its
 241  * current time.
 242  * @param hook hook function of the viewer.
 243  * @param hook_data hook data associated with the hook function.
 244  * @param main_win the main window the viewer belongs to.
 245  */
 246
 247 void lttvwindow_register_current_time_notify(MainWindow *main_win,
 248             LttvHook hook, gpointer hook_data);
 249
 250
 251 /**
 252  * Function to unregister a viewer's hook function which is used to
 253  * set/update the current time of the viewer.
 254  * @param hook hook function of the viewer.
 255  * @param hook_data hook data associated with the hook function.
 256  * @param main_win the main window the viewer belongs to.
 257  */
 258
 259 void lttvwindow_unregister_current_time_notify(MainWindow * main_win,
 260             LttvHook hook, gpointer hook_data);
 261
 262
 263 /**
 264  * Function to register a hook function for a viewer to show
 265  * its content.
 266  * @param hook hook function of the viewer.
 267  * @param hook_data hook data associated with the hook function.
 268  * @param main_win the main window the viewer belongs to.
 269  */
 270
 271 void lttvwindow_register_show_notify(MainWindow *main_win,
 272           LttvHook hook, gpointer hook_data);
 273
 274
 275 /**
 276  * Function to unregister a viewer's hook function which is used to
 277  * show the content of the viewer.
 278  * @param hook hook function of the viewer.
 279  * @param hook_data hook data associated with the hook function.
 280  * @param main_win the main window the viewer belongs to.
 281  */
 282
 283 void lttvwindow_unregister_show_notify(MainWindow * main_win,
 284               LttvHook hook, gpointer hook_data);
 285
 286
 287 /**
 288  * Function to register a hook function for a viewer to set/update the
 289  * dividor of the hpane. It provides a way to make the horizontal
 290  * dividors of all the viewers linked together.
 291  * @param hook hook function of the viewer.
 292  * @param hook_data hook data associated with the hook function.
 293  * @param main_win the main window the viewer belongs to.
 294  */
 295
 296 void lttvwindow_register_dividor(MainWindow *main_win,
 297                     LttvHook hook, gpointer hook_data);
 298
 299
 300 /**
 301  * Function to unregister a viewer's hook function which is used to
 302  * set/update hpane's dividor of the viewer.
 303  * @param hook hook function of the viewer.
 304  * @param hook_data hook data associated with the hook function.
 305  * @param main_win the main window the viewer belongs to.
 306  */
 307
 308 void lttvwindow_unregister_dividor(MainWindow *main_win,
 309                     LttvHook hook, gpointer hook_data);
 310
 311
 312
 313 /**
 314  * Update the status bar whenever something changed in the viewer.
 315  * @param main_win the main window the viewer belongs to.
 316  * @param info the message which will be shown in the status bar.
 317  */
 318
 319 void lttvwindow_report_status(MainWindow *main_win, char *info);
 320
 321
 322 /**
 323  * Function to set the time interval of the current tab.
 324  * It will be called by a viewer's signal handle associated with
 325  * the move_slider signal
 326  * @param main_win the main window the viewer belongs to.
 327  * @param time_interval a pointer where time interval is stored.
 328  */
 329
 330 void lttvwindow_report_time_window(MainWindow *main_win, TimeWindow *time_window);
 331
 332 /**
 333  * Function to set the current time/event of the current tab.
 334  * It will be called by a viewer's signal handle associated with
 335  * the button-release-event signal
 336  * @param main_win the main window the viewer belongs to.
 337  * @param time a pointer where time is stored.
 338  */
 339
 340 void lttvwindow_report_current_time(MainWindow *main_win, LttTime *time);
 341
 342
 343 /**
 344  * Function to set the position of the hpane's dividor (viewer).
 345  * It will be called by a viewer's signal handle associated with
 346  * the motion_notify_event event/signal
 347  * @param main_win the main window the viewer belongs to.
 348  * @param position position of the hpane's dividor.
 349  */
 350
 351 void lttvwindow_report_dividor(MainWindow *main_win, gint position);
 352
 353 /**
 354  * Function to set the focused pane (viewer).
 355  * It will be called by a viewer's signal handle associated with
 356  * the grab_focus signal
 357  * @param main_win the main window the viewer belongs to.
 358  * @param paned a pointer to a pane where the viewer is contained.
 359  */
 360 //FIXME : can we do this through normal GTK signals ?
 361 void lttvwindow_report_focus(MainWindow *main_win, gpointer paned);
 362
 363
 364 /**
 365  * Function to request data in a specific time interval to the main window.
 366  * The main window will use this time interval and the others present
 367  * to get the data from the process trace.
 368  * @param main_win the main window the viewer belongs to.
 369  * @param paned a pointer to a pane where the viewer is contained.
 370  */
 371
 372 void lttvwindow_time_interval_request(MainWindow *main_win,
 373           TimeWindow time_requested, guint num_events,
 374           LttvHook after_process_traceset,
 375           gpointer after_process_traceset_data);
 376
 377 /**
 378  * Function to get the life span of the traceset
 379  * @param main_win the main window the viewer belongs to.
 380  * @param start start time of the traceset.
 381  * @param end end time of the traceset.
 382  */
 383
 384 const TimeInterval *lttvwindow_get_time_span(MainWindow *main_win);
 385
 386 /**
 387  * Function to get the current time window of the current tab.
 388  * @param main_win the main window the viewer belongs to.
 389  * @param time_interval a pointer where time interval will be stored.
 390  */
 391
 392 const TimeWindow *lttvwindow_get_time_window(MainWindow *main_win);
 393
 394
 395 /**
 396  * Function to get the current time/event of the current tab.
 397  * @param main_win the main window the viewer belongs to.
 398  * @param time a pointer where time will be stored.
 399  */
 400
 401 const LttTime *lttvwindow_get_current_time(MainWindow *main_win);
 402
 403 /**
 404  * Function to get the traceset from the current tab.
 405  * @param main_win the main window the viewer belongs to.
 406  * @param traceset a pointer to a traceset.
 407  */
 408
 409 const LttvTraceset *lttvwindow_get_traceset(MainWindow *main_win);
 410
 411
 412 /**
 413  * Function to get the filter of the current tab.
 414  * @param main_win, the main window the viewer belongs to.
 415  * @param filter, a pointer to a filter.
 416  */
 417
 418 //FIXME
 419 typedef void lttv_filter;
 420 //FIXME
 421 const lttv_filter *lttvwindow_get_filter(MainWindow *main_win);
 422
 423
 424 /**
 425  * Function to get the stats of the traceset
 426  * It must be non const so the viewer can modify it. //FIXME really ?
 427  * @param main_win the main window the viewer belongs to.
 428  */
 429
 430 LttvTracesetStats* lttvwindow_get_traceset_stats(MainWindow *main_win);
 431
 432 /**
 433  * Function to get the context of the traceset
 434  * It must be non const so the viewer can add and remove hooks from it.
 435  * @param main_win the main window the viewer belongs to.
 436  */
 437
 438
 439 LttvTracesetContext* lttvwindow_get_traceset_context(MainWindow *main_win);
 440
 441