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 set_time_window
  81 set_current_time
  82 update_traceset?
  83 update_filter?
  84 show_viewer?
  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
 110 /**
 111  * Function to register a view constructor so that main window can generate
 112  * a toolbar item for the viewer in order to generate a new instance easily.
 113  * It will be called by init function of the module.
 114  * @param ButtonPixmap image shown on the toolbar item.
 115  * @param tooltip tooltip of the toolbar item.
 116  * @param view_constructor constructor of the viewer.
 117  */
 118
 119 void lttvwindow_viewer_register_toolbar_item(char ** pixmap, char *tooltip, lttvwindow_viewer_constructor view_constructor);
 120
 121
 122 /**
 123  * Function to unregister the viewer's constructor, release the space
 124  * occupied by pixmap, tooltip and constructor of the viewer.
 125  * It will be called when a module is unloaded.
 126  * @param view_constructor constructor of the viewer which is used as
 127  * a reference to find out where the pixmap and tooltip are.
 128  */
 129
 130 void toolbar_item_unreg(lttvwindow_viewer_constructor view_constructor);
 131
 132
 133 /**
 134  * Function to register a view constructor so that main window can generate
 135  * a menu item for the viewer in order to generate a new instance easily.
 136  * It will be called by init function of the module.
 137  * @param menu_path path of the menu item.
 138  * @param menu_text text of the menu item.
 139  * @param view_constructor constructor of the viewer.
 140  */
 141
 142 void menu_item_reg(char *menu_path, char *menu_text, lttvwindow_viewer_constructor view_constructor);
 143
 144
 145 /**
 146  * Function to unregister the viewer's constructor, release the space
 147  * occupied by menu_path, menu_text and constructor of the viewer.
 148  * It will be called when a module is unloaded.
 149  * @param view_constructor constructor of the viewer which is used as
 150  * a reference to find out where the menu_path and menu_text are.
 151  */
 152
 153 void menu_item_unreg(lttvwindow_viewer_constructor view_constructor);
 154
 155
 156 /**
 157  * Update the status bar whenever something changed in the viewer.
 158  * @param main_win the main window the viewer belongs to.
 159  * @param info the message which will be shown in the status bar.
 160  */
 161
 162 void update_status(MainWindow *main_win, char *info);
 163
 164
 165 /**
 166  * Function to get the current time window of the current tab.
 167  * It will be called by a viewer's hook function to update the
 168  * time window of the viewer and also be called by the constructor
 169  * of the viewer.
 170  * @param main_win the main window the viewer belongs to.
 171  * @param time_interval a pointer where time interval will be stored.
 172  */
 173
 174 void get_time_window(MainWindow *main_win, TimeWindow *time_window);
 175
 176
 177 /**
 178  * Function to set the time interval of the current tab.
 179  * It will be called by a viewer's signal handle associated with
 180  * the move_slider signal
 181  * @param main_win the main window the viewer belongs to.
 182  * @param time_interval a pointer where time interval is stored.
 183  */
 184
 185 void set_time_window(MainWindow *main_win, TimeWindow *time_window);
 186
 187 /**
 188  * Function to get the current time/event of the current tab.
 189  * It will be called by a viewer's hook function to update the
 190  * current time/event of the viewer.
 191  * @param main_win the main window the viewer belongs to.
 192  * @param time a pointer where time will be stored.
 193  */
 194
 195 void get_current_time(MainWindow *main_win, LttTime *time);
 196
 197
 198 /**
 199  * Function to set the current time/event of the current tab.
 200  * It will be called by a viewer's signal handle associated with
 201  * the button-release-event signal
 202  * @param main_win the main window the viewer belongs to.
 203  * @param time a pointer where time is stored.
 204  */
 205
 206 void set_current_time(MainWindow *main_win, LttTime *time);
 207
 208
 209 /**
 210  * Function to get the traceset from the current tab.
 211  * It will be called by the constructor of the viewer and also be
 212  * called by a hook funtion of the viewer to update its traceset.
 213  * @param main_win the main window the viewer belongs to.
 214  * @param traceset a pointer to a traceset.
 215  */
 216
 217 //void get_traceset(MainWindow *main_win, Traceset *traceset);
 218
 219
 220 /**
 221  * Function to get the filter of the current tab.
 222  * It will be called by the constructor of the viewer and also be
 223  * called by a hook funtion of the viewer to update its filter.
 224  * @param main_win, the main window the viewer belongs to.
 225  * @param filter, a pointer to a filter.
 226  */
 227
 228 //void get_filter(MainWindow *main_win, Filter *filter);
 229
 230
 231 /**
 232  * Function to register a hook function for a viewer to set/update its
 233  * time interval.
 234  * It will be called by the constructor of the viewer.
 235  * @param hook hook function of the viewer. Takes a TimeInterval* as call_data.
 236  * @param hook_data hook data associated with the hook function.
 237  * @param main_win the main window the viewer belongs to.
 238  */
 239
 240 void reg_update_time_window(LttvHook hook, gpointer hook_data,
 241                             MainWindow * main_win);
 242
 243
 244 /**
 245  * Function to unregister a viewer's hook function which is used to
 246  * set/update the time interval of the viewer.
 247  * It will be called by the destructor of the viewer.
 248  * @param hook hook function of the viewer. Takes a TimeInterval as call_data.
 249  * @param hook_data hook data associated with the hook function.
 250  * @param main_win the main window the viewer belongs to.
 251  */
 252
 253 void unreg_update_time_window(LttvHook hook, gpointer hook_data,
 254                               MainWindow * main_win);
 255
 256
 257 /**
 258  * Function to register a hook function for a viewer to set/update its
 259  * traceset.
 260  * It will be called by the constructor of the viewer.
 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.
 264  */
 265
 266 void reg_update_traceset(LttvHook hook, gpointer hook_data,
 267                        MainWindow * main_win);
 268
 269
 270 /**
 271  * Function to unregister a viewer's hook function which is used to
 272  * set/update the traceset of the viewer.
 273  * It will be called by the destructor of the viewer.
 274  * @param hook hook function of the viewer.
 275  * @param hook_data hook data associated with the hook function.
 276  * @param main_win the main window the viewer belongs to.
 277  */
 278
 279 void unreg_update_traceset(LttvHook hook, gpointer hook_data,
 280                          MainWindow * main_win);
 281
 282
 283 /**
 284  * Function to redraw each viewer belonging to the current tab
 285  * @param main_win the main window the viewer belongs to.
 286  */
 287
 288 void update_traceset(MainWindow * main_win);
 289
 290
 291 /**
 292  * Function to register a hook function for a viewer to set/update its
 293  * filter.
 294  * It will be called by the constructor of the viewer.
 295  * @param hook hook function of the viewer.
 296  * @param hook_data hook data associated with the hook function.
 297  * @param main_win the main window the viewer belongs to.
 298  */
 299
 300 void reg_update_filter(LttvHook hook, gpointer hook_data,
 301                      MainWindow *main_win);
 302
 303
 304 /**
 305  * Function to unregister a viewer's hook function which is used to
 306  * set/update the filter of the viewer.
 307  * It will be called by the destructor of the viewer.
 308  * @param hook hook function of the viewer.
 309  * @param hook_data hook data associated with the hook function.
 310  * @param main_win the main window the viewer belongs to.
 311  */
 312
 313 void unreg_update_filter(LttvHook hook,  gpointer hook_data,
 314                        MainWindow * main_win);
 315
 316
 317 /**
 318  * Function to register a hook function for a viewer to set/update its
 319  * current time.
 320  * It will be called by the constructor of the viewer.
 321  * @param hook hook function of the viewer.
 322  * @param hook_data hook data associated with the hook function.
 323  * @param main_win the main window the viewer belongs to.
 324  */
 325
 326 void reg_update_current_time(LttvHook hook, gpointer hook_data,
 327                           MainWindow *main_win);
 328
 329
 330 /**
 331  * Function to unregister a viewer's hook function which is used to
 332  * set/update the current time of the viewer.
 333  * It will be called by the destructor of the viewer.
 334  * @param hook hook function of the viewer.
 335  * @param hook_data hook data associated with the hook function.
 336  * @param main_win the main window the viewer belongs to.
 337  */
 338
 339 void unreg_update_current_time(LttvHook hook, gpointer hook_data,
 340                             MainWindow * main_win);
 341
 342
 343 /**
 344  * Function to register a hook function for a viewer to show
 345  *the content of the viewer.
 346  * It will be called by the constructor of the viewer.
 347  * @param hook hook function of the viewer.
 348  * @param hook_data hook data associated with the hook function.
 349  * @param main_win the main window the viewer belongs to.
 350  */
 351
 352 void reg_show_viewer(LttvHook hook, gpointer hook_data,
 353                      MainWindow *main_win);
 354
 355
 356 /**
 357  * Function to unregister a viewer's hook function which is used to
 358  * show the content of the viewer..
 359  * It will be called by the destructor of the viewer.
 360  * @param hook hook function of the viewer.
 361  * @param hook_data hook data associated with the hook function.
 362  * @param main_win the main window the viewer belongs to.
 363  */
 364
 365 void unreg_show_viewer(LttvHook hook, gpointer hook_data,
 366                        MainWindow * main_win);
 367
 368
 369 /**
 370  * Function to show each viewer in the current tab.
 371  * It will be called by main window after it called process_traceset
 372  * @param main_win the main window the viewer belongs to.
 373  */
 374
 375 void show_viewer(MainWindow *main_win);
 376
 377
 378 /**
 379  * Function to set the focused pane (viewer).
 380  * It will be called by a viewer's signal handle associated with
 381  * the grab_focus signal
 382  * @param main_win the main window the viewer belongs to.
 383  * @param paned a pointer to a pane where the viewer is contained.
 384  */
 385
 386 void set_focused_pane(MainWindow *main_win, gpointer paned);
 387
 388
 389 /**
 390  * Function to register a hook function for a viewer to set/update the
 391  * dividor of the hpane.
 392  * It will be called by the constructor of the viewer.
 393  * @param hook hook function of the viewer.
 394  * @param hook_data hook data associated with the hook function.
 395  * @param main_win the main window the viewer belongs to.
 396  */
 397
 398 void reg_update_dividor(LttvHook hook, gpointer hook_data,
 399                       MainWindow *main_win);
 400
 401
 402 /**
 403  * Function to unregister a viewer's hook function which is used to
 404  * set/update hpane's dividor of the viewer.
 405  * It will be called by the destructor of the viewer.
 406  * @param hook hook function of the viewer.
 407  * @param hook_data hook data associated with the hook function.
 408  * @param main_win the main window the viewer belongs to.
 409  */
 410
 411 void unreg_update_dividor(LttvHook hook, gpointer hook_data,
 412                         MainWindow *main_win);
 413
 414
 415 /**
 416  * Function to set the position of the hpane's dividor (viewer).
 417  * It will be called by a viewer's signal handle associated with
 418  * the motion_notify_event event/signal
 419  * @param main_win the main window the viewer belongs to.
 420  * @param position position of the hpane's dividor.
 421  */
 422
 423 void set_hpane_dividor(MainWindow *main_win, gint position);
 424
 425
 426 /**
 427  * Function to get the life span of the traceset
 428  * @param main_win the main window the viewer belongs to.
 429  * @param start start time of the traceset.
 430  * @param end end time of the traceset.
 431  */
 432
 433 void get_traceset_time_span(MainWindow *main_win, TimeInterval *time_span);
 434
 435
 436 /**
 437  * Function to get the stats of the traceset
 438  * @param main_win the main window the viewer belongs to.
 439  */
 440
 441 LttvTracesetStats* get_traceset_stats(MainWindow *main_win);
 442
 443 LttvTracesetContext* get_traceset_context(MainWindow *main_win);