frame_t Struct Reference

Data structure for the Synema frames. More...

#include <frame-common.h>

Collaboration diagram for frame_t:
Collaboration graph
[legend]

Data Fields

gchar * type
 Type of the monitoring tool for this frame.
size_ratio_t size
 Size ratio to use for that frame.
machine_tdisplay_machine
 The machine for which data should be displayed.
time_period_t display_period
 Period for which the data should be shown.
gdouble avg_refresh_time
 Last calculated average refresh time for a frame.
gdouble avg_refresh_timeout
 Time left until recalculating the average refresh time.
struct __frame_table_t * parent
 The frames table to which this frame is attached.
gboolean hidden
 Tells whether the frame is being displayed or is in an hidden frames stack.
guint id
 An unique identifier for the frame.
frame_error_t last_err
 The type of the last error that occurred.
void * priv
 A pointer to data specific to a monitoring tool.
GList *(* build_func_list )()
 Called during frame init, returns a list of functions that you want to be available for frames of your plugin's type.
GList *(* build_time_periods )()
 Called during frame init, returns a list of time periods available for your plugin.
int(* init_private )(struct __frame_t *)
 Called automatically when the frame is initialised.
int(* restore_private )(struct __frame_t *, GKeyFile *)
 Called automatically after a frame has been restored.
int(* save_private )(struct __frame_t *, GKeyFile *)
 Called automatically when a frame is saved.
int(* free_private )(struct __frame_t *)
 Called automatically before the frame is destroyed.
int(* is_refreshing_needed )(struct __frame_t *)
 Tells if the frame's images should be recomputed.
int(* refresh_content )(struct __frame_t *)
 Computes the new images with ploticus.
int(* draw_area )(struct __frame_t *, cairo_t *)
 Draws what needs to be displayed in a cairo surface.
char *(* get_display_name )(struct __frame_t *)
 Returns the display name to use for the frame.
int(* frame_size_changed )(struct __frame_t *)
 Reflets a frame size change in the plugin's internal data.
int(* display_machine_changed )(struct __frame_t *)
 Reflects the display machine change in the plugin's internal data.
int(* time_period_changed )(struct __frame_t *)
 Reflects the time period change in the plugin's internal data.
int(* button_press_handler )(struct __frame_t *, GdkEventButton *)
 Handles mouse button press events.
int(* button_release_handler )(struct __frame_t *, GdkEventButton *)
 Handles mouse button release events.

Detailed Description

Data structure for the Synema frames.

This is a frame in which data will be displayed about a monitoring tool. The struct contains all the data necessary, including the drawing area where each plugin developer will display it's data, widgets to switch machines and display periods, etc.

The struct also contains pointers to functions that must be written by each plugin developer.

Definition at line 73 of file frame-common.h.


Field Documentation

Last calculated average refresh time for a frame.

Definition at line 82 of file frame-common.h.

Time left until recalculating the average refresh time.

Definition at line 83 of file frame-common.h.

Called during frame init, returns a list of functions that you want to be available for frames of your plugin's type.

Remarks:
The functions will be displayed in the same order they're discovered in the list.
If you don't want a menu with custom functions, just return -1

In this function, you should make a GList containing func_list_t structs that all contain a display name and a pointer to a function.

These functions will be added in a frame-specific menu, in the order they are found.

The calling function is in charge of freeing the list.

Returns:
a list of func_list_t that will be added to the frame's menu

Called during frame init, returns a list of time periods available for your plugin.

Remarks:
If you want the frame to begin with a particular time period, put it in the beginning of the list. The calling function may not respect your choice.
You should always include the live mode.

In this function, you should create a GList of time_period_t structs that you want to be available for your frame. It will be automatically called during the initialisation of the frame. The list will be freed automatically by the calling function.

Returns:
a list of time_period_t structures
int(* frame_t::button_press_handler)(struct __frame_t *, GdkEventButton *)

Handles mouse button press events.

Note:
This function is optional.

You should use this function to handle mouse button press events. The GdkEvent parameter will give you the coordinates, the mouse button pressed, and it will tell if it is a single, double or triple click.

You can then use this information to simulate a button click if the coordinates are in a rectangle drawn with cairo.

Remarks:
Coordinates are reachable with event->x and event->y which are of type double.
event->button will be 1 for left buttons, 2 for middle buttons, and 3 for right buttons.
event->type will be GDK_2BUTTON_PRESS for a double click, and GDK_3BUTTON_PRESS for a triple click. Note that there will also be 2 (resp. 3) GDK_BUTTON_PRESS sent at the same time.
Parameters:
[out] frame_t * the frame on which the event occurred
[in] GdkEventButton * the data about the button press event
Returns:
0 if no error occurrs, another value otherwise
int(* frame_t::button_release_handler)(struct __frame_t *, GdkEventButton *)

Handles mouse button release events.

Note:
This function is optional.

You should use this function to handle mouse button release events. The GdkEvent parameter will give you the coordinates, the mouse button releaseed, and it will tell if it is a single, double or triple click.

You can then use this information to simulate a button click if the coordinates are in a rectangle drawn with cairo.

Remarks:
Coordinates are reachable with event->x and event->y which are of type double.
event->button will be 1 for left buttons, 2 for middle buttons, and 3 for right buttons.
It's not possible to know if a button release is a single or double click.
Parameters:
[out] frame_t * the frame on which the event occurred
[in] GdkEventButton * the data about the button release event
Returns:
0 if no error occurrs, another value otherwise

