gnuplot.tcl

multiplot::constructor

multiplot::constructor

SYNOPSIS

    constructor {args} {

PURPOSE

Create a new Gnuplot multi-plot object.

HOW TO USE

Either:

    set obj [::pwtk::gp::multiplot new ?OPTIONS? auto NPLOTS ?NPMAX? ?NX?  ?HEAD.TERM?]

or:

    set obj [::pwtk::gp::multiplot new ?OPTIONS? manual PP NX NY  ?HEAD.TERM?]

where OPTIONS are:

    -o  ORIENT
    -s  SX,SY 
    -fs FONTSIZE
    -t  TITLE    
    -spin       
    -pause PAUSE

ARGUMENTS

OPTIONS --- see OPTIONS below
auto | manual --- automatic or manual mode (see below)
NPLOTS, NPMAX, NX, PP, NY --- see below
HEAD.TERM --- "HEAD" is the rootname of Gnuplot script; "TERM" is the type of terminal (PWTK's terminal name) and the file's extension if plot is printed to a file; possible values are those returned by ::pwtk::gp::pwtk_terminals

OPTIONS

-o ORIENT --- page orientation (portrait or landscape); used explicitly only for EPS, while for other terminals, it's a hint for the multiplot layout
-s SX,SY --- terminal size (i.e. window or picture size)
-fs FONTSIZE --- font size
-t TITLE --- the window title (for window-type terminals only)
-spin --- spin-PDOS-like plots with positive & negative Y-values, f(x) & -f(x)
-pause PAUSE --- value for the Gnuplot's pause command (useful for window terminals)

DESCRIPTION

Two modes of multiplot Gnuplot objects are possible:

auto
manual

The auto mode: PWTK determines how to arrange plots on the page, i.e., number of plots in X- and Y-directions (columns and rows). The nplots, npmax, and nx are:

NPLOTS --- hint for the number of pages (one or more)
NPMAX --- (optional) maximum number of plots per page
NX --- (optional) number of plots in X-direction

The manual mode: User manually specifies the layout by specifying pp, nx, ny, where:

PP --- hint for the number of pages (one or more)
NX --- number of plots in X-direction (i.e. columns)
NY --- number of plots in Y-direction (i.e. rows)

SOURCE

        set options_initiated 0
        array set my_options [array get ::pwtk::gp::options]
        
        set page 0
        set plot 0
                
        # command-line arguments usage:
        #      ?OPTIONS? auto   NPLOTS ?NPMAX? ?NX?  ?HEAD.TERM?
        #      ?OPTIONS? manual PP NX NY  ?HEAD.TERM?

        set nargmin 2
        set nargmax 5
        set usage "new ?-o ORIENT?  ?-s SIZE?  ?-fs FONTSIZE?  ?-t TITLE?  ?-spin?  {auto NPLOTS ?NPMAX? ?NX? | manual PP NX NY}  ?HEAD.TERM?"
        ::pwtk::gp::parseOpt_term_

        set mode [lindex $args 0]
        
        switch -- $mode {
            auto {
                # args == auto NPLOTS ?NPMAX? ?NX? ?HEAD.TERM?
                #
                # where: NPMAX = (optional) max # plots per page, overwrites default
                #        NX    = (optional) max # of plots in X-dir, overwrites default

                set nplot   [lindex $args 1]
                set lastarg [lindex $args end]
                
                if { ! [string is integer -strict $lastarg] } {
                    set head_dot_term $lastarg
                    set args [lrange $args 0 end-1]
                } else {
                    set id [incr ::pwtk::gp::multiplot_id]
                    set head_dot_term multiplot-$id.win
                }
                set orient [::pwtk::gp::orient [::pwtk::gp::term_ $head_dot_term] $opt(s) $opt(t)]

                set len   [llength $args]
                set npmax [expr { $len >= 3 ? [lindex $args 2] : -1 }]
                set nx    [expr { $len == 4 ? [lindex $args 3] : -1 }]

                if { ! [::pwtk::type::number posint -strict $nplot] } {
                    ::pwtk::error "NPLOT must be positive integer, but got $nplot" 1
                }
                if { ! [string is integer -strict $npmax] || ! [string is integer -strict $nx] } {
                    ::pwtk::error "NPMAX and NX must be integers, but got $npmax and $nx" 1
                }
                array set mp [::pwtk::gp::multiplot_array $nplot $npmax $nx $orient $opt(spin)]
            }
            
            manual {                
                # args == manual PP NX NY  ?HEAD.TERM?
                
                set pp [lindex $args 1]
                set nx [lindex $args 2]
                set ny [lindex $args 3]
                set lastarg [lindex $args 4]
                
                if { $lastarg ne {} } {
                    set head_dot_term $lastarg
                    set args [lrange $args 0 end-1]
                } else {
                    set id [incr ::pwtk::gp::multiplot_id]
                    set head_dot_term multiplot-$id.win
                }

                if { ! [::pwtk::type::number posint -strict $pp] \
                         || ! [::pwtk::type::number posint -strict $nx] \
                         || ! [::pwtk::type::number posint -strict $ny] } {
                    ::pwtk::error "PP, NX, NY must be positive integers, but got: \"$args\"" 1
                }
                array set mp [subst {
                    pp $pp
                    np [expr $nx*$ny]
                    nx $nx
                    ny $ny}]
                set mp(fsize) $opt(fs)
            }
            
            default {
                ::pwtk::error "unkown mode \"$mode\", must be either auto or manual" 1
            }
        }

        set head [::pwtk::gp::head_ $head_dot_term]
        set term [::pwtk::gp::term_ $head_dot_term]
        
        # -s
        
        if { $opt(s) == {} } {
            switch -- [::pwtk::gp::gp2pwtk $term] {
                eps { set size $::pwtk::gp::gp(eps.multisize) }
                pdf { set size $::pwtk::gp::gp(pdf.multisize) }
                default { set size $::pwtk::gp::gp(multisize) }
            }
        } else {
            set size $opt(s)
        }

        # -fs
        
        if { $opt(fs) == {} } {
            set fsize $mp(fsize)
        } else {
            set fsize $opt(fs)
        }

        # -spin & -p

        set opts {}
        if { $mp(pp) > 1 } {
            append opts "-p "
        }
        if { $opt(spin) } {
            append opts "-spin "
        }

        # -pause
        
        my pause_ mouse $opt(pause)

        # -t
        
        if { $opt(t) == {} } {
            if { $term in $::pwtk::gp::gp(win.terminals) } {
                if { $mp(pp) == 1 } {
                    set next "($pauseText to Exit)"
                } else {
                    set next "($pauseText to continue to next page)"
                }        
                set title "Page 1/$mp(pp)  $next"
            } else {
                set title {}
            }        
        } else {
            set title "title '[string trim $opt(t) ']'"
        }

        set prolog [::pwtk::gp::get_term {*}$opts -o $opt(o) -s $size -fs $fsize -t $title $head_dot_term]\n
    }

TABLE OF CONTENTS

multiplot::constructor