Tcl Commands¶

Besides being able to access the menu options (e.g., gtkwave::/File/Quit), within Tcl scripts there are more commands available for manipulating the viewer.

addCommentTracesFromList: adds comment traces to the viewer

Syntax: set num_found [ gtkwave::addCommentTracesFromList list ]

Example¶

set clk48 [list]
lappend clk48 "$facname1"
lappend clk48 "$facname2"
...
set num_added [ gtkwave::addCommentTracesFromList $clk48 ]

addSignalsFromList: adds signals to the viewer

Syntax: set num_found [ gtkwave::addSignalsFromList list ]

Example¶

set clk48 [list]
lappend clk48 "$facname1"
lappend clk48 "$facname2"
...
set num_added [ gtkwave::addSignalsFromList $clk48 ]

deleteSignalsFromList: deletes signals from the viewer.

This deletes only the first instance found unless the signal is specified multiple times in the list.

Syntax: set num_deleted [ gtkwave::deleteSignalsFromList list ]

Example¶

set clk48 [list]
lappend clk48 "$facname1"
lappend clk48 "$facname2"
...
set num_deleted [ gtkwave::deleteSignalsFromList $clk48 ]

deleteSignalsFromListIncludingDuplicates: deletes signals from the viewer.

This deletes all the instances found so there is no need to specify the same signal multiple times in the list.

Syntax: set num_deleted [ gtkwave::deleteSignalsFromListIncludingDuplicates list ]

Example¶

set clk48 [list]
lappend clk48 "$facname1"
lappend clk48 "$facname2"
...
set num_deleted [ gtkwave::deleteSignalsFromListIncludingDuplicates $clk48 ]

findNextEdge: advances the marker to the next edge for highlighted signals

Syntax: set marker_time [ gtkwave::findNextEdge ]

Example¶

gtkwave::highlightSignalsFromList "top.clk"
set time_value [ gtkwave::findNextEdge ]
puts "time_value: $time_value"

findPrevEdge: moves the marker to the previous edge for highlighted signals

Syntax: set marker_time [ gtkwave::findPrevEdge ]

Example¶

gtkwave::highlightSignalsFromList "top.clk"
set time_value [ gtkwave::findPrevEdge ]
puts "time_value: $time_value"

forceOpenTreeNode: forces open one tree node in the Signal Search Tree and closes the rest.

If upper levels are not open, the tree will remain closed however once the upper levels are opened, the hierarchy specified will become open. If path is missing or is an empty string, the function returns the current hierarchy path selected by the SST or -1 in case of error.

Syntax: gtkwave::forceOpenTreeNode hierarchy_path

Returned value: 0 - success 1 - path not found in the tree -1 - SST tree does not exist

Example¶

set path tb.HDT.cpu
switch -- [ gtkwavetcl::forceOpenTreeNode $path ] {
    -1 {puts "Error: SST is not supported here"}
    1 {puts "Error: '$path' was not recorder to dump file"}
    0 {}
}

getArgv: returns a list of arguments which were used to start gtkwave from the command line

Syntax: set argvlist [ gtkwave::getArgv ]

Example¶

set argvs [ gtkwave::getArgv ]
puts "$argvs"

getBaselineMarker: returns the numeric value of the baseline marker time

Syntax: set baseline_time [ gtkwave::getBaselineMarker ]

Example¶

set baseline [ gtkwave::getBaselineMarker ]
puts "$baseline"

getDisplayedSignals: returns a list of all signals currently on display

Syntax: set display_list [ gtkwave::getDisplayedSignals ]

Example¶

set display_list [ gtkwave::getDisplayedSignals ]
puts "$display_list"

getDumpFileName: returns the filename for the loaded dumpfile

Syntax: set loaded_file_name [ gtkwave::getDumpFileName ]

Example¶

set nfacs [ gtkwave::getNumFacs ]
set dumpname [ gtkwave::getDumpFileName ]
set dmt [ gtkwave::getDumpType ]
puts "number of signals in dumpfile '$dumpname' of type $dmt: $nfacs"

getDumpType: returns the dump type as a string (VCD, PVCD, LXT, LXT2, GHW, VZT)

Syntax: set dump_type [ gtkwave::getDumpType ]

Example¶

set nfacs [ gtkwave::getNumFacs ]
set dumpname [ gtkwave::getDumpFileName ]
set dmt [ gtkwave::getDumpType ]
puts "number of signals in dumpfile '$dumpname' of type $dmt: $nfacs"

