DataTrackWidget Class Reference

DataTrackWidget is the heart of the graph rendering classes. More...

#include <DataTrackWidget.h>

Inheritance diagram for DataTrackWidget:
TrackWidget AnnotationTrackWidget DataDensityTrackWidget ScoreTrackWidget SequenceTrackWidget BarLineRelNotationTrackWidget

List of all members.

Public Slots

void update_graphics (GraphicsEvent *)
void update_highlight (int, int)
void receive_key_event (int, bool)
void set_score_scale_bounds (double, double)

Signals

void select_state_change (DataTrackWidget *)
void mouse_dragged (int, int)
void new_info (InfoEvent *)

Public Member Functions

 DataTrackWidget (GVec *, Preferences *preferences=0, QWidget *parent=0)
virtual QString type_name ()=0
virtual GVecget_gvec ()
bool is_selected ()
void set_selected (bool)
void set_manual_highlights (GVecGFF *)
void set_feature_highlights (GVecGFF *)
void set_filter (SearchFilterEvent *)
void set_filter (SearchFilterEvent *, GVecGFF *, vector< size_t >)
SearchFilterEventget_filter ()
bool has_active_filter ()
void clear_filter ()
void set_strand (StrandGraphicsEvent::Option)
bool visible (QString)
void visible (QString, bool)
void copy_state (DataTrackWidget *)
ColorGraphicsEventget_graphics_color_status ()
AxisGraphicsEventget_graphics_axis_status ()
virtual GraphControlsWidgetget_graph_controls_widget ()
virtual QString get_graph_explanation ()
double score_scale_max ()
double score_scale_min ()
virtual long last_bp ()
virtual bool has_focus (QString)
void get_selected_drawable_rects (vector< QRect > &)
void align_drawables (const QRect &, DrawableGraphicsAlignEvent::aligntype)

Protected Member Functions

virtual size_t starting_index ()
virtual size_t stopping_index ()
virtual size_t subsample_rate (size_t, size_t)
size_t pass_pt_start (size_t)
size_t low_res_cutoff ()
void resizeEvent (QResizeEvent *)
void mousePressEvent (QMouseEvent *)
void mouseReleaseEvent (QMouseEvent *)
void mouseDoubleClickEvent (QMouseEvent *)
void mouseMoveEvent (QMouseEvent *)
virtual void type_specific_graphics_event (GraphTypeSpecificGraphicsEvent *)
void draw_background (QPainter *)
void draw_selected (QPainter *)
void draw_vertical_cursor (QPainter *)
void draw_highlight (QPainter *)
void draw_drawables (QPainter *)
void draw_name (QPainter *, QString, int, int)
void draw_data (QPainter *)
virtual void draw_data_record (QPainter *, size_t, vector< QColor * > *colors=0)
virtual void draw_data_record_lr (QPainter *, size_t, vector< QColor * > *colors=0)

Protected Attributes

GVecgvec
float h
float w
bool show_file_name
bool show_y_axis
bool selected
SearchFilterEventfilter
bool has_filter
GVecGFFpass_regions
vector< size_t > pass_indices
set< QString > invisible_sequences
GVecGFFmanual_highlights
GVecGFFfeature_highlights
int lb_mouse_press_x
int lb_mouse_press_y
int lb_mouse_drag_x
int lb_mouse_drag_y
bool shift_key_on
vector< Drawable * > drawable_objects
TrackNameDrawablename_drawable
bool drawable_moveable
StrandGraphicsEvent::Option strand_stat
QString strand
float h3u
float h3l

Detailed Description

DataTrackWidget is the heart of the graph rendering classes.

DataTrackWidget is the class from which all track graphic classes are intended to be derived, ie. it and its progeny do the actual drawing work.

DataTrackWidget is abstract, but at the time of this writing there is but a single method that is required, DataTrackWidget::type_name( ). This method does nothing more than return a, hopefully, unique but informal name for the type, ie. it's not necessary to use the class name or similar, just something that might help distinguish it from other graph types when an end-user is toggling between graph type options for their data.

