-update: called when the windows is exposed/resized, the time window is changed,
- the current time is changed or the traceset is changed (different
- traceset or traces added/removed. Redraw or register hooks.
-process_trace for update: hooks called
-update_end: remove the hooks.
-
-There may be different versions of update functions for the different cases,
-or the type of update may be described in an argument. The expose method
-normally provides the exposed region. This should be used to register hooks
-to process_traceset but also tell about the time interval for which it is
-required. Then, a expose_end will be required to remove the hooks and finish
-the display as needed.
-
-In most cases, the enclosing window knows about updates such as a new trace
-added to a traceset, time window updates caused by scrolling and even
-expose events. There are a few cases, however, where updates are caused by
-actions known by a view instance. For example, clicking in a view may update
-the current time; all viewers within the same window must be told about the
-new current time to change the currently highlighted time point. A viewer
-reports such events by calling report_update on its lttvwindow. The lttvwindow
-will thereafter call update for each of its contained viewers.
-
-
-Things that can happen to a viewer:
-
-update_time_window
-update_current_time
-update_traceset
-update_filter
-show_viewer
-update_dividor
-?? Reshape, damage as gtk methods ??
-
-Things that a viewer can do:
-
-update_status
-set_time_window
-set_current_time
-update_traceset?
-update_filter?
-show_viewer?
-set_focused_pane
-set_hpane_dividor
+
+Reporting Changes to the Main Window
+
+In most cases, the enclosing window knows about updates such as described in the
+Notification section higher. There are a few cases, however, where updates are
+caused by actions known by a view instance. For example, clicking in a view may
+update the current time; all viewers within the same window must be told about
+the new current time to change the currently highlighted time point. A viewer
+reports such events by calling lttvwindow_report_current_time on its lttvwindow.
+The lttvwindow will consequently call current_time_notify for each of its
+contained viewers.
+
+
+Available report methods are :
+
+lttvwindow_report_status : reports the text of the status bar.
+lttvwindow_report_time_window : reports the new time window.
+lttvwindow_report_current_time : reports the new current time.
+lttvwindow_report_dividor : reports the new horizontal dividor's position.
+lttvwindow_report_focus : One on the widgets in the viewer has the keyboard's
+ focus from GTK.
+
+
+
+Requesting Events to Main Window
+
+Events can be requested by passing a EventsRequest structure to the main window.
+They will be delivered later when the next g_idle functions will be called.
+Event delivery is done by calling the event hook for this event ID, or the
+main event hooks. A pointer to the EventsRequest structure is passed as
+hook_data to the event hooks of the viewers.
+
+EventsRequest consists in
+- a pointer to the viewer specific data structure
+- a start timestamp or position
+- a stop_flag, ending the read process when set to TRUE
+- a end timestamp and/or position and/or number of events to read
+- hook lists to call for traceset/trace/tracefile begin and end, and for each
+ event (event hooks and event_by_id hooks).
+
+The main window will deliver events for every EventRequests it has pending
+through an algorithm that guarantee that all events requested, and only them,
+will be delivered to the viewer between the call of the tracefile_begin hooks
+and the call of the tracefile_end hooks.
+
+If a viewer wants to stop the event request at a certain point inside the event
+hooks, it has to set the stop_flag to TRUE and return TRUE from the hook
+function. Then return value will stop the process traceset. Then, the main
+window will look for the stop_flag and remove the EventRequests from its lists,
+calling the process_traceset_end for this request (it removes hooks from the
+context and calls the after hooks).
+
+It no stop_flag is rose, the end timestamp, end position or number of events to
+read has to be reached to determine the end of the request. Otherwise,
+the end of traceset does determine it.
+
+
+GTK Events
+
+Events and Signals
+
+GTK is quite different from the other graphical toolkits around there. The main
+difference resides in that there are many X Windows inside one GtkWindow,
+instead of just one. That means that X events are delivered by the glib main
+loop directly to the widget corresponding to the GdkWindow affected by the X
+event.
+
+Event delivery to a widget emits a signal on that widget. Then, if a handler
+is connected to this widget's signal, it will be executed. There are default
+handlers for signals, connected at class instantiation time. There is also
+the possibility to connect other handlers to these signals, which is what
+should be done in most cases when a viewer needs to interact with X in any
+way.
+
+
+
+Signal emission and propagation is described there :
+
+http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
+
+For further information on the GTK main loop (now a wrapper over glib main loop)
+see :
+
+http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
+http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
+
+
+For documentation on event handling in GTK/GDK, see :
+
+http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
+http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
+
+
+Signals can be connected to handlers, emitted, propagated, blocked,
+stopped. See :
+
+http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
+
+
+
+
+The "expose_event"
+
+Provides the exposed region in the GdkEventExpose structure.
+
+There are two ways of dealing with exposures. The first one is to directly draw
+on the screen and the second one is to draw in a pixmap buffer, and then to
+update the screen when necessary.
+
+In the first case, the expose event will be responsible for registering hooks to
+process_traceset and require time intervals to the main window. So, in this
+scenario, if a part of the screen is damaged, the trace has to be read to
+redraw the screen.
+
+In the second case, with a pixmap buffer, the expose handler is only responsible
+of showing the pixmap buffer on the screen. If the pixmap buffer has never
+been filled with a drawing, the expose handler may ask for it to be filled.
+
+The interest of using events request to the main window instead of reading the
+events directly from the trace comes from the fact that the main window
+does merge requests from the different viewers in the same tab so that the
+read loop and the state update is shared. As viewers will, in the common
+scenario, request the same events, only one pass through the trace that will
+call the right hooks for the right intervals will be done.
+
+When the traceset read is over for a events request, the traceset_end hook is
+called. It has the responsibility of finishing the drawing if some parts
+still need to be drawn and to show it on the screen (if the viewer uses a pixmap
+buffer).
+
+It can add dotted lines and such visual effects to enhance the user's
+experience.
+
+
+FIXME : explain other important events
+
projects / lttv.git / blobdiff