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, Mathieu Desnoyers
   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
  23 Module Related API
  24
  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 module related hooks defined in this file.
  29
  30
  31 Viewer Instance Related API
  32
  33 The lifetime of a viewer is as follows. The viewer constructor function is
  34 called each time an instance view is created (one subwindow of this viewer
  35 type is created by the user either by clicking on the menu item or the button
  36 corresponding to the viewer). Thereafter, the viewer gets hooks called for
  37 different purposes by the window containing it. These hooks are detailed
  38 below. It also has to deal with GTK Events. Finally, it can be destructed by
  39 having its top level widget unreferenced by the main window or by any
  40 GTK Event causing a "destroy-event" signal on the its top widget. Another
  41 possible way for it do be destroyed is if the module gets unloaded. The module
  42 unload function will have to emit a "destroy" signal on each top level widget
  43 of all instances of its viewers.
  44
  45
  46 Notices from Main Window :
  47
  48 time_window : This is the time interval visible on the viewer's tab. Every
  49               viewer that cares about being synchronised by respect to the
  50               time with other viewers should register to this notification.
  51               They should redraw all or part of their display when this occurs.
  52
  53 traceset :    This notification is called whenever a trace is added/removed
  54               from the traceset. As it affects all the data displayed by the
  55               viewer, it sould redraw itself totally.
  56
  57 filter :      FIXME : describe..
  58
  59 current_time: Being able to zoom nearer a specific time or highlight a specific
  60               time on every viewer in synchronicity implies that the viewer
  61               has to shown a visual sign over the drawing or select an event
  62               when it receives this notice. It should also inform the main
  63               window with the appropriate report API function when a user
  64               selects a specific time as being the current time.
  65
  66 dividor :     This notice links the positions of the horizontal dividors
  67               between the graphic display zone of every viewer and their Y axis,
  68               typically showing processes, cpus, ...
  69
  70
  71 FIXME : Add background computation explanation here
  72 background_init: prepare for background computation (comes after show_end).
  73 process_trace for background: done in small chunks in gtk_idle, hooks called.
  74 background_end: remove the hooks and perhaps update the window.
  75
  76
  77 Reporting Changes to the Main Window
  78
  79 In most cases, the enclosing window knows about updates such as described in the
  80 Notification section higher. There are a few cases, however, where updates are
  81 caused by actions known by a view instance. For example, clicking in a view may
  82 update the current time; all viewers within the same window must be told about
  83 the new current time to change the currently highlighted time point. A viewer
  84 reports such events by calling lttvwindow_report_current_time on its lttvwindow.
  85 The lttvwindow will thereafter call update for each of its contained viewers.
  86
  87
  88 Available report methods are :
  89
  90 lttvwindow_report_status : reports the text of the status bar.
  91 lttvwindow_report_time_window : reports the new time window.
  92 lttvwindow_report_current_time : reports the new current time.
  93 lttvwindow_report_dividor : reports the new horizontal dividor's position.
  94 lttvwindow_report_focus : One on the widgets in the viewer has the keyboard's
  95                           focus from GTK.
  96
  97 Requiring Time Interval
  98
  99 FIXME : explain
 100
 101
 102
 103 GTK Events
 104
 105 FIXME: explain GTK Events distribution and signals propagation in details
 106 (useful!)
 107
 108 The "expose_event"
 109
 110 Provides the exposed region in the GdkEventExpose structure.
 111
 112 There are two ways of dealing with exposures. The first one is to directly draw
 113 on the screen and the second one is to draw in a pixmap buffer, and then to
 114 update the screen when necessary.
 115
 116 In the first case, the expose event will be responsible for registering hooks to
 117 process_traceset and require time intervals to the main window. So, in this
 118 scenario, if a part of the screen is damaged, the trace has to be read to
 119 redraw the screen.
 120
 121 In the second case, with a pixmap buffer, the expose handler is only responsible
 122 of showing the pixmap buffer on the screen. If the pixmap buffer has never
 123 been filled with a drawing, the expose handler may ask for it to be filled.
 124
 125 It can add dotted lines and such visual effects to enhance the user's
 126 experience.
 127
 128
 129 FIXME : explain other important events
 130
 131 */
 132
 133
 134
 135
 136 /*! \file viewer.h
 137  * \brief API used by the graphical viewers to interact with their top window.
 138  *
 139  * Main window (lttvwindow module) is the place to contain and display viewers.
 140  * Viewers (lttv plugins) interact with main window through this API.
 141  * This header file should be included in each graphic module.
 142  *
 143  */
 144
 145 #include <gtk/gtk.h>
 146 #include <ltt/ltt.h>
 147 #include <lttv/hook.h>
 148 #include <lttvwindow/common.h>
 149 #include <lttv/stats.h>
 150 //FIXME (not ready yet) #include <lttv/filter.h>
 151
 152
 153 /* Module Related API */
 154
 155
 156 /* constructor a the viewer */
 157 //FIXME explain LttvTracesetSelector and key
 158 typedef GtkWidget * (*lttvwindow_viewer_constructor)
 159                 (MainWindow * main_window, LttvTracesetSelector * s, char *key);
 160
 161
 162 /**
 163  * Function to register a view constructor so that main window can generate
 164  * a toolbar item for the viewer in order to generate a new instance easily.
 165  *
 166  * It should be called by init function of the module.
 167  *
 168  * @param pixmap Image shown on the toolbar item.
 169  * @param tooltip tooltip of the toolbar item.
 170  * @param view_constructor constructor of the viewer.
 171  */
 172
 173 void lttvwindow_register_toolbar
 174                             (char ** pixmap,
 175                              char *  tooltip,
 176                              lttvwindow_viewer_constructor view_constructor);
 177
 178
 179 /**
 180  * Function to unregister the viewer's constructor, release the space
 181  * occupied by pixmap, tooltip and constructor of the viewer.
 182  *
 183  * It will be called when a module is unloaded.
 184  *
 185  * @param view_constructor constructor of the viewer.
 186  */
 187
 188 void lttvwindow_unregister_toolbar
 189                             (lttvwindow_viewer_constructor view_constructor);
 190
 191
 192 /**
 193  * Function to register a view constructor so that main window can generate
 194  * a menu item for the viewer in order to generate a new instance easily.
 195  *
 196  * It will be called by init function of the module.
 197  *
 198  * @param menu_path path of the menu item.
 199  * @param menu_text text of the menu item.
 200  * @param view_constructor constructor of the viewer.
 201  */
 202
 203 void lttvwindow_register_menu(char *menu_path,
 204                               char *menu_text,
 205                               lttvwindow_viewer_constructor view_constructor);
 206
 207
 208 /**
 209  * Function to unregister the viewer's constructor, release the space
 210  * occupied by menu_path, menu_text and constructor of the viewer.
 211  *
 212  * It will be called when a module is unloaded.
 213  *
 214  * @param view_constructor constructor of the viewer.
 215  */
 216
 217 void lttvwindow_unregister_menu(lttvwindow_viewer_constructor view_constructor);
 218
 219
 220
 221 /* Viewer Instance Related API */
 222
 223 /**
 224  * Structure used as hook_data for the time_window_notify hook.
 225  */
 226 typedef struct _TimeWindowNotifyData {
 227   TimeWindow *new_time_window;
 228   TimeWindow *old_time_window;
 229 } TimeWindowNotifyData;
 230
 231
 232 /**
 233  * Function to register a hook function that will be called by the main window
 234  * when the time interval needs to be updated.
 235  *
 236  * This register function is typically called by the constructor of the viewer.
 237  *
 238  * @param main_win the main window the viewer belongs to.
 239  * @param hook hook that sould be called by the main window when the time
 240  *             interval changes. This hook function takes a
 241  *             TimeWindowNotifyData* as call_data.
 242  * @param hook_data hook data associated with the hook function. It will
 243  *                  be typically a pointer to the viewer's data structure.
 244  */
 245
 246 void lttvwindow_register_time_window_notify(MainWindow *main_win,
 247                                             LttvHook    hook,
 248                                             gpointer    hook_data);
 249
 250
 251 /**
 252  * Function to unregister the time_window notification hook.
 253  *
 254  * This unregister function is typically called by the destructor of the viewer.
 255  *
 256  * @param main_win the main window the viewer belongs to.
 257  * @param hook hook that sould be called by the main window when the time
 258  *             interval changes. This hook function takes a
 259  *             TimeWindowNotifyData* as call_data.
 260  * @param hook_data hook data associated with the hook function. It will
 261  *                  be typically a pointer to the viewer's data structure.
 262  */
 263
 264 void lttvwindow_unregister_time_window_notify(MainWindow *main_win,
 265                                               LttvHook    hook,
 266                                               gpointer    hook_data);
 267
 268
 269 /**
 270  * Function to register a hook function that will be called by the main window
 271  * when the traceset is changed. That means that the viewer must redraw
 272  * itself completely or check if it's affected by the particular change to the
 273  * traceset.
 274  *
 275  * This register function is typically called by the constructor of the viewer.
 276  *
 277  * @param main_win the main window the viewer belongs to.
 278  * @param hook hook that should be called whenever a change to the traceset
 279  *             occurs. The call_data of this hook is a NULL pointer.
 280  * @param hook_data hook data associated with the hook function. It will
 281  *                  be typically a pointer to the viewer's data structure.
 282  */
 283
 284 void lttvwindow_register_traceset_notify(MainWindow *main_win,
 285                                          LttvHook    hook,
 286                                          gpointer    hook_data);
 287
 288
 289 /**
 290  * Function to unregister the traceset_notify hook.
 291  *
 292  * @param main_win the main window the viewer belongs to.
 293  * @param hook hook that should be called whenever a change to the traceset
 294  *             occurs. The call_data of this hook is a NULL pointer.
 295  * @param hook_data hook data associated with the hook function. It will
 296  *                  be typically a pointer to the viewer's data structure.
 297  */
 298
 299 void lttvwindow_unregister_traceset_notify(MainWindow *main_win,
 300                                            LttvHook    hook,
 301                                            gpointer    hook_data);
 302
 303
 304 /**
 305  * Function to register a hook function for a viewer to set/update its
 306  * filter.
 307  *
 308  * FIXME : Add information about what a filter is as seen from a viewer and how
 309  * to use it.
 310  *
 311  * This register function is typically called by the constructor of the viewer.
 312  *
 313  * @param main_win the main window the viewer belongs to.
 314  * @param hook hook function called by the main window when a filter change
 315  *             occurs.
 316  * @param hook_data hook data associated with the hook function. It will
 317  *                  be typically a pointer to the viewer's data structure.
 318  */
 319
 320 void lttvwindow_register_filter_notify(MainWindow *main_win,
 321                                        LttvHook    hook,
 322                                        gpointer    hook_data);
 323
 324
 325 /**
 326  * Function to unregister a viewer's hook function which is used to
 327  * set/update the filter of the viewer.
 328  *
 329  * This unregistration is called by the destructor of the viewer.
 330  *
 331  * @param main_win the main window the viewer belongs to.
 332  * @param hook hook function called by the main window when a filter change
 333  *             occurs.
 334  * @param hook_data hook data associated with the hook function. It will
 335  *                  be typically a pointer to the viewer's data structure.
 336  */
 337
 338 void lttvwindow_unregister_filter_notify(MainWindow * main_win,
 339                                          LttvHook     hook,
 340                                          gpointer     hook_data);
 341
 342
 343 /**
 344  * Function to register a hook function for a viewer to set/update its
 345  * current time.
 346  *
 347  * @param main_win the main window the viewer belongs to.
 348  * @param hook hook function of the viewer that updates the current time. The
 349  *             call_data is a LttTime* representing the new current time.
 350  * @param hook_data hook data associated with the hook function. It will
 351  *                  be typically a pointer to the viewer's data structure.
 352  */
 353
 354 void lttvwindow_register_current_time_notify(MainWindow *main_win,
 355                                              LttvHook    hook,
 356                                              gpointer    hook_data);
 357
 358
 359 /**
 360  * Function to unregister a viewer's hook function which is used to
 361  * set/update the current time of the viewer.
 362  * @param main_win the main window the viewer belongs to.
 363  * @param hook hook function of the viewer that updates the current time. The
 364  *             call_data is a LttTime* representing the new current time.
 365  * @param hook_data hook data associated with the hook function. It will
 366  *                  be typically a pointer to the viewer's data structure.
 367  */
 368
 369 void lttvwindow_unregister_current_time_notify(MainWindow *main_win,
 370                                                LttvHook    hook,
 371                                                gpointer    hook_data);
 372
 373
 374 /**
 375  * Function to register a hook function for a viewer to set/update the
 376  * dividor of the hpane. It provides a way to make the horizontal
 377  * dividors of all the viewers linked together.
 378  *
 379  * @param main_win the main window the viewer belongs to.
 380  * @param hook hook function of the viewer that will be called whenever a
 381  *             dividor changes in another viewer. The call_data of this hook
 382  *             is a gint*. The value of the integer is the new position of the
 383  *             hpane dividor.
 384  * @param hook_data hook data associated with the hook function. It will
 385  *                  be typically a pointer to the viewer's data structure.
 386  */
 387
 388 void lttvwindow_register_dividor(MainWindow *main_win,
 389                                  LttvHook    hook,
 390                                  gpointer    hook_data);
 391
 392
 393 /**
 394  * Function to unregister a viewer's hook function which is used to
 395  * set/update hpane's dividor of the viewer.
 396  *
 397  * @param main_win the main window the viewer belongs to.
 398  * @param hook hook function of the viewer that will be called whenever a
 399  *             dividor changes in another viewer. The call_data of this hook
 400  *             is a gint*. The value of the integer is the new position of the
 401  *             hpane dividor.
 402  * @param hook_data hook data associated with the hook function. It will
 403  *                  be typically a pointer to the viewer's data structure.
 404  */
 405
 406 void lttvwindow_unregister_dividor(MainWindow *main_win,
 407                                    LttvHook    hook,
 408                                    gpointer    hook_data);
 409
 410
 411
 412 /**
 413  * This method reports the information to show on the status bar in the
 414  * main window.
 415  *
 416  * @param main_win the main window the viewer belongs to.
 417  * @param info the message which will be shown in the status bar.
 418  */
 419
 420 void lttvwindow_report_status(MainWindow *main_win, const char *info);
 421
 422
 423 /**
 424  * Function to set the time interval of the current tab.a
 425  *
 426  * @param main_win the main window the viewer belongs to.
 427  * @param time_interval pointer to the time interval value.
 428  */
 429
 430 void lttvwindow_report_time_window(MainWindow       *main_win,
 431                                    const TimeWindow *time_window);
 432
 433 /**
 434  * Function to set the current time/event of the current tab.
 435  * It will be called by a viewer's signal handle associated with
 436  * the button-release-event signal
 437  * @param main_win the main window the viewer belongs to.
 438  * @param time a pointer where time is stored.
 439  */
 440
 441 void lttvwindow_report_current_time(MainWindow    *main_win,
 442                                     const LttTime *time);
 443
 444
 445 /**
 446  * Function to set the position of the hpane's dividor (viewer).
 447  * It will typically be called by a viewer's signal handle associated
 448  * with the motion_notify_event event/signal.
 449  *
 450  * @param main_win the main window the viewer belongs to.
 451  * @param position position of the hpane's dividor.
 452  */
 453
 454 void lttvwindow_report_dividor(MainWindow *main_win, gint position);
 455
 456 /**
 457  * Function to set the focused viewer of the tab.
 458  * It will be called by a viewer's signal handle associated with
 459  * the grab_focus signal of all widgets in the viewer.
 460  *
 461  * @param main_win the main window the viewer belongs to.
 462  * @param top_widget the top widget containing all the other widgets of the
 463  *                   viewer.
 464  */
 465 void lttvwindow_report_focus(MainWindow *main_win,
 466                              GtkWidget  *top_widget);
 467
 468
 469
 470 /* Structure sent to the time request hook */
 471 typedef struct _TimeRequest {
 472   TimeWindow  time_window;
 473   guint num_events;
 474   LttvHook after_hook;
 475   gpointer after_hook_data;
 476 } TimeRequest;
 477
 478 /**
 479  * Function to request data in a specific time interval to the main window. The
 480  * time request servicing is differed until the glib idle functions are
 481  * called.
 482  *
 483  * The viewer has to make sure that it has registered hooks in the main window's
 484  * traceset context before the glib idle's function gets called to ensure that
 485  * it will be called for the events it has asked for.
 486  *
 487  * @param main_win the main window the viewer belongs to.
 488  * @param time_requested the time requested by the viewer.
 489  * @param num_events the quantity of events to get (can be a little more if many
 490  *                   events have the same timestamp than the last one)
 491  * @param after_process_traceset hook called after the process traceset. It will
 492  *                               typically unregister the hooks in the context.
 493  *                               The call_data of this hook is a
 494  *                               const TimeRequest*, corresponding to the
 495  *                               original time request. It's there for
 496  *                               information purpose only and should not be
 497  *                               freed.
 498  * @param after_process_traceset_data hook data associated with the hook
 499  *                                    function. It will be typically a pointer
 500  *                                    to the viewer's data structure.
 501  */
 502
 503 void lttvwindow_time_interval_request(MainWindow *main_win,
 504                                       TimeWindow  time_requested,
 505                                       guint       num_events,
 506                                       LttvHook    after_process_traceset,
 507                                       gpointer    after_process_traceset_data);
 508
 509 /**
 510  * Function to get the life span of the traceset
 511  *
 512  * @param main_win the main window the viewer belongs to.
 513  * @return pointer to a time interval : the life span of the traceset.
 514  */
 515
 516 const TimeInterval *lttvwindow_get_time_span(MainWindow *main_win);
 517
 518 /**
 519  * Function to get the current time window of the current tab.
 520  *
 521  * @param main_win the main window the viewer belongs to.
 522  * @return a pointer to the current tab's time interval.
 523  */
 524
 525 const TimeWindow *lttvwindow_get_time_window(MainWindow *main_win);
 526
 527
 528 /**
 529  * Function to get the current time of the current tab.
 530  *
 531  * @param main_win the main window the viewer belongs to.
 532  * @return a pointer to the current tab's current time.
 533  */
 534
 535 const LttTime *lttvwindow_get_current_time(MainWindow *main_win);
 536
 537
 538 /**
 539  * Function to get the filter of the current tab.
 540  * @param main_win, the main window the viewer belongs to.
 541  * @param filter, a pointer to a filter.
 542  */
 543
 544 //FIXME
 545 typedef void lttv_filter;
 546 //FIXME
 547 const lttv_filter *lttvwindow_get_filter(MainWindow *main_win);
 548
 549
 550 /**
 551  * Function to get the stats of the traceset
 552  * It must be non const so the viewer can modify it.
 553  * FIXME : a set/get pair of functions would be more appropriate here.
 554  * @param main_win the main window the viewer belongs to.
 555  * @return A pointer to Traceset statistics.
 556  */
 557
 558 LttvTracesetStats* lttvwindow_get_traceset_stats(MainWindow *main_win);
 559
 560 /**
 561  * Function to get the context of the traceset
 562  * It must be non const so the viewer can add and remove hooks from it.
 563  * @param main_win the main window the viewer belongs to.
 564  * @return Context of the current tab.
 565  */
 566
 567
 568 LttvTracesetContext* lttvwindow_get_traceset_context(MainWindow *main_win);
 569
 570