Although not strictly enforced, there's another method that every derivative class will want to implement: QWidget::paintEvent( QPaintEvent* ). DataTrackWidget is itself derived from Qt's QWidget. To implement class specific drawing, the class must reimplement QWidget::paintEvent( QPaintEvent* ). The paintEvent method is called when the application is rendering widgets (including DataTrackWidget widgets) to the screen. Normally a user doesn't need to call it, although, code can trigger a repaint by calling QWidget::repaint( ) or QWidget::update( ). See the Qt documentation for more information. For an example of a reimplemented paintEvent method, check out ScoreTrackWidget.cpp or AnnotationTrackWidget.cpp.

Many of the methods here draw some common part of a graph such as DataTrackWidget::draw_background( QPainter* ) or DataTrackWidget::draw_name( QPainter* ). Use these methods within the paintEvent method when needed. One very important method, however, is DataTrackWidget::draw_data( QPainter* ). In general, the version supplied with DataTrackWidget should do the job for most applications and won't need overriding. Its main tasks: find the start and stop indices bounding all records that need to be drawn for the current view then cycle through them applying the subsample factor and any necessary filtering.

If using DataTrackWidget::draw_data( QPainter* ), however, an implementation must override the following two methods:

  void DataTrackWidget::draw_data_record   ( QPainter*, size_t, vector<QColor*>* colors = 0 )
  void DataTrackWidget::draw_data_record_lr( QPainter*, size_t, vector<QColor*>* colors = 0 )
  

These methods are where the actual per record drawing code should go. DataTrackWidget::draw_data( QPainter* ) will call one or the other of these methods for each record. Using the value returned from DataTrackWidget::low_res_cutoff( ), draw_data will determine whether to use the high resolution (draw_data_record) or low resolution (draw_data_record_lr) version of draw_data_record. The expectation is that the low resolution version produces a simpler, and hence quicker to render, glyph.


Constructor & Destructor Documentation

DataTrackWidget::DataTrackWidget ( GVec gvec,
Preferences p = 0,
QWidget *  parent = 0 
)

DataTrackWidget is abstract, so, of course, the only time this constructor is likely to be called is by the constructor of an implementing class.

The GVec pointer that is the first argument here can be any level in a GVec tree the implementor desires so long as the implementing class is aware, usually the case will be one vector of records per data track and the parameter pointing to a leaf node, record bearing GVec object and one should be aware that a method like DataTrackWidget::starting_index( ) or DataTrackWidget::draw_data( QPainter* painter ) acts on a specific record bearing GVec (usually a leaf node). Indeed, changing what GVec object is pointed to enables data track to draw multiple recrod vectors into a shared track. See DataTrackWidget description for more information on this idiom.


Member Function Documentation

void DataTrackWidget::align_drawables ( const QRect &  r,
DrawableGraphicsAlignEvent::aligntype  alignment 
)

Align Drawable objects on a grid.

Parameters:
const QRect& r the location to which the Drawable object will be translated
DrawableGraphicsAlignEvent::aligntype alignment
void DataTrackWidget::clear_filter (  ) 

Remove any filter associated with this track.

void DataTrackWidget::copy_state ( DataTrackWidget igraph  ) 

A graph might be copied or a track of data may have its graph type changed, in which case one graph is destroyed and the new graph created. Prior to displaying the new graph (and prior to destroying any old graphs), this method helps in transfering the state of the graph such as colors, ordinate scales, drawable objects, etc... (see code for details).

The method would be called on the new graph and passed the old graph.

Parameters:
DataTrackWidget* the graph from which to copy the state
void DataTrackWidget::draw_background ( QPainter *  painter  )  [protected]

Draws a rectangle the size of the track in the background color.

Parameters:
QPainter* 
void DataTrackWidget::draw_data ( QPainter *  painter  )  [protected]

When implementing a DataTrackWidget class, this method should be called from that class's paintEvent method. Its purpose is to determine the first and last records that need to be drawn and then cycle through the GVec record vector and paint a glyph for each record, skipping filtered records and advancing by the appropriate subsample factor, this is the thing that draws records!