getFacName: returns a string for the facility name which corresponds to a given facility number

Syntax: set fac_name [ gtkwave::getFacName fac_number ]

Example¶

set nfacs [ gtkwave::getNumFacs ]
for {set i 0} {$i < $nfacs } {incr i} {
    set facname [ gtkwave::getFacName $i ]
    puts "$i: $facname"
}

getFacDir: returns a string for the direction which corresponds to a given facility number

Syntax: set fac_dir [ gtkwave::getFacDir fac_number ]

Example¶

set nfacs [ gtkwave::getNumFacs ]
for {set i 0} {$i < $nfacs } {incr i} {
    set facdir [ gtkwave::getFacDir $i ]
    puts "$i: $facdir"
}

getFacVtype: returns a string for the variable type which corresponds to a given facility number

Syntax: set fac_vtype [ gtkwave::getFacVtype fac_number ]

Example¶

set nfacs [ gtkwave::getNumFacs ]
for {set i 0} {$i < $nfacs } {incr i} {
    set facvtype [ gtkwave::getFacVtype $i ]
    puts "$i: $facvtype"
}

getFacDtype: returns a string for the data type which corresponds to a given facility number

Syntax: set fac_dtype [ gtkwave::getFacDtype fac_number ]

Example¶

set nfacs [ gtkwave::getNumFacs ]
for {set i 0} {$i < $nfacs } {incr i} {
    set facdtype [ gtkwave::getFacDtype $i ]
    puts "$i: $facdtype"
}

getFontHeight: returns the font height for signal names

Syntax: set font_height [ gtkwave::getFontHeight ]

Example¶

set font_height [ gtkwave::getFontHeight ]
puts "$font_height"

getFromEntry: returns the time value string in the “From:” box.

Syntax: set from_entry [ gtkwave::getFromEntry ]

Example¶

set from_entry [ gtkwave::getFromEntry ]
puts "$from_entry"

getHierMaxLevel: returns the max hier value which is set in the viewer

Syntax: set hier_max_level [ gtkwave::getHierMaxLevel ]

Example¶

set max_level [ gtkwave::getHierMaxLevel ]
puts "$max_level"

getLeftJustifySigs: returns 1 if signals are left justified, else 0

Syntax: set left_justify [ gtkwave::getLeftJustifySigs ]

Example¶

set justify [ gtkwave::getLeftJustifySigs ]
puts "$justify"

getLongestName: returns number of characters of the longest name in the dumpfile

Syntax: set longestname_len [ gtkwave::getLongestName ]

Example¶

set longest [ gtkwave::getLongestName ]
puts "$longest"

getMarker: returns the numeric value of the primary marker position

Syntax: set marker_time [ gtkwave::getMarker ]

Example¶

set marker_time [ gtkwave::getMarker ]
puts "$marker_time"

getMaxTime: returns the numeric value of the last time value in the dumpfile

Syntax: set max_time [ gtkwave::getMaxTime ]

Example¶

set max_time [ gtkwave::getMaxTime ]
puts "$max_time"

getMinTime: returns the numeric value of the first time value in the dumpfile

Syntax: set min_time [ gtkwave::getMinTime ]

Example¶

set min_time [ gtkwave::getMinTime ]
puts "$min_time"

getNamedMarker: returns the numeric value of the named marker position

Syntax: set time_value [ gtkwave::getNamedMarker which ] such that which = A-Z or a-z

Example¶

set marker_time [ gtkwave::getNamedMarker A ]
puts "$marker_time"

getNumFacs: returns the number of facilities encountered in the dumpfile

Syntax: set numfacs [ gtkwave::getNumFacs ]

Example¶

set nfacs [ gtkwave::getNumFacs ]
set dumpname [ gtkwave::getDumpFileName ]
set dmt [ gtkwave::getDumpType ]
puts "number of signals in dumpfile '$dumpname' of type $dmt: $nfacs"

getNumTabs: returns the number of tabs shown on the viewer

Syntax: set numtabs [ gtkwave::getNumTabs ]

Example¶

set ntabs [ gtkwave::getNumTabs ]
puts "number of tabs: $ntabs"

getPixelsUnitTime: returns the number of pixels per unit time

Syntax: set pxut [ gtkwave::getPixelsUnitTime ]

Example¶

set pxut [ gtkwave::getPixelsUnitTime ]
puts "$pxut"

getSaveFileName: returns the save filename

Syntax: set save_file_name [ gtkwave::getSaveFileName ]

