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

   1 /* This file is part of the Linux Trace Toolkit Graphic User Interface
   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. As a dynamically loadable
  26 module, it thus has an init and a destroy function called whenever it is
  27 loaded/initialized and unloaded/destroyed. A graphical module depends on
  28 lttvwindow for construction of its viewer instances. In order to achieve this,
  29 it must register its constructor function to the main window along with
  30 button description or text menu entry description. A module keeps a list of
  31 every viewer that currently sits in memory so it can destroy them before the
  32 module gets unloaded/destroyed.
  33
  34
  35 Viewer Instance Related API
  36
  37 The lifetime of a viewer is as follows. The viewer constructor function is
  38 called each time an instance view is created (one subwindow of this viewer
  39 type is created by the user either by clicking on the menu item or the button
  40 corresponding to the viewer). Thereafter, the viewer gets hooks called for
  41 different purposes by the window containing it. These hooks are detailed
  42 below. It also has to deal with GTK Events. Finally, it can be destructed by
  43 having its top level widget unreferenced by the main window or by any
  44 GTK Event causing a "destroy-event" signal on the its top widget. Another
  45 possible way for it do be destroyed is if the module gets unloaded. The module
  46 unload function will have to emit a "destroy" signal on each top level widget
  47 of all instances of its viewers.
  48
  49
  50 Notices from Main Window
  51
  52 time_window : This is the time interval visible on the viewer's tab. Every
  53               viewer that cares about being synchronised by respect to the
  54               time with other viewers should register to this notification.
  55               They should redraw all or part of their display when this occurs.
  56
  57 traceset :    This notification is called whenever a trace is added/removed
  58               from the traceset. As it affects all the data displayed by the
  59               viewer, it sould redraw itself totally.
  60
  61 filter :      FIXME : describe..
  62
  63 current_time: Being able to zoom nearer a specific time or highlight a specific
  64               time on every viewer in synchronicity implies that the viewer
  65               has to shown a visual sign over the drawing or select an event
  66               when it receives this notice. It should also inform the main
  67               window with the appropriate report API function when a user
  68               selects a specific time as being the current time.
  69
  70 dividor :     This notice links the positions of the horizontal dividors
  71               between the graphic display zone of every viewer and their Y axis,
  72               typically showing processes, cpus, ...
  73
  74
  75 FIXME : Add background computation explanation here
  76 background_init: prepare for background computation (comes after show_end).
  77 process_trace for background: done in small chunks in gtk_idle, hooks called.
  78 background_end: remove the hooks and perhaps update the window.
  79
  80
  81 Reporting Changes to the Main Window
  82
  83 In most cases, the enclosing window knows about updates such as described in the
  84 Notification section higher. There are a few cases, however, where updates are
  85 caused by actions known by a view instance. For example, clicking in a view may
  86 update the current time; all viewers within the same window must be told about
  87 the new current time to change the currently highlighted time point. A viewer
  88 reports such events by calling lttvwindow_report_current_time on its lttvwindow.
  89 The lttvwindow will consequently call current_time_notify for each of its
  90 contained viewers.
  91
  92
  93 Available report methods are :
  94
  95 lttvwindow_report_status : reports the text of the status bar.
  96 lttvwindow_report_time_window : reports the new time window.
  97 lttvwindow_report_current_time : reports the new current time.
  98 lttvwindow_report_dividor : reports the new horizontal dividor's position.
  99 lttvwindow_report_focus : One on the widgets in the viewer has the keyboard's
 100                           focus from GTK.
 101
 102
 103
 104 Requesting Events to Main Window
 105
 106 Events can be requested by passing a EventsRequest structure to the main window.
 107 They will be delivered later when the next g_idle functions will be called.
 108 Event delivery is done by calling the middle hook for this event ID, or the
 109 main middle hooks.
 110
 111 EventsRequest consists in
 112 - a start timestamp or position
 113 - a stop_flag, ending the read process when set to TRUE
 114 - a end timestamp and/or position and/or number of events to read
 115 - hook lists to call for traceset/trace/tracefile begin and end, and for each
 116   event (middle).
 117
 118 The main window will deliver events for every EventRequests it has pending
 119 through an algorithm that guarantee that all events requested, and only them,
 120 will be delivered to the viewer between the call of the tracefile_begin hooks
 121 and the call of the tracefile_end hooks.
 122
 123 If a viewer wants to stop the event request at a certain point inside the event
 124 hooks, it has to set the stop_flag to TRUE and return TRUE from the hook
 125 function. Then return value will stop the process traceset. Then, the main
 126 window will look for the stop_flag and remove the EventRequests from its lists,
 127 calling the process_traceset_end for this request (it removes hooks from the
 128 context and calls the after hooks).
 129
 130 It no stop_flag is rose, the end timestamp, end position or number of events to
 131 read has to be reached to determine the end of the request. Otherwise,
 132 the end of traceset does determine it.
 133
 134
 135 GTK Events
 136
 137 Events and Signals
 138
 139 GTK is quite different from the other graphical toolkits around there. The main
 140 difference resides in that there are many X Windows inside one GtkWindow,
 141 instead of just one. That means that X events are delivered by the glib main
 142 loop directly to the widget corresponding to the GdkWindow affected by the X
 143 event.
 144
 145 Event delivery to a widget emits a signal on that widget. Then, if a handler
 146 is connected to this widget's signal, it will be executed. There are default
 147 handlers for signals, connected at class instantiation time. There is also
 148 the possibility to connect other handlers to these signals, which is what
 149 should be done in most cases when a viewer needs to interact with X in any
 150 way.
 151
 152
 153
 154 Signal emission and propagation is described there :
 155
 156 http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
 157
 158 For further information on the GTK main loop (now a wrapper over glib main loop)
 159 see :
 160
 161 http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
 162 http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
 163
 164
 165 For documentation on event handling in GTK/GDK, see :
 166
 167 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
 168 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
 169
 170
 171 Signals can be connected to handlers, emitted, propagated, blocked,
 172 stopped. See :
 173
 174 http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
 175
 176
 177
 178
 179 The "expose_event"
 180
 181 Provides the exposed region in the GdkEventExpose structure.
 182
 183 There are two ways of dealing with exposures. The first one is to directly draw
 184 on the screen and the second one is to draw in a pixmap buffer, and then to
 185 update the screen when necessary.
 186
 187 In the first case, the expose event will be responsible for registering hooks to
 188 process_traceset and require time intervals to the main window. So, in this
 189 scenario, if a part of the screen is damaged, the trace has to be read to
 190 redraw the screen.
 191
 192 In the second case, with a pixmap buffer, the expose handler is only responsible
 193 of showing the pixmap buffer on the screen. If the pixmap buffer has never
 194 been filled with a drawing, the expose handler may ask for it to be filled.
 195
 196 It can add dotted lines and such visual effects to enhance the user's
 197 experience.
 198
 199
 200 FIXME : explain other important events
 201
 202 */
 203
 204
 205
 206
 207 /*! \file viewer.h
 208  * \brief API used by the graphical viewers to interact with their top window.
 209  *
 210  * Main window (lttvwindow module) is the place to contain and display viewers.
 211  * Viewers (lttv plugins) interact with main window through this API.
 212  * This header file should be included in each graphic module.
 213  *
 214  */
 215
 216 #include <gtk/gtk.h>
 217 #include <ltt/ltt.h>
 218 #include <lttv/hook.h>
 219 #include <lttvwindow/common.h>
 220 #include <lttv/stats.h>
 221 //FIXME (not ready yet) #include <lttv/filter.h>
 222
 223
 224 /* Module Related API */
 225
 226
 227 /* constructor a the viewer */
 228 //FIXME explain LttvTracesetSelector and key
 229 typedef GtkWidget * (*lttvwindow_viewer_constructor)
 230                 (MainWindow * main_window, LttvTracesetSelector * s, char *key);
 231
 232
 233 /**
 234  * Function to register a view constructor so that main window can generate
 235  * a toolbar item for the viewer in order to generate a new instance easily.
 236  *
 237  * It should be called by init function of the module.
 238  *
 239  * @param pixmap Image shown on the toolbar item.
 240  * @param tooltip tooltip of the toolbar item.
 241  * @param view_constructor constructor of the viewer.
 242  */
 243
 244 void lttvwindow_register_toolbar
 245                             (char ** pixmap,
 246                              char *  tooltip,
 247                              lttvwindow_viewer_constructor view_constructor);
 248
 249
 250 /**
 251  * Function to unregister the viewer's constructor, release the space
 252  * occupied by pixmap, tooltip and constructor of the viewer.
 253  *
 254  * It will be called when a module is unloaded.
 255  *
 256  * @param view_constructor constructor of the viewer.
 257  */
 258
 259 void lttvwindow_unregister_toolbar
 260                             (lttvwindow_viewer_constructor view_constructor);
 261
 262
 263 /**
 264  * Function to register a view constructor so that main window can generate
 265  * a menu item for the viewer in order to generate a new instance easily.
 266  *
 267  * It will be called by init function of the module.
 268  *
 269  * @param menu_path path of the menu item.
 270  * @param menu_text text of the menu item.
 271  * @param view_constructor constructor of the viewer.
 272  */
 273
 274 void lttvwindow_register_menu(char *menu_path,
 275                               char *menu_text,
 276                               lttvwindow_viewer_constructor view_constructor);
 277
 278
 279 /**
 280  * Function to unregister the viewer's constructor, release the space
 281  * occupied by menu_path, menu_text and constructor of the viewer.
 282  *
 283  * It will be called when a module is unloaded.
 284  *
 285  * @param view_constructor constructor of the viewer.
 286  */
 287
 288 void lttvwindow_unregister_menu(lttvwindow_viewer_constructor view_constructor);
 289
 290
 291
 292 /* Viewer Instance Related API */
 293
 294 /**
 295  * Structure used as hook_data for the time_window_notify hook.
 296  */
 297 typedef struct _TimeWindowNotifyData {
 298   TimeWindow *new_time_window;
 299   TimeWindow *old_time_window;
 300 } TimeWindowNotifyData;
 301
 302
 303 /**
 304  * Function to register a hook function that will be called by the main window
 305  * when the time interval needs to be updated.
 306  *
 307  * This register function is typically called by the constructor of the viewer.
 308  *
 309  * @param main_win the main window the viewer belongs to.
 310  * @param hook hook that sould be called by the main window when the time
 311  *             interval changes. This hook function takes a
 312  *             TimeWindowNotifyData* as call_data.
 313  * @param hook_data hook data associated with the hook function. It will
 314  *                  be typically a pointer to the viewer's data structure.
 315  */
 316
 317 void lttvwindow_register_time_window_notify(MainWindow *main_win,
 318                                             LttvHook    hook,
 319                                             gpointer    hook_data);
 320
 321
 322 /**
 323  * Function to unregister the time_window notification hook.
 324  *
 325  * This unregister function is typically called by the destructor of the viewer.
 326  *
 327  * @param main_win the main window the viewer belongs to.
 328  * @param hook hook that sould be called by the main window when the time
 329  *             interval changes. This hook function takes a
 330  *             TimeWindowNotifyData* as call_data.
 331  * @param hook_data hook data associated with the hook function. It will
 332  *                  be typically a pointer to the viewer's data structure.
 333  */
 334
 335 void lttvwindow_unregister_time_window_notify(MainWindow *main_win,
 336                                               LttvHook    hook,
 337                                               gpointer    hook_data);
 338
 339
 340 /**
 341  * Function to register a hook function that will be called by the main window
 342  * when the traceset is changed. That means that the viewer must redraw
 343  * itself completely or check if it's affected by the particular change to the
 344  * traceset.
 345  *
 346  * This register function is typically called by the constructor of the viewer.
 347  *
 348  * @param main_win the main window the viewer belongs to.
 349  * @param hook hook that should be called whenever a change to the traceset
 350  *             occurs. The call_data of this hook is a NULL pointer.
 351  * @param hook_data hook data associated with the hook function. It will
 352  *                  be typically a pointer to the viewer's data structure.
 353  */
 354
 355 void lttvwindow_register_traceset_notify(MainWindow *main_win,
 356                                          LttvHook    hook,
 357                                          gpointer    hook_data);
 358
 359
 360 /**
 361  * Function to unregister the traceset_notify hook.
 362  *
 363  * @param main_win the main window the viewer belongs to.
 364  * @param hook hook that should be called whenever a change to the traceset
 365  *             occurs. The call_data of this hook is a NULL pointer.
 366  * @param hook_data hook data associated with the hook function. It will
 367  *                  be typically a pointer to the viewer's data structure.
 368  */
 369
 370 void lttvwindow_unregister_traceset_notify(MainWindow *main_win,
 371                                            LttvHook    hook,
 372                                            gpointer    hook_data);
 373
 374
 375 /**
 376  * Function to register a hook function for a viewer to set/update its
 377  * filter.
 378  *
 379  * FIXME : Add information about what a filter is as seen from a viewer and how
 380  * to use it.
 381  *
 382  * This register function is typically called by the constructor of the viewer.
 383  *
 384  * @param main_win the main window the viewer belongs to.
 385  * @param hook hook function called by the main window when a filter change
 386  *             occurs.
 387  * @param hook_data hook data associated with the hook function. It will
 388  *                  be typically a pointer to the viewer's data structure.
 389  */
 390
 391 void lttvwindow_register_filter_notify(MainWindow *main_win,
 392                                        LttvHook    hook,
 393                                        gpointer    hook_data);
 394
 395
 396 /**
 397  * Function to unregister a viewer's hook function which is used to
 398  * set/update the filter of the viewer.
 399  *
 400  * This unregistration is called by the destructor of the viewer.
 401  *
 402  * @param main_win the main window the viewer belongs to.
 403  * @param hook hook function called by the main window when a filter change
 404  *             occurs.
 405  * @param hook_data hook data associated with the hook function. It will
 406  *                  be typically a pointer to the viewer's data structure.
 407  */
 408
 409 void lttvwindow_unregister_filter_notify(MainWindow * main_win,
 410                                          LttvHook     hook,
 411                                          gpointer     hook_data);
 412
 413
 414 /**
 415  * Function to register a hook function for a viewer to set/update its
 416  * current time.
 417  *
 418  * @param main_win the main window the viewer belongs to.
 419  * @param hook hook function of the viewer that updates the current time. The
 420  *             call_data is a LttTime* representing the new current time.
 421  * @param hook_data hook data associated with the hook function. It will
 422  *                  be typically a pointer to the viewer's data structure.
 423  */
 424
 425 void lttvwindow_register_current_time_notify(MainWindow *main_win,
 426                                              LttvHook    hook,
 427                                              gpointer    hook_data);
 428
 429
 430 /**
 431  * Function to unregister a viewer's hook function which is used to
 432  * set/update the current time of the viewer.
 433  * @param main_win the main window the viewer belongs to.
 434  * @param hook hook function of the viewer that updates the current time. The
 435  *             call_data is a LttTime* representing the new current time.
 436  * @param hook_data hook data associated with the hook function. It will
 437  *                  be typically a pointer to the viewer's data structure.
 438  */
 439
 440 void lttvwindow_unregister_current_time_notify(MainWindow *main_win,
 441                                                LttvHook    hook,
 442                                                gpointer    hook_data);
 443
 444
 445 /**
 446  * Function to register a hook function for a viewer to set/update the
 447  * dividor of the hpane. It provides a way to make the horizontal
 448  * dividors of all the viewers linked together.
 449  *
 450  * @param main_win the main window the viewer belongs to.
 451  * @param hook hook function of the viewer that will be called whenever a
 452  *             dividor changes in another viewer. The call_data of this hook
 453  *             is a gint*. The value of the integer is the new position of the
 454  *             hpane dividor.
 455  * @param hook_data hook data associated with the hook function. It will
 456  *                  be typically a pointer to the viewer's data structure.
 457  */
 458
 459 void lttvwindow_register_dividor(MainWindow *main_win,
 460                                  LttvHook    hook,
 461                                  gpointer    hook_data);
 462
 463
 464 /**
 465  * Function to unregister a viewer's hook function which is used to
 466  * set/update hpane's dividor of the viewer.
 467  *
 468  * @param main_win the main window the viewer belongs to.
 469  * @param hook hook function of the viewer that will be called whenever a
 470  *             dividor changes in another viewer. The call_data of this hook
 471  *             is a gint*. The value of the integer is the new position of the
 472  *             hpane dividor.
 473  * @param hook_data hook data associated with the hook function. It will
 474  *                  be typically a pointer to the viewer's data structure.
 475  */
 476
 477 void lttvwindow_unregister_dividor(MainWindow *main_win,
 478                                    LttvHook    hook,
 479                                    gpointer    hook_data);
 480
 481
 482
 483 /**
 484  * This method reports the information to show on the status bar in the
 485  * main window.
 486  *
 487  * @param main_win the main window the viewer belongs to.
 488  * @param info the message which will be shown in the status bar.
 489  */
 490
 491 void lttvwindow_report_status(MainWindow *main_win, const char *info);
 492
 493
 494 /**
 495  * Function to set the time interval of the current tab.a
 496  *
 497  * @param main_win the main window the viewer belongs to.
 498  * @param time_interval pointer to the time interval value.
 499  */
 500
 501 void lttvwindow_report_time_window(MainWindow       *main_win,
 502                                    const TimeWindow *time_window);
 503
 504 /**
 505  * Function to set the current time/event of the current tab.
 506  * It will be called by a viewer's signal handle associated with
 507  * the button-release-event signal
 508  * @param main_win the main window the viewer belongs to.
 509  * @param time a pointer where time is stored.
 510  */
 511
 512 void lttvwindow_report_current_time(MainWindow    *main_win,
 513                                     const LttTime *time);
 514
 515
 516 /**
 517  * Function to set the position of the hpane's dividor (viewer).
 518  * It will typically be called by a viewer's signal handle associated
 519  * with the motion_notify_event event/signal.
 520  *
 521  * @param main_win the main window the viewer belongs to.
 522  * @param position position of the hpane's dividor.
 523  */
 524
 525 void lttvwindow_report_dividor(MainWindow *main_win, gint position);
 526
 527 /**
 528  * Function to set the focused viewer of the tab.
 529  * It will be called by a viewer's signal handle associated with
 530  * the grab_focus signal of all widgets in the viewer.
 531  *
 532  * @param main_win the main window the viewer belongs to.
 533  * @param top_widget the top widget containing all the other widgets of the
 534  *                   viewer.
 535  */
 536 void lttvwindow_report_focus(MainWindow *main_win,
 537                              GtkWidget  *top_widget);
 538
 539
 540
 541 /* Structure sent to the time request hook */
 542                                                 /* Value considered as empty */
 543 typedef struct _EventsRequest {
 544   LttTime                     start_time,       /* Unset : { 0, 0 }          */
 545   LttvTracesetContextPosition start_position,   /* Unset : num_traces = 0    */
 546   LttTime                     end_time,         /* Unset : { 0, 0 }          */
 547   guint                       num_events,       /* Unset : G_MAXUINT         */
 548   LttvTracesetContextPosition end_position,     /* Unset : num_traces = 0    */
 549   LttvHooksById              *before_traceset,  /* Unset : NULL              */
 550   LttvHooksById              *before_trace,     /* Unset : NULL              */
 551   LttvHooksById              *before_tracefile, /* Unset : NULL              */
 552   LttvHooksById              *middle,           /* Unset : NULL              */
 553   LttvHooksById              *after_tracefile,  /* Unset : NULL              */
 554   LttvHooksById              *after_trace,      /* Unset : NULL              */
 555   LttvHooksById              *after_traceset    /* Unset : NULL              */
 556 } EventsRequest;
 557
 558
 559 /**
 560  * Function to request data in a specific time interval to the main window. The
 561  * time request servicing is differed until the glib idle functions are
 562  * called.
 563  *
 564  * The viewer has to provide hooks that should be associated with the event
 565  * request.
 566  *
 567  * Either start time or start position must be defined in a EventRequest
 568  * structure for it to be valid.
 569  *
 570  * end_time, end_position and num_events can all be defined. The first one
 571  * to occur will be used as end criterion.
 572  *
 573  * @param main_win the main window the viewer belongs to.
 574  * @param events_requested the structure of request from.
 575  */
 576
 577 void lttvwindow_events_request(MainWindow    *main_win,
 578                                EventsRequest  events_request);
 579
 580 /**
 581  * Function to get the life span of the traceset
 582  *
 583  * @param main_win the main window the viewer belongs to.
 584  * @return pointer to a time interval : the life span of the traceset.
 585  */
 586
 587 const TimeInterval *lttvwindow_get_time_span(MainWindow *main_win);
 588
 589 /**
 590  * Function to get the current time window of the current tab.
 591  *
 592  * @param main_win the main window the viewer belongs to.
 593  * @return a pointer to the current tab's time interval.
 594  */
 595
 596 const TimeWindow *lttvwindow_get_time_window(MainWindow *main_win);
 597
 598
 599 /**
 600  * Function to get the current time of the current tab.
 601  *
 602  * @param main_win the main window the viewer belongs to.
 603  * @return a pointer to the current tab's current time.
 604  */
 605
 606 const LttTime *lttvwindow_get_current_time(MainWindow *main_win);
 607
 608
 609 /**
 610  * Function to get the filter of the current tab.
 611  * @param main_win, the main window the viewer belongs to.
 612  * @param filter, a pointer to a filter.
 613  */
 614
 615 //FIXME
 616 typedef void lttv_filter;
 617 //FIXME
 618 const lttv_filter *lttvwindow_get_filter(MainWindow *main_win);
 619
 620
 621 /**
 622  * Function to get the stats of the traceset
 623  * It must be non const so the viewer can modify it.
 624  * FIXME : a set/get pair of functions would be more appropriate here.
 625  * @param main_win the main window the viewer belongs to.
 626  * @return A pointer to Traceset statistics.
 627  */
 628
 629 LttvTracesetStats* lttvwindow_get_traceset_stats(MainWindow *main_win);
 630
 631 /**
 632  * Function to get the context of the traceset
 633  * It must be non const so the viewer can add and remove hooks from it.
 634  * @param main_win the main window the viewer belongs to.
 635  * @return Context of the current tab.
 636  */
 637
 638
 639 LttvTracesetContext* lttvwindow_get_traceset_context(MainWindow *main_win);
 640
 641