This method, however, does not contain actualy drawing code. Instead it calls one of two virtual methods based on the current resolution and resolution threshold (lr => low resolution):

  virtual void draw_data_record   ( QPainter*, size_t, vector<QColor*>* colors = 0 );
  virtual void draw_data_record_lr( QPainter*, size_t, vector<QColor*>* colors = 0 );
  

Implementations should put actual drawing related code in overridden versions of these two methods. See AnnotationTrackWidget as an example.

Parameters:
QPainter* see Qt QPainter and QWidget classes for more information
void DataTrackWidget::draw_data_record ( QPainter *  painter,
size_t  i,
vector< QColor * > *  colors = 0 
) [protected, virtual]

This method is normally called from DataTrackWidget::draw_data( QPainter* painter ); however, nothing stops an implementation from using it directly. More importaly, the version supplied here does nothing. Reimplement it to provide the per record glyph drawing, ie. code that actually draws 1 single record should go in here.

The color parameter comes as a vector; all of the colors in this vector will be used one after another. When using low alpha values (opacity), this can help create layering affects.

Parameters:
QPainter* this is the painter created in a classes paintEvent( QPaintEvent* ) method
size_t the index of the record to be drawn
vector<QColor*>* the colors to paint the record
See also:
DataTrackWidget::draw_data_record_lr( QPainter* painter, size_t i, vector<QColor*>* colors )

Reimplemented in AnnotationTrackWidget, BarLineRelNotationTrackWidget, and ScoreTrackWidget.

void DataTrackWidget::draw_data_record_lr ( QPainter *  painter,
size_t  i,
vector< QColor * > *  colors = 0 
) [protected, virtual]

This is the low resolution version of DataTrackWidget::draw_data_record( QPainter* painter, size_t i, vector<QColor*>* colors ).

Generally, this method can be used to create a simpler (faster) or otherwise more useful record glyph at far out zoom levels.

Parameters:
QPainter* this is the painter created in a classes paintEvent( QPaintEvent* ) method
size_t the index of the record to be drawn
vector<QColor*>* the colors to paint the record
See also:
DataTrackWidget::draw_data_record( QPainter* painter, size_t i, vector<QColor*>* colors )

Reimplemented in AnnotationTrackWidget, BarLineRelNotationTrackWidget, and ScoreTrackWidget.

void DataTrackWidget::draw_drawables ( QPainter *  painter  )  [protected]

Draws the Drawable objects set for this class. Drawable objects are glyphs adorning the track like track name, a y-axis or whateverelse one might create and add to the vector of Drawable objects.

Parameters:
QPainter* 
void DataTrackWidget::draw_highlight ( QPainter *  painter  )  [protected]

Draws both feature and manual highlights, if there are any, in the highlight color.

Parameters:
QPainter* 
void DataTrackWidget::draw_name ( QPainter *  p,
QString  name,
int  x,
int  xn 
) [protected]

Draws a record name onto the graph in the text color. The caller must take care that the name lines up in some appropriate manner with the other parts of the record glyph.

Parameters:
QPainter* 
QString name that will be drawn
int x start point to draw name in screen pixel coordinates
int xn end point to draw name in screen pixel coordinates
void DataTrackWidget::draw_selected ( QPainter *  painter  )  [protected]

Draws a highlight around the track in the text color to indicated that the track is selected. However, the method makes no check whether the track actually is in a selected state or not.

Parameters:
QPainter* 
See also:
DataTrackWidget::is_selected( )
void DataTrackWidget::draw_vertical_cursor ( QPainter *  painter  )  [protected]

Draws the vertical cursor, if it's visible, across the track as a dotted line in the text color.

Parameters:
QPainter* 
See also:
TrackWidget::set_show_vertical_cursor( bool tf )
SearchFilterEvent * DataTrackWidget::get_filter (  ) 
Returns:
SearchFilterEvent* the filter associated with this track
GraphControlsWidget * DataTrackWidget::get_graph_controls_widget (  )  [virtual]