The machine for which data should be displayed.

Definition at line 78 of file frame-common.h.

int(* frame_t::display_machine_changed)(struct __frame_t *)

Reflects the display machine change in the plugin's internal data.

Warning:
It's better not to do anything heavy in this function as it can be called several times in a raw.

In this function, you should make sure your internal data is in sync with the new machine, so that the data computed by ploticus matches this machine.

Parameters:
[in,out] frame_t * the frame whose machine changed
Returns:
-1 if an error occurred, 0 otherwise

Period for which the data should be shown.

Definition at line 79 of file frame-common.h.

int(* frame_t::draw_area)(struct __frame_t *, cairo_t *)

Draws what needs to be displayed in a cairo surface.

Warning:
Resource hungry operations are strictly prohibited in this function. It can be called dozens times per second.

This function is where you should draw lines, text and pictures to the screen. It contains a cairo surface clipped to the region where redrawing is needed. You should only do cairo and gdk drawing here and you should not compute images with ploticus.

Parameters:
[in] frame_t * the frame which needs to be redrawn
[out] cairo_t * the cairo surface in which you should draw
Returns:
0 if drawing went well, another value otherwise
int(* frame_t::frame_size_changed)(struct __frame_t *)

Reflets a frame size change in the plugin's internal data.

Warning:
It's better not to do anything heavy in this function as it can be called several times in a raw.

This function may or may not be needed depending on your implementation. It's the place where you should change your internal data to make sure the drawing function now draws on a surface matching the new size of the drawing area.

Parameters:
[in,out] frame_t * the frame whose size changed
Returns:
-1 if an error occurred, 0 otherwise
int(* frame_t::free_private)(struct __frame_t *)

Called automatically before the frame is destroyed.

In this function, you should free all the data pointed by the priv member. Do not free anything else, it will be taken care of by the free function calling this one before destroying the frame.

Parameters:
[out] frame_t * the frame for which private data should be freed
Returns:
0 if destruction went well, another value otherwise
char*(* frame_t::get_display_name)(struct __frame_t *)

Returns the display name to use for the frame.

This function returns a static string that can be used as a display name for the frame in the main GUI.

Parameters:
[in] frame_t * the frame whose name is wanted
Returns:
the frame's name
gboolean frame_t::hidden

Tells whether the frame is being displayed or is in an hidden frames stack.

Definition at line 85 of file frame-common.h.

guint frame_t::id

An unique identifier for the frame.

Definition at line 86 of file frame-common.h.

int(* frame_t::init_private)(struct __frame_t *)

Called automatically when the frame is initialised.

You should initialise your private_data structure and do anything you need to do right after frame initialisation in this function.

Parameters:
[in,out] frame_t * the frame that has just been initialised
Returns:
0 if initialisation went well, another value otherwise
int(* frame_t::is_refreshing_needed)(struct __frame_t *)

Tells if the frame's images should be recomputed.

Warning:
Your implementation of this function must be very fast.

This function tells if reports changed and the ploticus-generated pictures need to be drawn again.

Parameters:
[in] frame_t * the frame which you want to check
Returns:
1 if refreshing is needed, 0 if not, a negative value if error

The type of the last error that occurred.

Definition at line 87 of file frame-common.h.

struct __frame_table_t* frame_t::parent [read]

The frames table to which this frame is attached.

Definition at line 84 of file frame-common.h.

A pointer to data specific to a monitoring tool.

Definition at line 106 of file frame-common.h.

int(* frame_t::refresh_content)(struct __frame_t *)

Computes the new images with ploticus.

This function tells if reports changed and the ploticus-generated images need to be drawn again. You can do anything such as generating these images and computing textual reports in this function.

You should only compute the images for the current set of machine and time period. However, you can compute them for several sizes.

Parameters:
[in,out] frame_t * the frame for which data should be refreshed
Returns:
0 if refreshing went well, another value otherwise
int(* frame_t::restore_private)(struct __frame_t *, GKeyFile *)

Called automatically after a frame has been restored.

Note:
This function is optional.

In this function, you should load from the GKeyFile anything you saved in the save_private function. This is meant to allow you to restore the state your private data had when your frame was saved.

Parameters:
[out] frame_t * the frame whose private data should be restored
[in] GKeyFile * the file containing the data to restore
Returns:
0 if all the data was properly restored, another value otherwise
int(* frame_t::save_private)(struct __frame_t *, GKeyFile *)

Called automatically when a frame is saved.

Note:
This function is optional.

In this function, you should save in a GKeyFile anything in the frame's private data you need to can restore the state of the frame later.

Parameters:
[out] frame_t * the frame whose private data should be saved
[in] GKeyFile * the file in which the data should be saved
Returns:
0 if all the data was entirely saved, another value otherwise

Size ratio to use for that frame.

Definition at line 77 of file frame-common.h.

int(* frame_t::time_period_changed)(struct __frame_t *)

Reflects the time period change in the plugin's internal data.

Warning:
It's better not to do anything heavy in this function as it can be called several times in a raw.

In this function, you should make sure your internal data is in sync with the new time period, so that the data computed by ploticus matches this time period.

Parameters:
[in,out] frame_t * the frame whose time period changed
Returns:
-1 if an error occurred, 0 otherwise
gchar* frame_t::type

Type of the monitoring tool for this frame.

Definition at line 74 of file frame-common.h.


The documentation for this struct was generated from the following file:
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on Tue Jan 12 00:48:45 2010 for ENSIBSynema by  doxygen 1.6.1