Provided by: gbrowse_2.56+dfsg-12build3_all bug

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.