Provided by: gbrowse_2.56+dfsg-8_all 
NAME
Legacy::Graphics::Browser-- Old version, deprecated
METHODS
The remainder of this document describes the methods available to the programmer.
new()
my $browser = Legacy::Graphics::Browser->new();
Create a new Legacy::Graphics::Browser object. The object is initially empty. This is
done automatically by gbrowse.
url_label()
my $url_label = $browser->url_label($yucky_url);
Creates a label.alias for URL strings starting with 'http' or 'ftp'. The last word
(following a '/') in the url is used for the label. Returns a string "url:label".
read_configuration()
my $success = $browser->read_configuration('/path/to/gbrowse.conf');
Parse the files in the gbrowse.conf configuration directory. This is done automatically
by gbrowse. Returns a true status code if successful.
$conf_dir = dir()
Returns the directory path that this config is attached to.
sources()
@sources = $browser->sources;
Returns the list of symbolic names for sources. The symbolic names are derived from the
configuration file name by:
1) stripping off the .conf extension.
2) removing the pattern "^\d+\."
This means that the configuration file "03.fly.conf" will have the symbolic name "fly".
source()
$source = $browser->source;
$source = $browser->source($new_source);
Sets or gets the current source. The default source will the first one found in the
gbrowse.conf directory when sorted alphabetically.
If you attempt to set an invalid source, the module will issue a warning and will return
undef.
setting()
$value = $browser->setting(general => 'stylesheet');
$value = $browser->setting(gene => 'fgcolor');
$value = $browser->setting('stylesheet');
The setting() method returns the value of one of the current source configuration
settings. setting() takes two arguments. The first argument is the name of the stanza in
which the configuration option is located. The second argument is the name of the
setting. Stanza and option names are case sensitive, with the exception of the "general"
section, which is automatically folded to lowercase.
If only one argument is provided, then the "general" stanza is assumed.
Option values are folded in such a way that newlines and tabs become single spaces. For
example, if the "default features" option is defined like this:
default features = Transcripts
Genes
Scaffolds
Then the value retrieved by
$browser->setting('general'=>'default features');
will be the string "Transcripts Genes Scaffolds". Note that it is your responsibility to
split this into a list. I suggest that you use Text::Shellwords to split the list in such
a way that quotes and escapes are preserved.
Because of the default, you could also fetch this information without explicitly
specifying the stanza. Combined with shellwords gives the idiom:
@defaults = shellwords($browser->setting('default features'));
fallback_setting()
$value = $browser->setting(gene => 'fgcolor');
Tries to find the setting for designated label (e.g. "gene") first. If this fails, looks
in [TRACK DEFAULTS]. If this fails, looks in [GENERAL].
plugin_setting()
$value = = $browser->plugin_setting("option_name");
When called in the context of a plugin, returns the setting for the requested option. The
option must be placed in a [PluginName:plugin] configuration file section:
[MyPlugin:plugin]
foo = bar
Now within the MyPlugin.pm plugin, you may call $browser->plugin_setting('foo') to return
value "bar".
db_settings()
@args = $browser->db_settings;
Returns the appropriate arguments for connecting to Bio::DB::GFF. It can be used this
way:
$db = Bio::DB::GFF->new($browser->dbgff_settings);
gbrowse_root()
$root = $browser->gbrowse_root()
Return the setting of "gbrowse root"
relative_path()
$relative_path = $browser->relative_path('gbrowse.css');
Add the setting of "gbrowse root" to the indicated path, if relative. Otherwise pass
through unchanged.
relative_path_setting()
$relative_path = $browser->relative_path_setting('stylesheet');
Like relative_path(), but works on a named setting rather than an actual path or
directory.
version()
$version = $browser->version
This is a shortcut method that returns the value of the "version" option in the general
section. The value returned is the version of the data source.
description()
$description = $browser->description
This is a shortcut method that returns the value of the "description" option in the
general section. The value returned is a human-readable description of the data source.
$time = $browser->remember_settings_time
Return the relative time (in CGI "expires" format) to maintain information about the
current page settings, including plugin configuration.
$time = $browser->remember_source_time
Return the relative time (in CGI "expires" format) to maintain information on which source
the user is viewing.
$language = $browser->language([$new_language])
Get/set an associated Legacy::Graphics::Browser::I18n language translation object.
$french = $browser->tr($english)
Translate message into currently-set language, with fallback to POSIX, via associated
Legacy::Graphics::Browser::I18n language translation object.
$section_setting = $browser->section_setting($section_name)
Returns "open" "closed" or "off" for the named section. Named sections are:
instructions
search
overview
details
tracks
display
add tracks
labels()
@track_labels = $browser->labels
This method returns the names of each of the track stanzas, hereinafter called "track
labels" or simply "labels". These labels can be used in subsequent calls as the first
argument to setting() in order to retrieve track-specific options.
default_labels()
@default_labels = $browser->default_labels
This method returns the labels for each track that is turned on by default.
label2type()
@feature_types = $browser->label2type($label,$lowres);
Given a track label, this method returns a list of the corresponding sequence feature
types in a form that can be passed to Bio::DB::GFF. The optional $lowres flag can be used
to tell label2type() to select a set of features that are suitable when viewing large
sections of the sequence (it is up to the person who writes the configuration file to
specify this).
type2label()
$label = $browser->type2label($type);
Given a feature type, this method translates it into a track label.
feature2label()
$label = $browser->feature2label($feature [,$length]);
Given a Bio::DB::GFF::Feature (or anything that implements a type() method), this method
returns the corresponding label. If an optional length is provided, the method takes
semantic zooming into account.
citation()
$citation = $browser->citation($label)
This is a shortcut method that returns the citation for a given track label. It simply
calls $browser->setting($label=>'citation');
width()
$width = $browser->width
This is a shortcut method that returns the width of the display in pixels.
header()
$header = $browser->header;
This is a shortcut method that returns the header HTML for the gbrowse page.
footer()
$footer = $browser->footer;
This is a shortcut method that returns the footer HTML for the gbrowse page.
config()
$config = $browser->config;
This method returns a Bio::Graphics::FeatureFile object corresponding to the current
source.
mtime()
$time = $browser->mtime()
This method returns the modification time of the config file for the current source.
path()
$path = $browser->path()
This method returns the file path of the config file for the current source.
make_link()
$url = $browser->make_link($feature,$panel,$label)
Given a Legacy::SeqFeatureI object, turn it into a URL suitable for use in a hypertext
link. For convenience, the Legacy::Graphics panel is also provided. If $label is
provided, then its link overrides the type of the feature.
render_panels()
$panels = $browser->render_panels(%args);
Render an image and an image map according to the options in %args. In a Returns a two-
element list. The first element is a URL that refers to the image which can be used as
the SRC for an <IMG> tag. The second is a complete image map, including the <MAP> and
</MAP> sections.
The arguments are a series of tag=>value pairs, where tags are:
Argument Value
segment A Bio::DB::GFF::Segment or
Legacy::Das::SegmentI object (required).
tracks An arrayref containing a series of track
labels to render (required). The order of the labels
determines the order of the tracks.
options A hashref containing options to apply to
each track (optional). Keys are the track labels
and the values are 0=auto, 1=force no bump,
2=force bump, 3=force label, 4=expanded bump.
feature_files A hashref containing a series of
Bio::Graphics::FeatureFile objects to be
rendered onto the display (optional). The keys
are labels assigned to the 3d party
features. These labels must appear in the
tracks arrayref in order for render_panels() to
determine the order in which to render them.
do_map This argument is a flag that controls whether or not
to generate the image map. It defaults to false.
do_centering_map This argument is a flag that controls whether or not
to add elements to the image map so that the user can
center the image by clicking on the scale. It defaults
to false, and has no effect unless do_map is also true.
title Add specified title to the top of the image.
noscale Suppress the scale
flip Flip coordinates left to right
hilite_callback Callback for performing hilighting
image_and_map This argument will cause render_panels to emulate
the legacy method image_and_map() and return a
GD::Image object and a 'boxes' array reference rather
than rendered html. This argument applies only to composite
(non-draggable) panel images.
Any arguments names that begin with an initial - (hyphen) are passed through to
Bio::Graphics::Panel->new() directly
Any arguments names that begin with an initial - (hyphen) are passed through to
Bio::Graphics::Panel->new() directly
drag_and_drop()
Return true if drag_and_drop tracks should be enabled on this datasource. Looks at the
"drag and drop" option and also consults a series of user agents known to support
drag_and_drop.
generate_panels()
Generate the GD object and the imagemap and returns a hashref in the format
$results->{track_label} = {image=>$uri, map=>$map_data, width=>$w, height=>$h, file=>$img_path)
If the "drag_n_drop" argument is false, then returns a single track named "__all__".
Arguments: a key=>value list
'section' Section type to draw; one of "overview", "region" or "detail"
'segment' A feature iterator that responds to next_seq() methods
'feature_files' A hash of Bio::Graphics::FeatureFile objects containing 3d party
features
'options' An hashref of options, where 0=auto, 1=force no bump, 2=force bump,
3=force label
4=force fast bump, 5=force fast bump and label
'drag_n_drop' Force drag-and-drop behavior on or off
'limit' Place a limit on the number of features of each type to show.
'labels' List of named tracks, in the order in which they are to be shown
'tracks' List of named tracks, in the order in which they are to be shown
(deprecated)
'label_scale' If true, prints chromosome name next to scale
'title' A title for the image
'noscale' Suppress scale entirely
'image_class' Optional image class for generating SVG output (by passing GD::SVG)
'cache_extra' Extra cache args needed to make this image unique
'scale_map_type' If equal to "centering_map" adds an imagemap to the ruler that
recenters.
If equal to "interval_map" creates an imagemap that jumps to a small
interval in map
'featurefile_select' callback for selecting features to be rendered from a featurefile
onto a panel any arguments that begin with an initial - (hyphen) are passed through to
Panel->new directly
add_feature_file
Internal use: render a feature file into a panel
generate_image
($url,$path) = $browser->generate_image($gd)
Given a GD::Image object, this method calls its png() or gif() methods (depending on GD
version), stores the output into the temporary directory given by the "tmpimages" option
in the configuration file, and returns a two element list consisting of the URL to the
image and the physical path of the image.
new_hits_on_overview()
$hashref = $browser->hits_on_overview($db,$hits,$options,$keyname);
This method is used to render a series of genomic positions ("hits") into a graphical
summary of where they hit on the genome in a segment-by-segment (e.g. chromosome) manner.
The first argument is a Bio::DB::GFF (or Bio::DasI) database.
The second argument is an array ref containing one of:
1) a set of array refs in the form [ref,start,stop,name], where
name is optional.
2) a Bio::DB::GFF::Feature object
3) a Legacy::SeqFeatureI object.
The third argument is the page settings hash from gbrowse.
The fourth option is the key to use for the "hits" track.
The returned HTML is stored in a hashref, where the keys are the reference sequence names
and the values are HTML to be emitted.
error()
my $error = $browser->error(['new error']);
Retrieve or store an error message. Currently used to pass run-time errors involving
uploaded/remote annotation files.
create_panel_args()
@args = $self->create_panel_args($section,$args);
Return arguments need to create a Bio::Graphics::Panel. $section is one of
'detail','overview', or 'region' $args is a hashref that contains the keys:
keystyle
title
image_class
postgrid
background
create_track_args()
@args = $self->create_track_args($label,$args);
Return arguments need to create a Legacy::Graphics::Track. $label is a config file stanza
label for the track.
segment_coordinates()
($start,$stop,$flip) = $self->segment_coordinates($segment,$flip)
Method to correct for rare case in which start and stop are flipped.
create_cache_key()
$cache_key = $self->create_cache_key(@args)
Create a unique cache key for the given args.
get_cached_panel()
($image_uri,$map,$width,$height) = $self->get_cached_panel($cache_key)
Return cached image url, imagemap data, width and height of image.
($region_sizes,$region_labels,$region_default) = $config->region_sizes()
Return information about the region panel:
1. list of valid region sizes (@$region_sizes)
2. mapping of size to label (%$region_labels)
3. default size ($region_default)
SEE ALSO
Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::Graphics::Feature,
Bio::Graphics::FeatureFile
AUTHOR
Lincoln Stein <lstein@cshl.org>.
Copyright (c) 2001 Cold Spring Harbor Laboratory
This package and its accompanying libraries is free software; you can redistribute it
and/or modify it under the terms of the GPL (either version 1, or at your option, any
later version) or the Artistic License 2.0. Refer to LICENSE for the full license text.
In addition, please see DISCLAIMER.txt for disclaimers of warranty.