Graphs are likely to have control mechanisms that are particular to how they render data. For instance, in a histogram one would like to be able to set the bin size. The GraphControlsWidget class provides a mechanism for a graph to implement such controls. This method would be used to retrieve the track specific widget.

In left unimplemented, this default returns 0.

Returns:
GraphControlsWidget*
See also:
DataTrackWidget::type_specific_graphics_event( GraphTypeSpecificGraphicsEvent* )

Reimplemented in BarLineRelNotationTrackWidget, DataDensityTrackWidget, and SequenceTrackWidget.

QString DataTrackWidget::get_graph_explanation (  )  [virtual]

Complicated visualization often require some explanation! This method can be used by an implementing class to provide such descriptions, for instance, to display in an info box or pop-up.

Here, the method returns an empty QString

Returns:
QString
AxisGraphicsEvent * DataTrackWidget::get_graphics_axis_status (  ) 

This method was originally created to support edit boxes that allowed a user to textually coerce the x axis. Certainly, it could have other uses anywhere one might want to know what the axis are currently set to.

Returns:
AxisGraphicsEvent
ColorGraphicsEvent * DataTrackWidget::get_graphics_color_status (  ) 

This method returns info about the tracks color appearance. This might be useful, for instance, to a widget responsible for updating color info or, perhaps, for another track that would like to have matching colors.

Returns:
ColorGraphicsEvent
GVec * DataTrackWidget::get_gvec (  )  [virtual]
Returns:
the GVec object currently set

Reimplemented in BarLineRelNotationTrackWidget.

void DataTrackWidget::get_selected_drawable_rects ( vector< QRect > &  vec  ) 

Returns a list of the locations of drawable objects, ie drawable objects selected via a double mouse clicks, for the purpose of translating their locations.

Parameters:
vector< QRect >& a vector onto which the locations are pushed
bool DataTrackWidget::has_active_filter (  ) 

Indicates whether a data record filter (via SearchFilterEvent) has been set for this track.

Returns:
is there a filter currently acting on this track?
bool DataTrackWidget::has_focus ( QString  focus  )  [virtual]

A DataTrackWidget is considered to have the named sequence focus if its currently set gvec has that named sequence as focus.

Parameters:
QString focus a sequence name that may be the focus
Returns:
whether the parameter is the current sequence focus
bool DataTrackWidget::is_selected (  ) 
Returns:
select state
See also:
DataTrackWidget::set_selected( bool tf )
long DataTrackWidget::last_bp (  )  [virtual]
Returns:
the value of GVec::last_bp( ) for the track's currently set GVec object

Reimplemented in BarLineRelNotationTrackWidget.

size_t DataTrackWidget::low_res_cutoff (  )  [protected]

Here this method returns a constant, 350. That value is used to determine the threshold number of data points for switching between low resolution glyphs (fast rendering) and high resolution glyphs (generally more informative).

Reimplemented in AnnotationTrackWidget, and BarLineRelNotationTrackWidget.

void DataTrackWidget::mouseDoubleClickEvent ( QMouseEvent *  me  )  [protected]

This is another method overridden from QWidget. Calls to this method are handled by Qt library code in general. If overridding this method, consider explicitly calling this version there as it contains code for selecting a graph as well as Drawable objects within the graph.

Parameters:
QMouseEvent* see Qt QWidget documentation
void DataTrackWidget::mouseMoveEvent ( QMouseEvent *  me  )  [protected]

Yet another method overridden from QWidget. Calls to this method are handled by Qt library code in general. If overridding this method, consider explicitly calling this version there as it contains code for moving Drawable objects.

Parameters:
QMouseEvent* see Qt QWidget documentation
void DataTrackWidget::mousePressEvent ( QMouseEvent *  me  )  [protected]