Example¶

set savename [ gtkwave::getSaveFileName ]
puts "$savename"

getStemsFileName: returns the stems filename

Syntax: set stems_file_name [ gtkwave::getStemsFileName ]

Example¶

set stemsname [ gtkwave::getStemsFileName ]
puts "$stemsname"

getTimeDimension: returns the first character of the time units that the trace was saved in (e.g., “u” for us, “n” for “ns”, “s” for sec, etc.)

Syntax: set dimension_first_char [ gtkwave::getTimeDimension ]

Example¶

set dimch [ gtkwave::getTimeDimension ]
puts "$dimch"

getTimeZero: returns the numeric value for what represents the time #0 in the dumpfile. This is only of interest if the $timezero directive is encountered in the dumpfile.

Syntax: set zero_time [ gtkwave::getTimeZero ]

Example¶

set zero_time [ gtkwave::getTimeZero ]
puts "$zero_time"

getToEntry: returns the time value string in the “To:” box.

Syntax: set to_entry [ gtkwave::getToEntry ]

Example¶

set to_entry [ gtkwave::getFromEntry ]
puts "$to_entry"

getTotalNumTraces: returns the total number of traces that are being displayed currently

Syntax: set total_traces [ gtkwave::getTotalNumTraces ]

Example¶

set totnum [ gtkwave::getTotalNumTraces ]
puts "$totnum"

getTraceFlagsFromIndex: returns the decimal value of the sum of all flags for a given trace

Syntax: set flags [ gtkwave::getTraceFlagsFromIndex trace_number ]

Example¶

set tflags [ gtkwave::getTraceFlagsFromIndex 0 ]
puts "$tflags"

getTraceFlagsFromName: returns the decimal value of the sum of all flags for a given trace

Syntax: set flags [ gtkwave::getTraceFlagsFromName trace_name ]

Example¶

set tflags [ gtkwave::getTraceFlagsFromName {top.des.k1x[1:48]} ]
puts "$tflags"

getTraceNameFromIndex: returns the name of a trace when given the index value

Syntax: set trace_name [ gtkwave::getTraceNameFromIndex trace_number ]

Example¶

set tname [ gtkwave::getTraceNameFromIndex 1 ]
puts "$tname"

getTraceScrollbarRowValue: returns the scrollbar value (which corresponds to the trace index for the topmost trace on screen)

Syntax: set scroller_value [ gtkwave::getTraceScrollbarRowValue ]

Example¶

set scroller [ gtkwave::getTraceScrollbarRowValue ]
puts "$scroller"

getTraceValueAtMarkerFromIndex: returns the value under the marker for the trace numbered trace index

Syntax: set ascii_value [ gtkwave::getTraceValueAtMarkerFromIndex trace_number ]

Example¶

set tvi [ gtkwave::getTraceValueAtMarkerFromIndex 2 ]
puts "$tvi"

getTraceValueAtMarkerFromName: returns the value under the primary marker for the given trace name

Syntax: set ascii_value [ gtkwave::getTraceValueAtMarkerFromName fac_name ]

Example¶

set tvn [ gtkwave::getTraceValueAtMarkerFromName {top.des.k2x[1:48]} ]
puts "$tvn"

getTraceValueAtNamedMarkerFromName: returns the value under the named marker for the given trace name

Syntax: set ascii_value [ gtkwave::getTraceValueAtNamedMarkerFromName which fac_name ] such that which = A-Z or a-z

Example¶

set tvn [ gtkwave::getTraceValueAtNamedMarkerFromName A {top.des.k2x[1:48]} ]
puts "$tvn"

getUnitTimePixels: returns the number of time units per pixel

Syntax: set utpx [ gtkwave::getUnitTimePixels ]

Example¶

set utpx [ gtkwave::getUnitTimePixels ]
puts "$utpx"

getVisibleNumTraces: returns number of non-collapsed traces

Syntax: set num_visible_traces [ gtkwave::getVisibleNumTraces ]

Example¶

set nvt [ gtkwave::getVisibleNumTraces ]
puts "$nvt"

getWaveHeight: returns the height of the wave window in pixels

Syntax: set wave_height [ gtkwave::getWaveHeight ]

Example¶

set wht [ gtkwave::getWaveHeight ]
puts "$wht"

getWaveWidth: returns the width of the wave window in pixels

Syntax: set wave_width [ gtkwave::getWaveWidth ]

Example¶

set wwt [ gtkwave::getWaveWidth ]
puts "$wwt"

