BLTInterface

BLT Plot Commands

BLT Plot Commands - commands used to control the BLT plot windows

Synopsis

BLT Plot Commands

CreateGraphWindow

Create a new plotting surface and return the file handle. The file handle is required as a parameter to the other BLT window commands.

CreateLine

Add a new line to an existing plot.

CreateSingleLine

Add a new single data set to an existing plot.

ClearGraph

Clear a graph window of all data, and reset the window.

AddtoLine

Add one or more data points to an existing line in the plot window.

CreateBound

Add an outline to the graph. This can be then filled in with color in the plot window. Normal lines are not completed, and do not have fill properties.

FlipY

This command allows the Y axis orientation to be changed.

Description

The BLT window offers more control than the xgraph window. This option is tightly integrated into the command language. The following commands are implemented as scripts, and use the tcl based pipes for passing information. [../Post.html#TCLReturn TCL return] commands can be used to extract data which can be added to a plot surface. Multiple BLT windows can be opened at any one time.

All of these commands are tcl scripts, and operate by writing tcl/tk commands through a pipe to the receving end. Therefore, they all have similar structure. Each command uses the "puts" command to write into the pipe. Various strings are passed to control the behavior of the plot window.

CreateGraphWindow

This command creates a new plot surface. It takes no arguments, and returns the file handle of the window. The file handle is a required parameter for the remainder of the BLT plot commands. This is implemented as a tcl script, and the script is:

proc CreateGraphWindow {} {
    global GraphWindow flxs_library
    #create the graph window and initialize it
    set foo [open "| $GraphWindow" w]
    puts $foo "set flxs_library $flxs_library"
    puts $foo "set flxs_library $flxs_library/Plot"
    puts $foo "source ${flxs_library}/Plot/Plot.tk"
    flush $foo
    #create the global array information for the window
    set arr ${foo}Arr
    global $arr
    array set $arr "bound 0"
    array set $arr "colIndex 0"
    array set $arr "PenNames {}"
    return $foo
}

GraphWindow is a global tcl variable set at initialization that contains the path of the bltwish program. Please see the [../Install.html installation notes] for advice on configuring this parameter. The bltwish program is exec'd through a pipe and configured. The puts commands configure the window. The bltwish program is then passed three configuration commands. This first two are setting the location of the flooxs library of tcl/tk commands along with the Plot procedure subdirectory. This flxs_library variable is set at program startup and is controlled with the FLXSHOME environment variable - see at [../Install.html installation]. The third command configures bltwish to become the plotting surface. The remaining commands set up global variable for handling the automatic pen stepping and configuration as material is added to the window. You should this:

CreateLine

This command allows a named list of lists of coordinates to be added to a specified plot surface. It takes three parameters. The first is the name of the window to add the line. The second is the name of the data set to be used in Legends and identification. The final is the data for the line. Each set of data is a list. Each element of the list is a list of coordinates. Each sublist is drawn as a single line segment, and is unconnected to other lists. This is implemented as a tcl script, and the script is:

proc CreateLine {Win Name Data} {
    global ColorList 
    set Name [CreatePen $Win $Name] 
    #puts $Win ".graph pen create $Name"
    #puts $Win ".graph pen configure $Name -symbol none"
    #puts $Win ".graph pen configure $Name -linewidth 2"
    set arr ${Win}Arr
    global $arr
    set ci [lindex [array get $arr colIndex] 1]
    puts $Win ".graph pen configure $Name -color [lindex $ColorList $ci]"
    set ci [expr ($ci + 1) % [llength $ColorList]]
    array set $arr "colIndex $ci"
    puts $Win ".graph element create $Name -data [list [lindex $Data 0]]"
    puts $Win ".graph element configure $Name -pen $Name"
    flush $Win
    for {set i 1} {$i < [llength $Data]} {incr i} {
		puts $Win ".graph element create ${Name}.$i"
		set foo ".graph element configure ${Name}.$i"
		puts $Win "$foo -data [list [lindex $Data $i]]"
		puts $Win "$foo -pen $Name"
		puts $Win "$foo -label {}"
		flush $Win
    }
}

This script creates a pen with the passed name in the plot window. Pens define the style of line - color, width and marker. Other line segments are given the same properties, but are kept off the legend. Only one entry in the legend occurs for each create line.

CreateSingleLine

This command allows a named list of coordinates to be added to a specified plot surface. It differs from CreateLine only in that it doesn't take a list of lists. It takes three parameters. The first is the name of the window to add the line. The second is the name of the data set to be used in Legends and identification. The final is the data for the line. The list is drawn as a single line segment, and is unconnected to other lists. This is implemented as a tcl script, and the script is:

proc CreateSingleLine {Win Name Data} {
    global ColorList
    set Name [CreatePen $Win $Name]
    set arr ${Win}Arr
    global $arr
    set ci [lindex [array get $arr colIndex] 1]
    puts $Win ".graph pen configure $Name -color [lindex $ColorList $ci]"
    set ci [expr ($ci + 1) % [llength $ColorList]]
    array set $arr "colIndex $ci"
    puts $Win ".graph element create $Name -data [list $Data]"
    puts $Win ".graph element configure $Name -pen $Name"
    flush $Win
}

This script create a data element with the passed name in the plot window. Other line segments are given the same properties, but are kept off the legend. Only one entry in the legend occurs for each create line.

ClearGraph

This command empties all elements that have been added to plot window. It takes one argument - the name of the window that is to be cleared. This is implemented as a tcl script.

proc ClearGraph {Win} {
    puts $Win {foreach line [.graph element name] {.graph element delete $line}}
    puts $Win {foreach line [.graph marker names] {.graph marker delete $line}}
    puts $Win {foreach line [.graph pen names] {
		if {! [string match "active*" $line] } {.graph pen delete $line}}
	}
    puts $Win ".graph axis configure x -min {}"
    puts $Win ".graph axis configure x -max {}"
    puts $Win ".graph axis configure y -min {}"
    puts $Win ".graph axis configure y -max {}"
    flush $Win
    set arr ${Win}Arr
    global $arr
    array set $arr "bound 0"
    array set $arr "colIndex 0"
    array set $arr "PenNames {}"
}

This script passes commands to loop over all graph elements, markers and pens and deletes them. The axis are set back to autoscale and the variables controlling line incrementing of styles are rest.

AddtoLine

This command allows a new data point to be added to an existing line. The command takes four arguments. The first two are the name of the plot window and the name of the line. The last two are the x and y coordinates to be added to the line. The x and y are added to the line in a connected fashion. This is implemented as a tcl script, and the script is:

proc AddtoLine {Win Name X Y} {
    #check and see if the line exists currently
    set arr ${Win}Arr 
    global $arr
    set Hold [array get $arr PenNames]
    #returns true if name exists...
    if { [lsearch -exact [lindex $Hold 1] $Name] == -1 } {
		CreateSingleLine $Win $Name [list $X $Y]
    } else {
		set str [format {set xl [.graph element cget %s -xdata]} $Name]
		puts $Win $str
		puts $Win "lappend xl $X"
		set str [format {set yl [.graph element cget %s -ydata]} $Name]
		puts $Win $str
		puts $Win "lappend yl $Y"
		set str [format ".graph element configure %s -xdata $%s" $Name xl]
		puts $Win $str
		set str [format ".graph element configure %s -ydata $%s" $Name yl]
		puts $Win $str
    }
    flush $Win
}

The script retrieves the current list of data for both the x and y coordinates, and then adds the new points to the end of the list. The graph is then reset to use the new data lists. If the named line does not exist, it is created.

CreateBound

This command is very similar to CreateLine. The major difference is that this command assumes that the data passed it is a connected circle. This allows fill patterns and colors to be selected. It takes three parameters. The first is the name of the window to add the line. The second is the name of the data set to be used in Legends and identification. The final is the data for the line. Each set of data is a list. Each element of the list is a list of coordinates. Each sublist is drawn a single line segment, and is unconnected to other lists. This is implemented as a tcl script, and the script is: Because BLT does use markers to autoscale the plot, a bounding box is created and added to the plot using the maximum positions of the various marker elements.

FlipY

This command changes the orientation of the y axis. It takes two arguments. The first is the name of the window to operate in. The second is a boolean for the direction of the y axis. True will result in a window with the positive y direction down. This is implemented as a tcl script.

proc FlipY {Win Dir} {
    puts $Win ".graph axis configure y -descending $Dir"
    flush $Win
}

SetLimits

This command changes the minimum and maximum limits of a particular axis. It takes four arguments, the window name, the axis (x or y), and the minimum and maximum value on the axis.

proc SetLimits {Win Axis Min Max} {
    puts $Win ".graph axis configure $Axis -min $Min"
    puts $Win ".graph axis configure $Axis -max $Max"
    flush $Win
}

SetAxisType

This command changes the whether an axis is log or linear. It takes three arguments - the window name, the axis (x or y) and either log or linear.

proc SetAxisType {Win Axis log} {
    if {[string compare $log log]==0} {
		puts $Win ".graph axis configure $Axis -log 1"
    } else {
		puts $Win ".graph axis configure $Axis -log 0"
    }
    flush $Win
}

Examples

These are some simple examples. More complex examples are also available.

set plot [CreateGraphWindow]

Create a plot window and assign the identifier to the tcl variable "plot".

CreateLine $plot Junction [[slice.html slice] silicon val=0.0]

Add a line to the plot corresponding to a zero crossing of the [select.html selected] variable. The line will be added to the plot $plot and named "Junction".

CreateBound $plot Silicon [[bound.html bound] silicon]

Add a the silicon material boundary to the plot. The boundary will be added to the plot $plot and named "Silicon".

ClearGraph $plot

Clear all lines and markers from plot window $plot.

You can save an image of your plot from the plot window clicking the options under the <file> tab. If you want to automate the image save, here is a short procedure that saves the current plot window as a gif with the name passed ($file).

proc SaveImage { file } {

   global Win;
   puts $Win ".graph snap .image"
   puts $Win ".image write $file -format gif"
   flush $Win

}

Bugs and Missing Features

There needs to be additional work on the [BLTWindow.html plot surface control].

See Also

BLT Window Operations