This method originates from QWidget and under most circumstances will only ever need to be called by the Qt library. However, it is likely that a user implemented class overrides this class. In this basic rendition, several functions are supports: selecting and moving Drawable objects (y-axis bar, file name , etc...), adding and removing highlights and generating the FeatureInfoEvents that provide meta-data description about records under the mouse press. Therefore, if reimplementing this class, it's a good idea to call this method directly as well, for instance, by adding a call to DataTrackWidget::mousePressEvent( me ) explicitly in the reimplemented version.

Parameters:
QMouseEvent* see Qt's QWidget documentation

Reimplemented in AnnotationTrackWidget, BarLineRelNotationTrackWidget, and ScoreTrackWidget.

void DataTrackWidget::mouseReleaseEvent ( QMouseEvent *  me  )  [protected]

This method comes from Qt's QWidget class and will usually only be called by Qt library code. If reimplementing this method in a new class, one might want to consider explicitly calling this method at the end of their new version (ex. "DataTrackWidget::mouseReleaseEvent( me )") in order to preserve functionality related to drawing and removing of highlights.

Parameters:
QMouseEvent* see Qt QWidget documentation
void DataTrackWidget::receive_key_event ( int  key,
bool  state 
) [slot]

This very well may be an unnecessary method... so consider other Qt based options before using this. It's purpose was to pass Qt QKeyEvent generating events to the tracks when that event is captured by a non-track object.

This method may(should) go away in the future. Or at least change for the better.

Parameters:
int the numeric value of the key according to Qt
bool whether the shift key was depressed
void DataTrackWidget::resizeEvent ( QResizeEvent *  re  )  [protected]

Note that this method sets a number of constants that are used frequently in drawing graphs, such as h3u and h3l, the upper and lower thirds of the graph. If a class overrides this method they should consider calling the parent's method somewhere in their implementation, eg. by calling DataTrackWidget::resizeEvent( re ) explicitly.

Normally this is called by Qt code.

Parameters:
QResizeEvent* see Qt's QWidget documentation

Reimplemented in BarLineRelNotationTrackWidget.

double DataTrackWidget::score_scale_max (  ) 

This method returns the max value used for the y-axis. This may be the max score value of the data, or some other value the user has set to compress/stretch the y-axis.

Returns:
the max score to be used for the y-axis
See also:
DataTrackWidget::set_score_scale_bounds( double low, double high )
double DataTrackWidget::score_scale_min (  ) 

This method returns the min value used for the y-axis. This may be the min score value of the data, or some other value the user has set to compress/stretch data on the y-axis.

Returns:
the min score to be used for the y-axis
See also:
DataTrackWidget::set_score_scale_bounds( double low, double high )
void DataTrackWidget::set_feature_highlights ( GVecGFF gv  ) 

A feature highlight is a region (start and stop) set by a right mouse click on an existing feature that may or may not be associated with the current graph, ie the feature highlight is intended to be drawn in a highlight color across all graph tracks. Highlights, which are similar to manually set annotations, are stored in a GVecGFF.

Parameters:
GVecGFF* gv the feature highlights
void DataTrackWidget::set_filter ( SearchFilterEvent sfe,
GVecGFF pass_regions_gff,
vector< size_t >  pass_indices 
)

Set a filter for this track. The filter will be considered when the DataTrackWidget::draw_data( QPainter* painter ) method is called.

Sometimes it's not enough to compare the records in a track against a filter in deciding whether to render them or not, for instance, when performing logical-and or logical-or the track with other tracks. In this circumstance the search filter is used with in an outside engine (like BasicDisplayWidgetFilterEngine) which determines the regions and record indices that pass the filter criteria. That information is passed here.

Parameters:
SearchFilterEvent* 
See also:
DataTrackWidget::set_filter( SearchFilterEvent* sfe, GVecGFF* pass_regions_gff, vector<size_t> pass_indices )
void DataTrackWidget::set_filter ( SearchFilterEvent sfe  ) 

Set a filter for this track. The filter will be considered when the DataTrackWidget::draw_data( QPainter* painter ) method is called.