getWindowEndTime: returns the end time of the wave window

Syntax: set end_time_value [ gtkwave::getWindowEndTime ]

Example¶

set wet [ gtkwave::getWindowEndTime ]
puts "$wet"

getWindowStartTime: returns the start time of the wave window

Syntax: set start_time_value [ gtkwave::getWindowStartTime ]

Example¶

set wst [ gtkwave::getWindowStartTime ]
puts "$wst"

getZoomFactor: returns the zoom factor of the wave window

Syntax: set zoom_value [ gtkwave::getZoomFactor ]

Example¶

set zf [ gtkwave::getZoomFactor ]
puts "$zf"

highlightSignalsFromList: highlights the facilities contained in the list argument

Syntax: set num_highlighted [ gtkwave::highlightSignalsFromList list ]

Example¶

set clk48 [list]

lappend clk48 "$facname1"
lappend clk48 "$facname2"
...
set num_highlighted [ gtkwave::highlightSignalsFromList $clk48 ]

installFileFilter: installs file filter number which across all highlighted traces. Using zero for which removes the filter.

Syntax: set num_updated [ gtkwave::installFileFilter which ]

Example¶

set num_updated [ gtkwave::installFileFilter 0 ]
puts "$num_updated"

installProcFilter: installs process filter number which across all highlighted traces. Using zero for which removes the filter.

Syntax: set num_updated [ gtkwave::installProcFilter which ]

Example¶

set num_updated [ gtkwave::installProcFilter 0 ]
puts "$num_updated"

installTransFilter: installs transaction process filter number which across all highlighted traces. Using zero for which removes the filter.

Syntax: set num_updated [ gtkwave::installTransFilter which ]

Example¶

set num_updated [ gtkwave::installTransFilter 0 ]
puts "$num_updated"

loadFile: loads a new file

Syntax: gtkwave::loadFile filename

Example¶

gtkwave::loadFile "$filename"

nop: calls the GTK main loop in order to update the gtkwave GUI

Syntax: gtkwave::nop

Example¶

gtkwave::nop

presentWindow: raises the main window in the stacking order or deiconifies it

Syntax: gtkwave::presentWindow

Example¶

gtkwave::presentWindow

reLoadFile: reloads the current active file

Syntax: gtkwave::reLoadFile

Example¶

gtkwave::reLoadFile

setBaselineMarker: sets the time for the baseline marker (-1 removes it)

Syntax: gtkwave::setBaselineMarker time_value

Example¶

gtkwave::setBaselineMarker 128

setCurrentTranslateEnums: sets the enum list to function as the current translate file and returns the corresponding which value to be used with gtkwave::installFileFilter. As a real file is not used, the results of this are not recreated when a save file is loaded or if the waveform is reloaded.

Syntax: set which_f [ gtkwave::setCurrentTranslateEnums elist ]

Example¶

set enums [list]

lappend enums 0000000000000000 IDLE
lappend enums FFFFFFFFFFFFFFFF BUSY
lappend enums 3000000000000000 OTHER
lappend enums 0123456789ABCDEF HEXSTATE
lappend enums 1111111111111111 "All 1s"

set which_f [ gtkwave::setCurrentTranslateFile $enums ]

puts "$which_f"

setCurrentTranslateFile: sets the filename to the current translate file and returns the corresponding which value to be used with gtkwave::installFileFilter.

Syntax: set which_f [ gtkwave::setCurrentTranslateFile filename ]

Example¶

set which_f [ gtkwave::setCurrentTranslateFile ./zzz.txt ]
puts "$which_f"

setCurrentTranslateProc: sets the filename to the current translate process (executable) and returns the corresponding which value to be used with gtkwave::installProcFilter.

Syntax: set which_f [ gtkwave::setCurrentTranslateProc filename ]

Example¶

set which_f [ gtkwave::setCurrentTranslateProc ./zzz.exe ]
puts "$which_f"

setCurrentTranslateTransProc: sets the filename to the current transaction translate process (executable) and returns the corresponding which value to be used with gtkwave::installTransFilter.

Syntax: set which_f [ gtkwave::setCurrentTranslateTransProc filename ]

Example¶

set which_f [ gtkwave::setCurrentTranslateTransProc ./zzz.exe ]
puts "$which_f"

setFromEntry: sets the time in the “From:” box.

Syntax: gtkwave::setFromEntry time_value

Example¶

gtkwave::setFromEntry 100

