ltt/branches/poly/lttv/modules/gui/lttvwindow/lttvwindow/gtktraceset.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 - Rename to viewer.h
  23 - Remove the _api functions which add nothing
  24 - streamline the rest.
  25
  26 A viewer plugin is, before anything, a plugin. It thus has an init and
  27 a destroy function called whenever it is loaded/initialized and
  28 unloaded/destroyed. A viewer depends on lttvwindow and thus uses its init and
  29 destroy functions to register viewer related hooks defined in this file.
  30
  31 The lifetime of a viewer is as follows. The viewer constructor function is
  32 called each time an instance view is created (one subwindow of this viewer
  33 type is created by the user). Thereafter, the viewer gets hooks called for
  34 different purposes by the window containing it. These hooks are detailed
  35 below.
  36
  37 show: called initially once the trace, position and time window are known.
  38       Do the drawing or register hooks
  39 process_trace for show: hooks called
  40 show_end: remove the hooks
  41
  42 background_init: prepare for background computation (comes after show_end).
  43 process_trace for background: done in small chunks in gtk_idle, hooks called.
  44 background_end: remove the hooks and perhaps update the window.
  45
  46 update: called when the windows is exposed/resized, the time window is changed,
  47         the current time is changed or the traceset is changed (different
  48         traceset or traces added/removed. Redraw or register hooks.
  49 process_trace for update: hooks called
  50 update_end: remove the hooks.
  51
  52 There may be different versions of update functions for the different cases,
  53 or the type of update may be described in an argument. The expose method
  54 normally provides the exposed region. This should be used to register hooks
  55 to process_traceset but also tell about the time interval for which it is
  56 required. Then, a expose_end will be required to remove the hooks and finish
  57 the display as needed.
  58
  59 In most cases, the enclosing window knows about updates such as a new trace
  60 added to a traceset, time window updates caused by scrolling and even
  61 expose events. There are a few cases, however, where updates are caused by
  62 actions known by a view instance. For example, clicking in a view may update
  63 the current time; all viewers within the same window must be told about the
  64 new current time to change the currently highlighted time point. A viewer
  65 reports such events by calling report_update on its lttvwindow. The lttvwindow
  66 will thereafter call update for each of its contained viewers.
  67
  68
  69 Things that can happen to a viewer:
  70
  71 update_time_window
  72 update_current_time
  73 update_traceset
  74 update_filter
  75 show_viewer
  76 update_dividor
  77 ?? Reshape, damage as gtk methods ??
  78
  79 Things that a viewer can do:
  80
  81 update_status
  82 set_time_window
  83 set_current_time
  84 update_traceset?
  85 update_filter?
  86 show_viewer?
  87 set_focused_pane
  88 set_hpane_dividor
  89 */
  90
  91
  92
  93
  94 /*! \file gtktraceset.h
  95  * \brief API used by the graphical viewers to interact with their top window.
  96  *
  97  * Main window (gui module) is the place to contain and display viewers.
  98  * Viewers (lttv plugins) interacte with main window through this API and
  99  * events sent by gtk.
 100  * This header file should be included in each graphic module.
 101  * This library is used by graphical modules to interact with the
 102  * tracesetWindow.
 103  *
 104  */
 105
 106 #include <gtk/gtk.h>
 107 #include <ltt/ltt.h>
 108 #include <lttv/hook.h>
 109 #include <lttvwindow/common.h>
 110 #include <lttv/stats.h>
 111
 112 /**
 113  * Function to register a view constructor so that main window can generate
 114  * a toolbar item for the viewer in order to generate a new instance easily.
 115  * It will be called by init function of the module.
 116  * @param ButtonPixmap image shown on the toolbar item.
 117  * @param tooltip tooltip of the toolbar item.
 118  * @param view_constructor constructor of the viewer.
 119  */
 120
 121 void toolbar_item_reg(char ** pixmap, char *tooltip, lttv_constructor view_constructor);
 122
 123
 124 /**
 125  * Function to unregister the viewer's constructor, release the space
 126  * occupied by pixmap, tooltip and constructor of the viewer.
 127  * It will be called when a module is unloaded.
 128  * @param view_constructor constructor of the viewer which is used as
 129  * a reference to find out where the pixmap and tooltip are.
 130  */
 131
 132 void toolbar_item_unreg(lttv_constructor view_constructor);
 133
 134
 135 /**
 136  * Function to register a view constructor so that main window can generate
 137  * a menu item for the viewer in order to generate a new instance easily.
 138  * It will be called by init function of the module.
 139  * @param menu_path path of the menu item.
 140  * @param menu_text text of the menu item.
 141  * @param view_constructor constructor of the viewer.
 142  */
 143
 144 void menu_item_reg(char *menu_path, char *menu_text, lttv_constructor view_constructor);
 145
 146
 147 /**
 148  * Function to unregister the viewer's constructor, release the space
 149  * occupied by menu_path, menu_text and constructor of the viewer.
 150  * It will be called when a module is unloaded.
 151  * @param view_constructor constructor of the viewer which is used as
 152  * a reference to find out where the menu_path and menu_text are.
 153  */
 154
 155 void menu_item_unreg(lttv_constructor view_constructor);
 156
 157
 158 /**
 159  * Update the status bar whenever something changed in the viewer.
 160  * @param main_win the main window the viewer belongs to.
 161  * @param info the message which will be shown in the status bar.
 162  */
 163
 164 void update_status(MainWindow *main_win, char *info);
 165
 166
 167 /**
 168  * Function to get the current time window of the current tab.
 169  * It will be called by a viewer's hook function to update the
 170  * time window of the viewer and also be called by the constructor
 171  * of the viewer.
 172  * @param main_win the main window the viewer belongs to.
 173  * @param time_interval a pointer where time interval will be stored.
 174  */
 175
 176 void get_time_window(MainWindow *main_win, TimeWindow *time_window);
 177
 178
 179 /**
 180  * Function to set the time interval of the current tab.
 181  * It will be called by a viewer's signal handle associated with
 182  * the move_slider signal
 183  * @param main_win the main window the viewer belongs to.
 184  * @param time_interval a pointer where time interval is stored.
 185  */
 186
 187 void set_time_window(MainWindow *main_win, TimeWindow *time_window);
 188
 189 /**
 190  * Function to get the current time/event of the current tab.
 191  * It will be called by a viewer's hook function to update the
 192  * current time/event of the viewer.
 193  * @param main_win the main window the viewer belongs to.
 194  * @param time a pointer where time will be stored.
 195  */
 196
 197 void get_current_time(MainWindow *main_win, LttTime *time);
 198
 199
 200 /**
 201  * Function to set the current time/event of the current tab.
 202  * It will be called by a viewer's signal handle associated with
 203  * the button-release-event signal
 204  * @param main_win the main window the viewer belongs to.
 205  * @param time a pointer where time is stored.
 206  */
 207
 208 void set_current_time(MainWindow *main_win, LttTime *time);
 209
 210
 211 /**
 212  * Function to get the traceset from the current tab.
 213  * It will be called by the constructor of the viewer and also be
 214  * called by a hook funtion of the viewer to update its traceset.
 215  * @param main_win the main window the viewer belongs to.
 216  * @param traceset a pointer to a traceset.
 217  */
 218
 219 //void get_traceset(MainWindow *main_win, Traceset *traceset);
 220
 221
 222 /**
 223  * Function to get the filter of the current tab.
 224  * It will be called by the constructor of the viewer and also be
 225  * called by a hook funtion of the viewer to update its filter.
 226  * @param main_win, the main window the viewer belongs to.
 227  * @param filter, a pointer to a filter.
 228  */
 229
 230 //void get_filter(MainWindow *main_win, Filter *filter);
 231
 232
 233 /**
 234  * Function to register a hook function for a viewer to set/update its
 235  * time interval.
 236  * It will be called by the constructor of the viewer.
 237  * @param hook hook function of the viewer. Takes a TimeInterval* as call_data.
 238  * @param hook_data hook data associated with the hook function.
 239  * @param main_win the main window the viewer belongs to.
 240  */
 241
 242 void reg_update_time_window(LttvHook hook, gpointer hook_data,
 243                             MainWindow * main_win);
 244
 245
 246 /**
 247  * Function to unregister a viewer's hook function which is used to
 248  * set/update the time interval of the viewer.
 249  * It will be called by the destructor of the viewer.
 250  * @param hook hook function of the viewer. Takes a TimeInterval as call_data.
 251  * @param hook_data hook data associated with the hook function.
 252  * @param main_win the main window the viewer belongs to.
 253  */
 254
 255 void unreg_update_time_window(LttvHook hook, gpointer hook_data,
 256                               MainWindow * main_win);
 257
 258
 259 /**
 260  * Function to register a hook function for a viewer to set/update its
 261  * traceset.
 262  * It will be called by the constructor of the viewer.
 263  * @param hook hook function of the viewer.
 264  * @param hook_data hook data associated with the hook function.
 265  * @param main_win the main window the viewer belongs to.
 266  */
 267
 268 void reg_update_traceset(LttvHook hook, gpointer hook_data,
 269                        MainWindow * main_win);
 270
 271
 272 /**
 273  * Function to unregister a viewer's hook function which is used to
 274  * set/update the traceset of the viewer.
 275  * It will be called by the destructor of the viewer.
 276  * @param hook hook function of the viewer.
 277  * @param hook_data hook data associated with the hook function.
 278  * @param main_win the main window the viewer belongs to.
 279  */
 280
 281 void unreg_update_traceset(LttvHook hook, gpointer hook_data,
 282                          MainWindow * main_win);
 283
 284
 285 /**
 286  * Function to redraw each viewer belonging to the current tab
 287  * @param main_win the main window the viewer belongs to.
 288  */
 289
 290 void update_traceset(MainWindow * main_win);
 291
 292
 293 /**
 294  * Function to register a hook function for a viewer to set/update its
 295  * filter.
 296  * It will be called by the constructor of the viewer.
 297  * @param hook hook function of the viewer.
 298  * @param hook_data hook data associated with the hook function.
 299  * @param main_win the main window the viewer belongs to.
 300  */
 301
 302 void reg_update_filter(LttvHook hook, gpointer hook_data,
 303                      MainWindow *main_win);
 304
 305
 306 /**
 307  * Function to unregister a viewer's hook function which is used to
 308  * set/update the filter of the viewer.
 309  * It will be called by the destructor of the viewer.
 310  * @param hook hook function of the viewer.
 311  * @param hook_data hook data associated with the hook function.
 312  * @param main_win the main window the viewer belongs to.
 313  */
 314
 315 void unreg_update_filter(LttvHook hook,  gpointer hook_data,
 316                        MainWindow * main_win);
 317
 318
 319 /**
 320  * Function to register a hook function for a viewer to set/update its
 321  * current time.
 322  * It will be called by the constructor of the viewer.
 323  * @param hook hook function of the viewer.
 324  * @param hook_data hook data associated with the hook function.
 325  * @param main_win the main window the viewer belongs to.
 326  */
 327
 328 void reg_update_current_time(LttvHook hook, gpointer hook_data,
 329                           MainWindow *main_win);
 330
 331
 332 /**
 333  * Function to unregister a viewer's hook function which is used to
 334  * set/update the current time of the viewer.
 335  * It will be called by the destructor of the viewer.
 336  * @param hook hook function of the viewer.
 337  * @param hook_data hook data associated with the hook function.
 338  * @param main_win the main window the viewer belongs to.
 339  */
 340
 341 void unreg_update_current_time(LttvHook hook, gpointer hook_data,
 342                             MainWindow * main_win);
 343
 344
 345 /**
 346  * Function to register a hook function for a viewer to show
 347  *the content of the viewer.
 348  * It will be called by the constructor of the viewer.
 349  * @param hook hook function of the viewer.
 350  * @param hook_data hook data associated with the hook function.
 351  * @param main_win the main window the viewer belongs to.
 352  */
 353
 354 void reg_show_viewer(LttvHook hook, gpointer hook_data,
 355                      MainWindow *main_win);
 356
 357
 358 /**
 359  * Function to unregister a viewer's hook function which is used to
 360  * show the content of the viewer..
 361  * It will be called by the destructor of the viewer.
 362  * @param hook hook function of the viewer.
 363  * @param hook_data hook data associated with the hook function.
 364  * @param main_win the main window the viewer belongs to.
 365  */
 366
 367 void unreg_show_viewer(LttvHook hook, gpointer hook_data,
 368                        MainWindow * main_win);
 369
 370
 371 /**
 372  * Function to show each viewer in the current tab.
 373  * It will be called by main window after it called process_traceset
 374  * @param main_win the main window the viewer belongs to.
 375  */
 376
 377 void show_viewer(MainWindow *main_win);
 378
 379
 380 /**
 381  * Function to set the focused pane (viewer).
 382  * It will be called by a viewer's signal handle associated with
 383  * the grab_focus signal
 384  * @param main_win the main window the viewer belongs to.
 385  * @param paned a pointer to a pane where the viewer is contained.
 386  */
 387
 388 void set_focused_pane(MainWindow *main_win, gpointer paned);
 389
 390
 391 /**
 392  * Function to register a hook function for a viewer to set/update the
 393  * dividor of the hpane.
 394  * It will be called by the constructor of the viewer.
 395  * @param hook hook function of the viewer.
 396  * @param hook_data hook data associated with the hook function.
 397  * @param main_win the main window the viewer belongs to.
 398  */
 399
 400 void reg_update_dividor(LttvHook hook, gpointer hook_data,
 401                       MainWindow *main_win);
 402
 403
 404 /**
 405  * Function to unregister a viewer's hook function which is used to
 406  * set/update hpane's dividor of the viewer.
 407  * It will be called by the destructor of the viewer.
 408  * @param hook hook function of the viewer.
 409  * @param hook_data hook data associated with the hook function.
 410  * @param main_win the main window the viewer belongs to.
 411  */
 412
 413 void unreg_update_dividor(LttvHook hook, gpointer hook_data,
 414                         MainWindow *main_win);
 415
 416
 417 /**
 418  * Function to set the position of the hpane's dividor (viewer).
 419  * It will be called by a viewer's signal handle associated with
 420  * the motion_notify_event event/signal
 421  * @param main_win the main window the viewer belongs to.
 422  * @param position position of the hpane's dividor.
 423  */
 424
 425 void set_hpane_dividor(MainWindow *main_win, gint position);
 426
 427
 428 /*
 429 CHECK These functions really should not appear here. Directr calls would
 430 be OK unless there is a linker problem.
 431 */
 432 /**
 433  * Function to process traceset. It will call lttv_process_trace,
 434  * each view will call this api to get events.
 435  * @param main_win the main window the viewer belongs to.
 436  * @param start the start time of the first event to be processed.
 437  * @param end the end time of the last event to be processed.
 438  */
 439
 440 void process_traceset_api(MainWindow *main_win, LttTime start,
 441                           LttTime end, unsigned maxNumEvents);
 442
 443
 444 /**
 445  * Function to add hooks into the context of a traceset,
 446  * before reading events from traceset, viewer will call this api to
 447  * register hooks
 448  * @param main_win the main window the viewer belongs to.
 449  * @param LttvHooks hooks to be registered.
 450  */
 451
 452 void context_add_hooks_api(MainWindow *main_win ,
 453                            LttvHooks *before_traceset,
 454                            LttvHooks *after_traceset,
 455                            LttvHooks *check_trace,
 456                            LttvHooks *before_trace,
 457                            LttvHooks *after_trace,
 458                            LttvHooks *check_tracefile,
 459                            LttvHooks *before_tracefile,
 460                            LttvHooks *after_tracefile,
 461                            LttvHooks *check_event,
 462                            LttvHooks *before_event,
 463                            LttvHooks *after_event);
 464
 465
 466 /**
 467  * Function to remove hooks from the context of a traceset,
 468  * before reading events from traceset, viewer will call this api to
 469  * unregister hooks
 470  * @param main_win the main window the viewer belongs to.
 471  * @param LttvHooks hooks to be registered.
 472  */
 473
 474 void context_remove_hooks_api(MainWindow *main_win ,
 475                               LttvHooks *before_traceset,
 476                               LttvHooks *after_traceset,
 477                               LttvHooks *check_trace,
 478                               LttvHooks *before_trace,
 479                               LttvHooks *after_trace,
 480                               LttvHooks *check_tracefile,
 481                               LttvHooks *before_tracefile,
 482                               LttvHooks *after_tracefile,
 483                               LttvHooks *check_event,
 484                               LttvHooks *before_event,
 485                               LttvHooks *after_event);
 486
 487
 488 /**
 489  * Function to get the life span of the traceset
 490  * @param main_win the main window the viewer belongs to.
 491  * @param start start time of the traceset.
 492  * @param end end time of the traceset.
 493  */
 494
 495 void get_traceset_time_span(MainWindow *main_win, TimeInterval *time_span);
 496
 497
 498 /**
 499  * Function to add/remove event hooks for state
 500  * @param main_win the main window the viewer belongs to.
 501  */
 502
 503 void state_add_event_hooks_api(MainWindow *main_win );
 504 void state_remove_event_hooks_api(MainWindow *main_win );
 505
 506
 507 /**
 508  * Function to add/remove event hooks for stats
 509  * @param main_win the main window the viewer belongs to.
 510  */
 511
 512 void stats_add_event_hooks_api(MainWindow *main_win );
 513 void stats_remove_event_hooks_api(MainWindow *main_win );
 514
 515
 516 /**
 517  * Function to get the stats of the traceset
 518  * @param main_win the main window the viewer belongs to.
 519  */
 520
 521 LttvTracesetStats* get_traceset_stats_api(MainWindow *main_win);
 522
 523 LttvTracesetContext* get_traceset_context(MainWindow *main_win);