Parameters:
SearchFilterEvent* 
See also:
DataTrackWidget::set_filter( SearchFilterEvent* sfe, GVecGFF* pass_regions_gff, vector<size_t> pass_indices )
void DataTrackWidget::set_manual_highlights ( GVecGFF gv  ) 

A manual highlight is a region (start and stop) set by a mouse drag that will be drawn in a highlight color across the graph. Highlights, which are similar to manually set annotations, are stored in a GVecGFF.

Parameters:
GVecGFF* gv the manual highlights
void DataTrackWidget::set_score_scale_bounds ( double  low,
double  high 
) [slot]

As a default, a track with score data will use the data's max/min value to determine the range of the y-axis. This method may be used to override those defaults and set a new y-axis range. This affects how the data is stretched/compressed, not the height of the graph. To change the height of the graph, use the appropriate QWidget methods.

Parameters:
double the lower limit of the y-axis
double the upper limit of the y-axis
void DataTrackWidget::set_selected ( bool  tf  ) 

The select state essentially allows a graph track to be flagged; usually this flag is accompanied by some sort of visual clue like a highlight box drawn around the track. The select state can be used to indicate that this track is to be considered a target, for instance, in search/filter actions or color and other graphic changes.

Parameters:
bool tf true to set the graph selected
See also:
DataTrackWidget::is_selected( )
size_t DataTrackWidget::starting_index (  )  [protected, virtual]

This method considers the base pair position of the right edge of the screen minus the length of the longest record and then returns the index of the first record in the GVec that needs to be drawn.

Returns:
lowest index of GVec* record that needs to be drawn
size_t DataTrackWidget::stopping_index (  )  [protected, virtual]

This method considers the base pair position of the left edge of and then returns the index of the last record in the GVec that needs to be drawn.

Returns:
size_t highest index of GVec* record that needs to be drawn
size_t DataTrackWidget::subsample_rate ( size_t  start,
size_t  stop 
) [protected, virtual]

If more data are available than pixel space in which to draw them, a subsampling of the data can speed rendering by avoiding drawing many data points on top of one another.

A class may override this method to set a subsample rate, ie. an integer indicating how to skip over the data such as 2 (every other datum) or 3 (every third datum). The default is the subsample_factor = (stop - start)/viewport_width where subsample is always an odd integer, ie. no subsampling until there are 3 times more data points than pixels.

Note that this approach doesn't consider where the data points might be concentrated in the viewport.

Parameters:
size_t start first index of data that will be drawn
size_t stop last index of data that will be drawn
Returns:
a subsample factor
void DataTrackWidget::type_specific_graphics_event ( GraphTypeSpecificGraphicsEvent  )  [protected, virtual]

Set graphics events generated via GraphControlsWidget objects.

See also:
DataTrackWidget::get_graph_controls_widget( )

Reimplemented in DataDensityTrackWidget, and SequenceTrackWidget.

void DataTrackWidget::update_graphics ( GraphicsEvent event  )  [slot]

Use this method to pass GraphicsEvent objects to the track. The method will determine what type of graphics event it has and approrriately set its attributes to match.

Despite its name, this method does not explicitly repaint the widget.

Parameters:
GraphicsEvent* 
void DataTrackWidget::visible ( QString  sequence,
bool  visible 
)

A track may be set visible or invisible. Since track is actually a stack of graphs, one per sequence name (ex. chromosome 2L, 2R, 3L, etc...) and visibility is set per sequence to allow maintenance of visibility state if toggling between sequences, querying or setting visibility state requires naming the target sequence.

The setting operation only succeeds if the sequence is found.

Parameters:
QString sequence target for the visibility setting operation
bool visible the state to which to set the visibility
bool DataTrackWidget::visible ( QString  sequence  ) 

Indicates whether the track is visible for the given sequence.

Parameters:
QString sequence for which visibility inquire is being made
Returns:
is the track visible for this sequence?
See also:
DataTrackWidget::visible( QString sequence, bool visible )

The documentation for this class was generated from the following files:
 All Classes Functions

Generated on Thu Sep 17 15:19:42 2009 for BQGB by  doxygen 1.6.1