setLeftJustifySigs: turns left justification for signal names on or off

Syntax: gtkwave::setLeftJustifySigs on_off_value

Example¶

gtkwave::setLeftJustifySigs on
gtkwave::setLeftJustifySigs off

setMarker: sets the time for the primary marker (-1 removes it)

Syntax: gtkwave::setMarker time_value

Example¶

gtkwave::setMarker 128

setNamedMarker: sets named marker A-Z (a-z) to a given time value and optionally renames the marker text to a string (-1 removes the marker)

Syntax: gtkwave::setNamedMarker which time_value [string]

Example¶

gtkwave::setNamedMarker A 400 "Example Named Marker"
gtkwave::setNamedMarker A 400

setTabActive: sets the active tab in the viewer (0..getNumTabs-1)

Syntax: gtkwave::setTabActive which

Example¶

gtkwave::setTabActive 0

setToEntry: sets the time in the “To:” box.

Syntax: gtkwave::setToEntry time_value

Example¶

gtkwave::setToEntry 600

setTraceHighlightFromIndex: highlights or unhighlights the specified trace

Syntax: gtkwave::setTraceHighlightFromIndex trace_index on_off

Example¶

gtkwave::setTraceHighlightFromIndex 2 on
gtkwave::setTraceHighlightFromIndex 2 off

setTraceHighlightFromNameMatch: highlights or unhighlights the specified trace

Syntax: gtkwave::setTraceHighlightFromNameMatch fac_name on_off

Example¶

gtkwave::setTraceHighlightFromNameMatch top.des.clk on
gtkwave::setTraceHighlightFromNameMatch top.clk off

setTraceScrollbarRowValue: sets the scrollbar for traces a number of traces down from the very top

Syntax: gtkwave::setTraceScrollbarRowValue scroller_value

Example¶

gtkwave::setTraceScrollbarRowValue 10

setWindowStartTime: scrolls the traces such that the start time is at the left margin (as long as the zoom level permits this)

Syntax: gtkwave::setWindowStartTime start_time

Example¶

gtkwave::setWindowStartTime 100

setZoomFactor: sets the zoom factor for the trace data (i.e., how compressed it is with respect to time)

Syntax: gtkwave::setZoomFactor zoom_value

Example¶

gtkwave::setZoomFactor -3

setZoomRangeTimes: sets the visible time range for the trace data

Syntax: gtkwave::setZoomRangeTimes time1 time2

Example¶

gtkwave::setZoomRangeTimes 100 217

showSignal: sets the scrollbar for traces a number of traces down from the very top (0), center (1), or bottom (2)

Syntax: gtkwave::setTraceScrollbarRowValue scroller_value position

Example¶

gtkwave::setTraceScrollbarRowValue 10 0

signalChangeList: returns time and value changes for the signals indicated by the argument names

Syntax: gtkwave::signalChangeList signal_name options

Where options is are one or more of the following:

-start_time start-time (default 0)
-end_time end-time (default last sample in dump file)
-max maximum-number-of-samples (default 0x7fffffff)
-dir forward|backward (default forward)

The function returns a Tcl list of value changes for the signal-name starting at start-time and ending at end-time or an empty list in any other case.

Even members of the list hold the time of change and odd members hold the value that is associated with the time the precedes it. Values are given as strings in the base of the signal.

If signal-name is not present then the first highlighted signal is taken.

Length of the list is defined by both end-time and max, whichever comes first.

To specify backward search, end-time should be smaller than start-time or dir should have the value of backward and end-time is not defined.

A conflict between timing (start/end-time) and direction (forward/backward) returns an empty list.

Examples:

prints the first 100 changes of the signal tb.HDT.cpu.CS starting at time 10000

Example¶

set signal tb.HDT.cpu.CS
set start_time 10000
foreach {time value} [gtkwave::signalChangeList $signal -start_time $start_time -max 100] {
    puts "Time: $time value: $value"
}

retrieve the value of tb.HDT.cpu.CS at time 123456

Example¶

lassign [gtkwave::signalChangeList tb.HDT.cpu.CS -start_time 123456 -max 1] dont_care value*

unhighlightSignalsFromList: unhighlights the facilities contained in the list argument

Syntax: set num_unhighlighted [ gtkwave::unhighlightSignalsFromList list ]

Example¶

set clk48 [list]
lappend clk48 "$facname1"
lappend clk48 "$facname2"
...
set num_highlighted [ gtkwave::unhighlightSignalsFromList $clk48 ]