Specman Beta

Features
Specman 4.3.4
Legal Notice
Copyright © 1998-2004 Verisity Design, Inc. All rights reserved.

Trademarks
Verisity, the Verisity logo, eAnalyzer, eCelerator, eRM, Invisible Specman, LicenseE,
Pure IP, Specman, Specman Elite, SpeXsim, SpeXtreme, SureCov, SureLint, SureSolve,
sVM, Verification Advisor, Verification Alliance, Verification Vault, Verification
Viewport, Visualization Toolkit, vManager, vPlan, Xbench, Xchange, Xcite, Xoc, Xpert,
Xsim, and Xtreme are either trademarks or registered trademarks of Verisity Design, Inc.
in the United States and/or other jurisdictions. All other trademarks are the exclusive
property of their respective owners.

Confidentiality Notice
Verisity confidential, do not distribute. The contents of this document constitute valuable
proprietary and confidential property of Verisity Design, Inc. No part of this information
product may be reproduced, transmitted, or translated in any form or by any means,
electronic, mechanical, manual, optical, or otherwise without prior written permission
from Verisity Design, Inc.

Information in this product is subject to change without notice and does not represent a
commitment on the part of Verisity. The information contained herein is the proprietary
and confidential information of Verisity or its licensors, and is supplied subject to, and may
be used only by Verisity’s customers in accordance with, a written agreement between
Verisity and its customers. Except as may be explicitly set forth in such agreement,
Verisity does not make, and expressly disclaims, any representations or warranties as to the
completeness, accuracy, or usefulness of the information contained in this document.
Verisity does not warrant that use of such information will not infringe any third party
rights, nor does Verisity assume any liability for damages or costs of any kind that may
result from use of such information.

Restricted Rights Legend

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in
subparagraphs (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013.

Destination Control Statement

All technical data contained in this product is subject to the export control laws of the
United States of America. Disclosure to nationals of other countries contrary to United
States law is prohibited. It is the reader’s responsibility to determine the applicable
regulations and to comply with them.
Contents

1 About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1

1.1 About Beta Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
1.2 Conventions in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.3 Syntax Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

2 Using the Visualization Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
2.1.1 VT Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
2.2 VT Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
2.2.1 Defining and Configuring VT Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
2.2.1.1 Extending the VT Window Kind and Subtype . . . . . . . . . . . . . . . . . 2-3
2.2.1.2 Configuring a Specific VT Window . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
2.2.1.3 Default Values for VT Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
2.2.2 VT Window Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
2.2.3 VT Window States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
2.2.4 VT Window Reuse Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
2.2.5 VT Window Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
2.2.6 Customizing Menus and the Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
2.2.6.1 Predefined Menus and Menu Commands . . . . . . . . . . . . . . . . . . . . . 2-9
2.2.6.2 Adding Menus and Menu Commands . . . . . . . . . . . . . . . . . . . . . . . 2-11
2.2.6.3 Adding Separators to Menus and the Toolbar . . . . . . . . . . . . . . . . . 2-11
2.2.6.4 Enabling and Disabling Menu Commands . . . . . . . . . . . . . . . . . . . 2-11
2.2.7 Adding Secondary Toolbars to a VT Window . . . . . . . . . . . . . . . . . . . . . . . . 2-11
2.2.8 VT Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
2.2.8.1 Using VT Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
2.2.8.2 Predefined VT Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

Specman Beta Features iii

Contents

2.2.8.3 Adding Custom VT Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

2.2.9 VT Window History Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
2.2.9.1 Navigating to Previous and Next Pages . . . . . . . . . . . . . . . . . . . . . . 2-13
2.2.9.2 Examining a Window’s History . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
2.2.10 Window ID Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
2.2.11 Closing a VT Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
2.2.12 VT Window Method Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
2.2.12.1 Errors for Inappropriate Use of VT Window Methods . . . . . . . . . . 2-16
2.3 VT Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
2.3.1 Defining and Configuring VT Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
2.3.2 Configuring a Specific VT Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
2.3.2.1 Using the configure() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
2.3.2.2 Calling Page Configuration Methods on the Page Instance . . . . . . 2-20
2.3.3 Creating and Displaying New VT Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
2.3.3.1 Creating VT Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
2.3.3.2 Displaying VT Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
2.3.4 Binding a VT Page to a VT Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
2.3.5 Setting the Content of a VT Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
2.3.5.1 Types of Content Displayed in VT . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
2.3.5.2 Methods for Setting Page Content . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
2.3.5.3 Showing HTML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
2.3.5.4 Showing Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
2.3.5.5 Showing Text Files, Images, and Directories . . . . . . . . . . . . . . . . . 2-26
2.3.5.6 Actual and Requested Content Query Methods . . . . . . . . . . . . . . . . 2-26
2.3.5.7 Incorrect Content Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
2.3.6 VT Page States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
2.3.7 VT Page Method Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
2.3.7.1 Errors for Inappropriate Use of VT Page Methods . . . . . . . . . . . . . 2-28
2.3.8 Searching for Text in VT Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
2.3.9 Jumping to Anchor Locations in HTML Pages . . . . . . . . . . . . . . . . . . . . . . . 2-29
2.3.10 Setting and Getting the Values of HTML Components . . . . . . . . . . . . . . . . . 2-30
2.3.11 Saving and Restoring Page Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31
2.4 VT Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31
2.4.1 Opening and Showing VT Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32
2.4.2 Converting Template Files to HTML Files . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32
2.4.3 Creating HTML Code for Different VT Components . . . . . . . . . . . . . . . . . . 2-33
2.4.4 Opening VT Pages in an External Browser . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34
2.4.5 Using VT for Textual Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35

iv Specman Beta Features

 Contents

2.4.6 VT Colors and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35

2.4.6.1 Predefined Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35
2.4.6.2 Using Styles to Colorize Text in Specview . . . . . . . . . . . . . . . . . . . 2-36
2.4.7 Using VT Manager History Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36
2.5 Using Specman to Create HTML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
2.5.1 HTML Hyperlinks, Widgets and Commands . . . . . . . . . . . . . . . . . . . . . . . . 2-37
2.5.1.1 HTML Hyperlinks and Anchors . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
2.5.1.2 HTML Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
2.5.1.3 HTML Spaces and Newlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39
2.5.1.4 Referencing HTML Widget Values . . . . . . . . . . . . . . . . . . . . . . . . . 2-39
2.5.1.5 Associating Specman Commands with HTML Widgets and Hyperlinks
2-41
2.5.1.6 Showing Tooltips Over HTML Widgets and Hyperlinks . . . . . . . . 2-44
2.5.2 Creating HTML Building Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44
2.5.2.1 Creating HTML Hyperlinks and Anchors . . . . . . . . . . . . . . . . . . . . 2-44
2.5.2.2 Creating HTML Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45
2.5.2.3 Creating HTML Input Components . . . . . . . . . . . . . . . . . . . . . . . . . 2-46
2.5.2.4 Creating Visualization Stripe Chart Components . . . . . . . . . . . . . . 2-46
2.5.2.5 Creating Other HTML Components . . . . . . . . . . . . . . . . . . . . . . . . 2-48
2.5.3 Creating an HTML Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48
2.5.3.1 Working with Lists of Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48
2.5.3.2 Using Text Expansion Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . 2-49
2.5.3.3 Working with HTML Template Files . . . . . . . . . . . . . . . . . . . . . . . 2-51
2.6 Visualization Toolkit Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-53
2.6.1 Sample e Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-53
2.6.2 Packet Viewer Example Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-56
2.7 Visualization Toolkit Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58
2.7.1 VT Manager API Methods for Opening VT Windows . . . . . . . . . . . . . . . . . 2-59
2.7.2 show_page() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-60
2.7.3 show_page_with_title() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61
2.7.4 open_page() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62
2.7.5 open_page_with_title() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64
2.7.6 show_search() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-65
2.7.7 VT Manager API Methods for Creating HTML Files . . . . . . . . . . . . . . . . . . 2-66
2.7.8 template_to_html() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-66
2.7.9 template_to_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-67
2.7.10 list_to_html() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-68
2.7.11 VT Manager API Methods for Creating HTML Component Code . . . . . . . . 2-69

Specman Beta Features v

Contents

2.7.12 HTML Helper Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-69

2.7.13 HTML_NEWLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-69
2.7.14 HTML_SPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-70
2.7.15 HTML_HORIZONTAL_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-71
2.7.16 Hyperlink Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72
2.7.17 lnk_command() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72
2.7.18 lnk_search() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-73
2.7.19 lnk_url_in_browser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-74
2.7.20 lnk_instance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-76
2.7.21 lnk_page() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-77
2.7.22 lnk_page_with_title() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-78
2.7.23 html_anchor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-80
2.7.24 lnk_anchor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-80
2.7.25 HTML Widget Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-81
2.7.26 btn_command() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82
2.7.27 btn_search() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-83
2.7.28 btn_url_in_browser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-85
2.7.29 btn_instance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-86
2.7.30 btn_page() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-87
2.7.31 btn_page_with_title() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-88
2.7.32 inp_textfield() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-89
2.7.33 inp_textarea() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91
2.7.34 inp_combobox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92
2.7.35 inp_listbox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-93
2.7.36 inp_checkbox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-94
2.7.37 inp_member() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-95
2.7.38 inp_hidden() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-97
2.7.39 Advanced Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-98
2.7.40 html_stripe() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-98
2.7.41 add_box() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-99
2.7.42 add_divider() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-100
2.7.43 add_field_boxes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-101
2.7.44 clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102
2.7.45 html_command_output() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-103
2.7.46 html_report() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-104
2.7.47 html_body() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-105

vi Specman Beta Features

 Contents

2.7.48 html_modules() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-106

2.7.49 inp_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-107
2.7.50 html_image() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-109
2.7.51 VT Manager API Methods for Using External Browsers . . . . . . . . . . . . . . 2-109
2.7.52 show_url_in_browser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-110
2.7.53 show_file_in_browser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-111
2.7.54 VT Manager API Utility Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-111
2.7.55 expand_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-112
2.7.56 expand_file_to_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-113
2.7.57 get_absolute_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-115
2.7.58 instance_to_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-116
2.7.59 get_color_code() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-116
2.7.60 text_style() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-119
2.7.61 show_styles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-122
2.7.62 get_all_windows() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-123
2.7.63 get_all_pages() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-123
2.7.64 VT Window API Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-125
2.7.65 Window Configuration Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-125
2.7.66 configure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-125
2.7.67 Window Graphic Properties Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-127
2.7.68 Methods to Set Window Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-127
2.7.69 set_location() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-127
2.7.70 set_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-128
2.7.71 set_locked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-129
2.7.72 set_title_prefix() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-131
2.7.73 Methods to Display Window Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-132
2.7.74 is_visible() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-132
2.7.75 is_opened() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-133
2.7.76 is_closed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-134
2.7.77 is_locked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-135
2.7.78 is_lockable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-136
2.7.79 Methods to Display Window Information . . . . . . . . . . . . . . . . . . . . . . . . . . 2-137
2.7.80 get_current_page() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-137
2.7.81 get_all_pages() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-138
2.7.82 get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-139
2.7.83 get_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-140

Specman Beta Features vii

Contents

2.7.84 get_location() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-141

2.7.85 get_title_prefix() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-142
2.7.86 Interactive Calls to Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-143
2.7.87 to_front() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-143
2.7.88 Menu Bar and Toolbar Preparation Methods . . . . . . . . . . . . . . . . . . . . . . . . 2-144
2.7.89 add_menu() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-145
2.7.90 add_menu_item() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-146
2.7.91 add_menu_separator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-148
2.7.92 add_toolbar_separator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-149
2.7.93 enable_action() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-150
2.7.94 hide_navigation_buttons() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152
2.7.95 set_lockable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152
2.7.96 Methods for Adding Secondary Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . 2-153
2.7.97 add_secondary_toolbar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-154
2.7.98 add_menu_item_to_secondary_toolbar() . . . . . . . . . . . . . . . . . . . . . . . . . . 2-155
2.7.99 add_separator_to_secondary_toolbar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-156
2.7.100 Window Symbols Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-157
2.7.101 set_symbol_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-158
2.7.102 set_symbol_values() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-159
2.7.103 get_symbol_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-161
2.7.104 get_symbol_values() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-162
2.7.105 Window Closing Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-163
2.7.106 set_pre_close_command() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-163
2.7.107 close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-165
2.7.108 VT Page API Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-165
2.7.109 Configure Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-166
2.8 configure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-166
2.8.1 Methods to Set Page Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-168
2.8.2 set_window_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-168
2.8.3 set_title() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-170
2.8.4 Methods to Set Page Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-171
2.8.5 set_url() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-171
2.8.6 set_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-172
2.8.7 set_anchor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-175
2.8.8 set_html_body() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-176
2.8.9 Methods to Display Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-179

viii Specman Beta Features

 Contents

2.8.10 show() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-179

2.8.11 show_in_new_window() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-180
2.8.12 Methods to Display Page Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-181
2.8.13 is_pre_opened() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-181
2.8.14 is_opened() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-182
2.8.15 is_current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-183
2.8.16 is_closed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-184
2.8.17 Methods to Display Page Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-184
2.8.18 get_window_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-185
2.8.19 get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-186
2.8.20 get_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-187
2.8.21 get_requested_url() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-188
2.8.22 get_requested_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-189
2.8.23 get_requested_anchor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-191
2.8.24 get_requested_html_body() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-192
2.8.25 get_title() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-193
2.8.26 get_window() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-194
2.8.27 Methods to Display the Page Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-195
2.8.28 get_url() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-195
2.8.29 get_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-196
2.8.30 get_anchor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-197
2.8.31 get_actual_html_body() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-198
2.8.32 Interactive Calls to Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-199
2.8.33 find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-199
2.8.34 find_by() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-200
2.8.35 go_to_anchor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-201
2.8.36 Methods to Set and Get Widget Contents . . . . . . . . . . . . . . . . . . . . . . . . . . 2-203
2.8.37 set_widget_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-203
2.8.38 get_widget_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-205
2.8.39 set_widget_items() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-206
2.8.40 get_widget_items() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-207
2.9 Backward Compatibility with Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-208
2.9.1 Changed VT Concepts and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-208
2.9.2 Modifications Needed in New VT Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-208
2.9.3 Deprecated VT Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-210
2.9.4 open_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-211

Specman Beta Features ix

Contents

2.9.5 show_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212

2.9.6 open_template() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-213
2.9.7 show_template() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-215
2.9.8 lnk_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-215
2.9.9 lnk_template() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-216
2.9.10 btn_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-217
2.9.11 btn_template() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-218
2.9.12 is_alive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-219
2.9.13 set_visible() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-220

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1

x Specman Beta Features

1 About This Book
This preface contains the following sections:

• “About Beta Features” on page 1-1

• “Conventions in This Book” on page 1-2
• “Syntax Notation” on page 1-3

1.1 About Beta Features

This manual describes the features that are classified as beta with this release. Beta features are stable
features that have been tested internally and critiqued by a small group of external users.

The beta features are expected to be useful to a wide variety of users. We encourage you to consult with
your Verisity CE (consulting engineer) to decide whether a given beta feature can add value to your
verification environment.

A beta feature's basic functionality generally remains stable between its beta release and its production
release. Enhancements to make the feature more useful, however, can be made during the beta period.
You can influence the enhancements made to beta features by sending usage feedback and enhancement
requests to Verisity.

Functionality enhancements can occasionally result in backward incompatibility with the original beta
feature. If so, you might be required to update your original implementation of a given beta feature after
it is released as a production feature.

Please send your feedback on beta features to your local Verisity CE or to Verisity Support. See the
Search and Browsing Tips for information about how to contact Support.

Note The documentation for a given beta feature is preliminary and might change between the feature's
beta release and production release.

Specman Beta Features 1-1

About This Book
Conventions in This Book

1.2 Conventions in This Book

This manual uses visual cues to help you locate and interpret information easily. These cues are
explained in Table 1-1.

Table 1-1 Document Conventions

Visual Cue Represents

courier The Courier font indicates e or HDL code. For example, the following line
indicates e code:
keep opcode in [ADD, ADDI];

courier bold In examples that show commands and their results, Courier bold indicates the
commands. For example, the following line shows the usage of the Specman
command, load:
vrst-tool> load test1

bold The bold font indicates keywords in descriptive text. For example, the following
sentence contains keywords for the show ini command and the get_symbol()
routine:

You can display these settings with the show ini setting command or retrieve
them within e code with the get_symbol() routine.

italic The italic font represents user-defined variables that you must provide. For
example, the following line instructs you to type the “write cover” as it appears,
and then the actual name of a file:

write cover filename

[ ] square Square brackets indicate optional parameters. For example, in the following
brackets construct the keywords “list of” are optional:

var name: [list of] type

[ ] bold brackets Bold square brackets are required. For example, in the following construct you
must type the bold square brackets as they appear:

extend enum-type-name: [name,…]

1-2 Specman Beta Features

 About This Book
Syntax Notation

Table 1-1 Document Conventions (continued)

Visual Cue Represents

construct, … An item, followed by a separator (usually a comma or a semicolon) and an ellipsis

is an abbreviation for a list of elements of the specified type. For example, the
following line means you can type a list of zero or more names separated by
commas.

extend enum-type-name: [name,…]

| The | character indicates alternative syntax or parameters. For example, the

following line indicates that either the bits or bytes keyword should be used:

type scalar-type (bits | bytes: num)

% Denotes the UNIX prompt.

C1>, C2>, … Denotes the SpeXsim prompt (VHDL, Verilog, or mixed -HDL designs).

> Denotes a third-party VHDL simulator prompt.

vrst-tool> Denotes the prompt for the Verisity tool you are running, including Specman,
vManager, SpeXsim, or SpeXtreme.

1.3 Syntax Notation

Each construct section starts with the syntax for the construct. The syntax shows the construct, any
arguments it accepts with their types, and the construct’s return type if it has one.

When using the construct, terms in bold in the syntax are to be entered exactly as shown. Terms in italics
are to be replaced by terms of your own. The argument types and the construct return type are for
information only and are not entered.

For example, the syntax notation for the predefined pseudo-method named list.first() is:

list.first(exp: bool): list-type

This is what the notation means:

• The bold .first and the parentheses must be entered exactly.

• The parts in italics, list and exp, must be replaced by a list name and an expression.
• “: bool” indicates that the expression must be a Boolean expression.
• “: list-type” means that the pseudo-method returns an item of the list element type.

Specman Beta Features 1-3

About This Book
Syntax Notation

An example of a call to the list.first() pseudo-method is shown below, where numbers is a list of integer
items and my_number is an integer. The pseudo-method returns the first integer in the list greater than 5:
my_number = numbers.first(it > 5)

1-4 Specman Beta Features

2 Using the Visualization Toolkit
This chapter describes the Visualization Toolkit (VT), a mechanism for creating custom windows based
on HTML files. This chapter covers the following topics:

• “Introduction” on page 2-1

• “VT Windows” on page 2-2
• “VT Pages” on page 2-17
• “VT Manager” on page 2-31
• “Using Specman to Create HTML Documents” on page 2-37
• “Visualization Toolkit Example” on page 2-53
• “Visualization Toolkit Method Reference” on page 2-58
• “Backward Compatibility with Previous Releases” on page 2-208

2.1 Introduction
The Visualization Toolkit (VT) is a Specman tool for designing custom HTML windows that can be
used to generate graphical and interactive reports, tutorials, and other simple applications. To create
HTML files that define the window content, VT uses three predefined e language structs (vt,
vt_window and vt_page). These structs and their predefined methods provide access to all VT
capabilities.

2.1.1 VT Conventions
VT obeys the following conventions:

• VT is case-sensitive.

Specman Beta Features 2-1

Using the Visualization Toolkit
VT Windows

All names and searched text in VT are case-sensitive, as in Specman.

• File names can be package-relative (see Chapter 9 “Encapsulation in e” in the Usage and Concepts
Guide for e Testbenches).
You can specify file names relative to any element along SPECMAN_PATH.

2.2 VT Windows
VT windows are graphical interfaces created and maintained by VT. Each VT window is represented in
Specman by an instance of the predefined vt_window struct. You can create a new kind of VT window
with a specific appearance and functionality by defining a new subtype of the vt_window struct and
using the predefined VT method named configure() to define its new attributes. For more information,
see “Defining and Configuring VT Windows” on page 2-3.

A vt_window object is created whenever a VT window is opened, that is, when you show a specific VT
page. You do not create a VT window directly, but rather use the vt or vt_page methods to request one.
The VT window has a content area in which VT pages are shown, containing either text or HTML
content.

This section covers the following topics:

• “Defining and Configuring VT Windows” on page 2-3

• “VT Window Creation” on page 2-5
• “VT Window States” on page 2-6
• “VT Window Reuse Policy” on page 2-6
• “VT Window Components” on page 2-7
• “Customizing Menus and the Toolbar” on page 2-9
• “Adding Secondary Toolbars to a VT Window” on page 2-11
• “VT Symbols” on page 2-11
• “VT Window History Features” on page 2-13
• “Window ID Number” on page 2-14
• “Closing a VT Window” on page 2-15
• “VT Window Method Scope” on page 2-16

See Also
• “VT Window API Methods” on page 2-125

2-2 Specman Beta Features

 Using the Visualization Toolkit
Defining and Configuring VT Windows

2.2.1 Defining and Configuring VT Windows

This section covers the following topics:

• “Extending the VT Window Kind and Subtype” on page 2-3

• “Configuring a Specific VT Window” on page 2-4

2.2.1.1 Extending the VT Window Kind and Subtype

The vt_window struct has an enumerated field of type vt_window_kind, with the field name kind. This
field is used by VT to determine which window shows a specific page.

You can use the vt_window_kind type in two ways:

• With the predefined enumerated value of vt_window_kind, ANY_WINDOW

This is the default kind for every VT window.
• Customizing vt_window_kind to configure the characteristics of the VT window
Configurable features are the menu bar, toolbar, window size, window location, and so on.

Using the Default VT Window Kind

Generally, we recommend defining a new window subtype for each application, but you might want to
use the default ANY_WINDOW VT window for simple windows.

Example
The following opens the default VT window with an instance of the user-defined MY_PAGE VT page
type. The predefined methods used in this example code are described later in this chapter.
var page := new MY_PAGE vt_page with {
.set_file("my_file.html");
};
page.show();

Customizing vt_window_kind
To define a specific type of VT window:

1. Extend the vt_window_kind enumerated type.

For example, you can define a VT window of kind MY_WINDOW by adding the enumerated kind
MY_WINDOW to the vt_window_kind type definition as follows:

Specman Beta Features 2-3

Using the Visualization Toolkit
Defining and Configuring VT Windows

extend vt_window_kind: [MY_WINDOW];

2. Extend the desired subtype of the vt_window struct using the configure() method.

For example:
extend MY_WINDOW vt_window {
configure() is also {
// code for MY_WINDOW vt_window definition
};
};
For more information on the configure() method, see configure() on page 2-125.

2.2.1.2 Configuring a Specific VT Window

Every VT window has the predefined method configure(), which is used to set the attributes of that
window.

The attributes of a VT window that you can set using the configure() method are:

• Size
• Location
• Title
• Menu bar
• Toolbar
• Whether the window is lockable
• Whether the window has navigation buttons (Prev and Next)

To configure a specific VT window:

• Under the relevant VT window subtype, extend the configure() method by adding method calls to
the predefined vt_window methods.

For example, you could set the location and size of a MY_WINDOW VT window and also add a menu
to it as follows:
extend vt_window_kind: [MY_WINDOW];

extend MY_WINDOW vt_window {

configure() is also {
set_location(250, 100);
set_size(600, 500);
add_menu("Packets");
add_menu_item("Packets", "Show Packets", "Show all packets",
"%appl.show_packets()", NULL, "Show Packets");
};

2-4 Specman Beta Features

 Using the Visualization Toolkit
VT Window Creation

};

At runtime, when a new instance of the window is created, the configure() method is called
automatically and the initialization and configuration operations are performed.

Note You must use is also (and not is, is only, or is first) to extend configure().

For more information on the configure() method, see configure() on page 2-125.

2.2.1.3 Default Values for VT Windows

The default values for VT windows (of any type) are:

• x location = 100
• y location = 50
• width = 500
• height = 400
• title prefix = “VT Window”

2.2.2 VT Window Creation

The creation of VT windows is done exclusively by VT. When there is a request to display a VT page,
VT automatically displays that page in a VT window.

Example
// Create a new VT page and configure it to open in a VT window of
// type MY_WINDOW:
var page := new MY_PAGE vt_page with {
.set_window_kind(MY_WINDOW);
.set_file("my_file.html");
};

// Use page_show() to create a new VT window, or reuse an existing window,

// and display the page in the window:
page.show();

In the above example, VT might create a new window to display the page or display the page in an
existing window. For details on whether a new window or an existing window is used, see “VT Window
Reuse Policy” on page 2-6.

Specman Beta Features 2-5

Using the Visualization Toolkit
VT Window States

2.2.3 VT Window States

Some VT window methods apply only to VT windows in a specific state. A VT window can be in one
of the following three states:

• Unopened—A VT window is in the unopened state during its creation and until it is displayed.
• Open—When the window is displayed (visible), its state changes to open.
• Closed—When a window is closed, its state changes to closed, and it cannot be reopened. All of the
pages in that window also become closed.

See Also
• “Closing a VT Window” on page 2-15
• “VT Window Method Scope” on page 2-16
• “Errors for Inappropriate Use of VT Window Methods” on page 2-16

2.2.4 VT Window Reuse Policy

When VT needs a window to display a page, it either reuses an open window or creates a new window.
Whenever possible, VT reuses open windows. If there is an unlocked open window of the required
window kind (determined by the page’s configuration) and there is no explicit command using the VT
page method show_in_new_window() to show the page in a new window, then VT displays the page in
the open window.

See Also
• “VT Window States” on page 2-6
• show_in_new_window() on page 2-180

2-6 Specman Beta Features

 Using the Visualization Toolkit
VT Window Components

2.2.5 VT Window Components

Figure 2-1 The Parts of a VT Window

A VT window has five main parts, as shown in Figure 2-1:

• “Title Bar” on page 2-7

• “Menu Bar” on page 2-8
• “Toolbar” on page 2-8
• “Page Area” on page 2-8
• “Status Bar” on page 2-9

Title Bar
The VT window title bar contains text in two parts, separated by a colon plus a space:

• Window title prefix

• Window page title
1. To specify the title prefix for a VT window, use set_title_prefix() method. For example:
my_window.set_title_prefix("My Window");
All of the pages in the my_window window get a prefix of “My Window”.

Specman Beta Features 2-7

Using the Visualization Toolkit
VT Window Components

Note If no title prefix is specified, then the default prefix “VT Window” is used.

2. To specify a page title, use the set_title() method. For example:

my_page.set_title("My Page");
Assuming that the my_page page appears in the my_window window, the content of the title bar
when that page is displayed is “My Window: My Page”.
Note If no page title is specified, then the title is determined according to the page’s content type:

• HTML pages—For HTML pages, VT uses the title in the <title> tag. If there is no <title> tag,
then the VT page title will be empty and the title bar will show only the VT window title prefix.
• Non-HTML pages—For text files, directories, images, and so on, VT uses the file (or directory)
name as the title.

See Also
• set_title_prefix() on page 2-131
• set_title() on page 2-170

Menu Bar
The menu bar has a set of predefined menus, as shown in Figure 2-1. On each menu, there is a set of
predefined menu commands, also shown in Figure 2-1.

You can add custom menu commands and also create custom menus. For instructions on customizing
menus and menu commands, see “Customizing Menus and the Toolbar” on page 2-9.

Toolbar
The toolbar contains buttons for a subset of menu commands to allow quick access to frequently used
features.

You can customize the toolbar by choosing which menu commands to include there. For instructions on
customizing toolbars, see “Customizing Menus and the Toolbar” on page 2-9.

Page Area
The page area displays the content of the VT page. Typically, it is an HTML page but other types of
pages, such as regular text, are possible.

2-8 Specman Beta Features

 Using the Visualization Toolkit
Customizing Menus and the Toolbar

The application developer defines the scope of interaction with the information: from passively viewing
displayed information to actively modifying page content (for example, by clicking buttons and
hyperlinks). For more information, see “Setting the Content of a VT Page” on page 2-22.

You can use Specman or a range of tools to create the content of VT pages. For more information, see
“Creating an HTML Template File” on page 2-51.

Status Bar
Every VT window has a status bar area that displays some information about the current page.

On the left • For files, the file type is displayed.

• For directories, the number of files in the directory is displayed.
On the right • When VT is active, “Busy” is displayed.
• When VT is idle, “Ready” is displayed.

2.2.6 Customizing Menus and the Toolbar

This section covers the following topics:

• “Predefined Menus and Menu Commands” on page 2-9

• “Adding Menus and Menu Commands” on page 2-11
• “Adding Separators to Menus and the Toolbar” on page 2-11
• “Enabling and Disabling Menu Commands” on page 2-11

2.2.6.1 Predefined Menus and Menu Commands

Any Specman command can be a VT window menu command.

Table 2-1 describes the predefined window menu commands.

Table 2-1 Predefined Menu Commands

Menu Command Description

File Lock Locks/unlocks the window (See also set_locked() on

page 2-129.

Close Closes the window and sends a notification (see “Closing a

VT Window” on page 2-15).

Specman Beta Features 2-9

Using the Visualization Toolkit
Customizing Menus and the Toolbar

Table 2-1 Predefined Menu Commands (continued)

Menu Command Description

Edit Find Opens the Find dialog box to search for text on the current
page.

View Prev Displays the previous page in the same window.

Next Displays the next page in the same window.

Show HTML Source Displays the HTML source code for the current page in
another window. (This action is relevant only for HTML
pages.)

Web Browser Displays the current page in a Web browser.

For more information on using an external Web browser,

see “Opening VT Pages in an External Browser” on page
2-34.

Options Show Toolbar Displays or hides the toolbar. This is a check box that
switches between the two states. The default is checked
(the toolbar is displayed). The three options below, which
control the appearance of the toolbar buttons, are
applicable only when this item is checked. Only one of the
following three options can be selected.

Text and Icon Shows both text and graphic symbols on toolbar buttons.
This is the default.

Icon Only Shows only graphic symbols on toolbar buttons.

Text Only Shows only text on toolbar buttons.

Omitting Predefined Commands

You can create windows that exclude some predefined commands. Specifically, you can exclude the
lock command and the navigation commands (Prev and Next).

For more information, see:

• set_lockable() on page 2-152

• hide_navigation_buttons() on page 2-152

2-10 Specman Beta Features

 Using the Visualization Toolkit
Adding Secondary Toolbars to a VT Window

2.2.6.2 Adding Menus and Menu Commands

In addition to the predefined menus and menu commands, you can add custom menus and menu
commands to a VT window.

For details on adding a new menu, see add_menu() on page 2-145.

For details on adding a menu command to a new or existing menu and, optionally, to the toolbar, see
add_menu_item() on page 2-146.

2.2.6.3 Adding Separators to Menus and the Toolbar

You can add separators between menu commands and toolbar buttons.

For details on adding separators to menus, see add_menu_separator() on page 2-148.

For details on adding separators to the toolbar, see add_toolbar_separator() on page 2-149.

2.2.6.4 Enabling and Disabling Menu Commands

You can enable or disable any user-defined menu commands. When you enable/disable a menu
command, VT automatically enables/disables any corresponding toolbar button. Disabled menu
commands and toolbar buttons are grayed out.

For details on enabling/disabling user-defined menu commands, see enable_action() on page 2-150.

2.2.7 Adding Secondary Toolbars to a VT Window

Each VT Window has a “main” toolbar that shows predefined and user actions (such as navigation
buttons). In addition to the main toolbar, you can add secondary toolbars to the VT window. The
secondary toolbars will appear below the main toolbar. You can add actions and separators to the
secondary toolbar.

When you create a secondary toolbar, you give it a unique name.

The VT methods you use to add a secondary toolbar to a VT window are:

• add_secondary_toolbar() on page 2-154

• add_menu_item_to_secondary_toolbar() on page 2-155
• add_separator_to_secondary_toolbar() on page 2-156

2.2.8 VT Symbols
This section contains the following topics:

Specman Beta Features 2-11

Using the Visualization Toolkit
VT Symbols

• “Using VT Symbols” on page 2-12

• “Predefined VT Symbols” on page 2-12
• “Adding Custom VT Symbols” on page 2-13

2.2.8.1 Using VT Symbols

VT symbols are a convenient way to reference a frequently used string. Symbols are defined per VT
window, and each window has its own list of symbols.

Each symbol associates a symbol name with a value. You reference symbol values with the notation
%symbol-name. For example, you might use the predefined VT window symbol _window to create an
HTML button as follows:
vt.btn_command("print %_window.get_size()", "Window Size");
Note To include “%” in a symbol, use “%%”.

See Also
• “Predefined VT Symbols” on page 2-12
• “Adding Custom VT Symbols” on page 2-13

2.2.8.2 Predefined VT Symbols

All predefined symbols have the format “_symbol-name”.

Table 2-2 shows the predefined VT window symbols.

Table 2-2 Predefined VT Window Symbols

Symbol Name Description

_window The current window’s instance (a vt_window object)

_window_kind The current window kind

Table 2-3 shows the predefined VT page symbols.

Table 2-3 Predefined VT Page Symbols

Symbol Name Description

_page The current page’s instance (a vt_page object)

2-12 Specman Beta Features

 Using the Visualization Toolkit
VT Window History Features

Table 2-3 Predefined VT Page Symbols (continued)

Symbol Name Description

_page_kind The page kind of the current page

_file The name of the current page’s file (usually an HTML file, but can also be a
text file, image file, or directory)

_anchor The location in the current page

2.2.8.3 Adding Custom VT Symbols

When configuring VT windows, you can add custom symbols with the VT window method
set_symbol_value().

Note You can get the value of any symbol with the VT window method get_symbol_value().

See Also
• set_symbol_value() on page 2-158
• set_symbol_values() on page 2-159
• get_symbol_value() on page 2-161
• get_symbol_values() on page 2-162

2.2.9 VT Window History Features

This section contains the following topics:

• “Navigating to Previous and Next Pages” on page 2-13

• “Examining a Window’s History” on page 2-14

2.2.9.1 Navigating to Previous and Next Pages

By default, VT adds Prev and Next buttons to the VT window toolbar to enable navigation between
pages. The Prev and Next commands are also found on the View menu of the window.

As you navigate VT pages, the following changes occur:

• The page portion of the window title changes to show the title of the new page.
• The page area of the window displays the content of the new page.

Specman Beta Features 2-13

Using the Visualization Toolkit
Window ID Number

• Page symbols for the current page reference the new page.
• The enabled/disabled state of menu commands might change.
You can exclude the navigation commands in a window by calling the hide_navigation_buttons()
method during the configuration phase.

See Also
• hide_navigation_buttons() on page 2-152

2.2.9.2 Examining a Window’s History

VT maintains a history for each window based on the following rules:

• Displaying a new VT page is added to the history (even if the content is the same as the previous page).
• Reloading the same VT page is not added to the history.
• Jumping to a new location in an HTML page is added to the history.
• Marking text is not added to the history.
You can use the following VT window methods to examine the VT window history:

• get_current_page()
• get_all_pages()
VT Manager provides similar methods for querying the general history state of all VT windows.

See Also
• get_current_page() on page 2-137
• get_all_pages() on page 2-138
• “VT Manager” on page 2-31

2.2.10 Window ID Number

Every new window instance automatically gets a unique ID number that is the next unused number in
the sequence of all windows.

You can get a VT window ID with the VT window method get_id().

2-14 Specman Beta Features

 Using the Visualization Toolkit
Closing a VT Window

Note The window ID number remains with that window even if the window is reused. In other words,
a reused window keeps its original ID number.

See Also
• get_id() on page 2-187
• “VT Window Reuse Policy” on page 2-6

2.2.11 Closing a VT Window

You can close a VT window in any of three ways:

• By using the Close command on the File menu

• By clicking the X button on the far right of the title bar
• By calling the VT window method close()
When a window is closed, it cannot be reopened. All of the pages in that window also become closed.
You cannot apply any VT window method on a closed window.

In the absence of a callback, a window closes with no notification.

To get notification that a VT window is about to close, in the unopened state of the VT window, set the
window method set_pre_close_command().

For example:
extend MY_WINDOW vt_window {
configure() is also {
set_pre_close_command("print %_window is about to close");
};
};

See Also
• close() on page 2-165
• set_pre_close_command() on page 2-163
• “VT Window States” on page 2-6
• “VT Window Reuse Policy” on page 2-6

Specman Beta Features 2-15

Using the Visualization Toolkit
VT Window Method Scope

2.2.12 VT Window Method Scope

Whether you can use a particular VT window method depends on the state of the window:

• Methods that configure the VT window can only be called for an unopened window.
• Methods that perform actions on a VT window can only be called on an open window.
• Methods that query the state of a VT window can be called at any time.
For detailed information on each of the VT window methods, see “VT Window API Methods” on page
2-125.

See Also
• “VT Window States” on page 2-6
• “Errors for Inappropriate Use of VT Window Methods” on page 2-16
• configure() on page 2-125

2.2.12.1 Errors for Inappropriate Use of VT Window Methods

The following errors result from trying to use VT window methods on windows that are not in the
appropriate state:

• ***Error: Cannot call 'method-name' after the window was opened

Issued if a method that can only be used on an unopened window is called for a window that is
already open
• ***Error: Cannot call 'method-name' before the window was opened
Issued if a method that can only be used on an open window is called for an unopened window
• ***Error: Cannot call 'method-name' after the window was closed
Issued if a method is called for a closed window

See Also
• “VT Window States” on page 2-6

2-16 Specman Beta Features

 Using the Visualization Toolkit
VT Pages

2.3 VT Pages
A VT page consists of the content that is displayed in the page area of a VT window. Usually this
content is of HTML type; but it can also be text files, images, or file system directories. Each VT
window can have many pages, one on top of another. Each VT page is represented in Specman by an
instance of the vt_page struct. You can create a new VT page by defining a new subtype of the vt_page
struct and using the predefined VT page method configure() to define the page’s attributes. For more
information, see “Defining and Configuring VT Pages” on page 2-17.

This section covers the following topics:

• “Defining and Configuring VT Pages” on page 2-17

• “Configuring a Specific VT Page” on page 2-19
• “Creating and Displaying New VT Pages” on page 2-20
• “Binding a VT Page to a VT Window” on page 2-22
• “Setting the Content of a VT Page” on page 2-22
• “VT Page States” on page 2-27
• “VT Page Method Scope” on page 2-28
• “Searching for Text in VT Pages” on page 2-29
• “Jumping to Anchor Locations in HTML Pages” on page 2-29
• “Setting and Getting the Values of HTML Components” on page 2-30
• “Saving and Restoring Page Data” on page 2-31

See Also
• “VT Page API Methods” on page 2-165

2.3.1 Defining and Configuring VT Pages

The non-generatable vt_page struct has an enumerated field of type vt_page_kind, with the field name
kind. This field is used by VT to encapsulate all of the characteristics of VT pages of that kind in a
central place.

You can use the vt_page_kind type in two ways:

• With the predefined enumerated value of vt_page_kind, ANY_PAGE

This is the default kind for every VT page.

Specman Beta Features 2-17

Using the Visualization Toolkit
Defining and Configuring VT Pages

• Customizing vt_page_kind to configure the characteristics of the VT page

Configurable features are the page content, page title, binding window, and so on.

Using the default VT page kind

Generally, we recommend defining a new page subtype for each application, but you might want to use
the default ANY_PAGE VT page for simple pages.

For example, the following opens the default VT page:

//create the default vt_page
var page:= new vt_page with {
.set_file("my_file.html");
};
//show the page
page.show();
Note After creating the VT page and before it is displayed, you can still configure the page without
using the configure() method.

Customizing the VT page kind

To define a specific type of VT page:

1. Extend the vt_page_kind enumerated type.

For example, you can define a VT page of kind MY_PAGE by adding the enumerated kind
MY_PAGE to the vt_page_kind type definition as follows:
extend vt_page_kind: [MY_PAGE];

2. Extend the desired subtype of the vt_page struct using the configure() method.

For example:
extend MY_PAGE vt_page {
configure() is also {
// code for MY_PAGE vt_page definition
};
};

Default value for any VT page

By default, a VT page of any type opens in a VT window of kind ANY_WINDOW.

2-18 Specman Beta Features

 Using the Visualization Toolkit
Configuring a Specific VT Page

See Also
• configure() on page 2-125

2.3.2 Configuring a Specific VT Page

Before a VT page is opened, you can set the following attributes of the page:

• Content
• Title
• Binding window
This section explains the two ways to set the attributes of a specific VT page:

• “Using the configure() Method” on page 2-19

• “Calling Page Configuration Methods on the Page Instance” on page 2-20

2.3.2.1 Using the configure() Method

Every VT page has the predefined configure() method.

To define a new page using the configure() method, under the relevant VT page subtype, extend the
configure() method by adding method calls to the predefined vt_page methods.

For example, you could set the title, content, and binding window of MY_PAGE VT page as follows:
extend vt_page_kind: [MY_PAGE];

extend MY_PAGE vt_page {

configure() is also {
set_window_kind(MY_WINDOW);
set_file("my_file.html");
set_title("My Page");
};
};

At runtime, when a new instance of the window is created, the configure() method is called
automatically and the initialization and configuration operations are performed.

Note You must use is also (and not is, is only, or is first) to extend configure().

For more information on the configure() method, see configure() on page 2-125.

Specman Beta Features 2-19

Using the Visualization Toolkit
Creating and Displaying New VT Pages

2.3.2.2 Calling Page Configuration Methods on the Page Instance

To define a new page by calling the page configuration methods on the page instance:

1. Create a new page instance.

For example:
var page := new MY_PAGE vt_page;

2. Configure the new page instance.

For example:
page.set_file("my_file.html");
page.set_title("My Page");
page.set_window_kind(MY_WINDOW);
Note As all VT windows are created automatically, this can be done only for VT pages and not for VT
windows.

2.3.3 Creating and Displaying New VT Pages

This section covers the following topics:

• “Creating VT Pages” on page 2-20

• “Displaying VT Pages” on page 2-21

2.3.3.1 Creating VT Pages

When you create a new VT page, it is neither bound to any window nor displayed.

To create a new instance of a VT page, use the new operator.

The following examples assume that you have defined a MY_PAGE VT page as follows:
extend MY_PAGE vt_page {
configure is also {
// code for configuring the VT page
};
};

Example 1 Creating a MY_PAGE VT page

var page := new MY_PAGE vt_page;

or:

2-20 Specman Beta Features

 Using the Visualization Toolkit
Creating and Displaying New VT Pages

var page: MY_PAGE vt_page = new;

Example 2 Creating the default VT page (of type ANY_PAGE)

var page := new vt_page;

or:
var page: ANY_PAGE vt_page = new;

Example 3 Creating the default VT page and initializing it

var page := new vt_page with {
//call VT page methods
.set_file("my_file.html");
};

2.3.3.2 Displaying VT Pages

To display a VT page, call either of the following VT page methods:

• show()
For example:
my_page.show();

• show_in_new_window()
For example:
my_page.show_in_new_window();

When the show() or show_in_new_window() methods of vt_page are called, VT binds the page to a
specific VT window, according to the window kind. At that point, the page is considered to be open.

Note Before displaying a VT page, you must set the page content.

See Also
• show() on page 2-179
• show_in_new_window() on page 2-180
• “Binding a VT Page to a VT Window” on page 2-22
• “VT Page States” on page 2-27

Specman Beta Features 2-21

Using the Visualization Toolkit
Binding a VT Page to a VT Window

2.3.4 Binding a VT Page to a VT Window

When you request the display of a VT page, VT must decide which VT window to display that page in.

You can specify the VT window kind used to display the VT page. If you do not specify the VT window
kind to use, VT shows the page in the default ANY_WINDOW window.

To specify the window kind that is used to show the page, use the VT page method set_window_kind()
in the configure() method.

For example, you could bind MY_PAGE VT page to a MY_WINDOW VT window as follows:
extend MY_PAGE vt_page {
configure is also {
set_window_kind(MY_WINDOW);
};
};

The actual binding occurs when the VT page show() or VT page show_in_new_window() method is
called.

VT shows the page either in an existing VT window or in a new VT window according to the VT
window reuse policy (see “VT Window Reuse Policy” on page 2-6).

See Also
• set_window_kind() on page 2-168
• “VT Window Reuse Policy” on page 2-6

2.3.5 Setting the Content of a VT Page

This section contains the following topics:

• “Types of Content Displayed in VT” on page 2-23

• “Methods for Setting Page Content” on page 2-23
• “Showing HTML Files” on page 2-25
• “Showing Template Files” on page 2-25
• “Showing Text Files, Images, and Directories” on page 2-26
• “Actual and Requested Content Query Methods” on page 2-26
• “Incorrect Content Settings” on page 2-27

2-22 Specman Beta Features

 Using the Visualization Toolkit
Setting the Content of a VT Page

2.3.5.1 Types of Content Displayed in VT

VT can show the following content:

• HTML
• Text (such as an e file)
• Images
• Directories

2.3.5.2 Methods for Setting Page Content

Before displaying a VT page, the page content must be set. There is no default page content. You can set
the VT page content by calling one of the following VT page methods:

“For All Files—Setting the VT Page URL” • set_url()

• set_file()
“For HTML Files Only—Setting the VT Page • set_html_body()
HTML Body” • set_anchor()

Note You can call any of these methods any number of times before the page is displayed.

For All Files—Setting the VT Page URL

To set the VT page URL, use set_url().

For example:
my_page.set_url("file:/my_dir/my_file.html#my_anchor");

The full URL is displayed on the page. The full URL can include the protocol and the anchor.

Note VT cannot open web URLs.

See Also
• set_url() on page 2-171
• show_url_in_browser() on page 2-110

For All files—Setting the VT Page File

To set the VT page file, use set_file().

For example, you might show the current directory as follows:

Specman Beta Features 2-23

Using the Visualization Toolkit
Setting the Content of a VT Page

my_page.set_file(".");

You can use this method to show HTML files (including template files), text files, image files, and
directories. You must supply VT with the name of a file or directory (which may or may not exist).
NULL or empty names are not allowed.

Note File/directory names can be full-path or relative names along SPECMAN_PATH.

See Also
• set_file() on page 2-172
• “Showing Template Files” on page 2-25

For HTML Files Only—Setting the VT Page HTML Body

To set the VT page HTML body, use set_html_body().

For example:
// Create the html body
var a_list: list of string;
a_list.add("VT example");
a_list.add(vt.lnk_command("show data sys", "Show Data"));

// Set the html body

a_page.set_html_body(a_list);

A list of string is passed as the parameter to this method. This list of string constitutes the body of the
HTML. When the VT page is shown, VT wraps the body with proper HTML code, creates an HTML
file, and displays it.

Tip The VT manager expand constructs and template methods can help you to create the list of string.
(See “Using Text Expansion Constructs” on page 2-49 and “Working with HTML Template Files” on
page 2-51).

See Also
• set_html_body() on page 2-176
• “Using Specman to Create HTML Documents” on page 2-37

For HTML Files Only—Setting the VT Page Location

To set the VT page location, use set_anchor().

2-24 Specman Beta Features

 Using the Visualization Toolkit
Setting the Content of a VT Page

For example, you could open the HTML file my_file.html at the starting location my_anchor as follows:
a_page.set_file("my_file.html");
a_page.set_anchor("my_anchor");

This method specifies the location (anchor) in an HTML page. The HTML page opens at the specified
location. This method must be used in conjunction with set_file() or set_html_body().

See Also
• set_file() on page 2-172
• set_anchor() on page 2-175
• set_html_body() on page 2-176

2.3.5.3 Showing HTML Files

To create a VT page with HTML content, you have the following options:

• Set the HTML from a URL.

To set the URL use the VT page method set_url().
• Set the HTML file name (full name or relative name along SPECMAN_PATH).
To set the file name use the VT page method set_file().
• Set the HTML file from a template file (you will need to convert it to HTML).
To set the template file use VT page method set_file() with the result of converting the template file
to an HTML file.
• Set the HTML body (by supplying a list of string) and let VT create a legal HTML file from it.
To set the HTML body use the VT page method set_html_body().
• Set the HTML location (anchor) that will be the starting location when the page is shown.
To set the anchor use the VT page method set_anchor().

2.3.5.4 Showing Template Files

To open a template file in VT, you need to do the following:

• Convert the template file to a normal HTML file.

To convert a template file to an HTML file, use the VT manager method template_to_html().
• Use the VT page set_file() method, passing it the HTML file as the argument.

Specman Beta Features 2-25

Using the Visualization Toolkit
Setting the Content of a VT Page

See Also
• “Using Specman to Create HTML Documents” on page 2-37
• set_file() on page 2-172
• template_to_html() on page 2-66

2.3.5.5 Showing Text Files, Images, and Directories

Other than HTML files you can show the following file types in VT:

• Text files (such as e files)

• Images in GIF, JPEG, or PNG format.
• Directory contents.
Use the VT Page method set_file() to set the above content.

For example, to set the content of the MY_PAGE VT page to be the e file my_file.e, do as follows:
extend MY_PAGE vt_page {
configure is also {
set_file("my_file.e");
};
};
Note When showing directories in VT, you will get relevant information on the directory contents and
you will be able to do normal file system navigation.

2.3.5.6 Actual and Requested Content Query Methods

VT page has two types of methods for querying the page content:

• Methods that return the requested content of the VT page.

• Methods that return the actual content of the VT page.
For example:

To set the file content of the VT page, use:

my_page.set_file("my_file.html");

To get the requested file name of the VT page, use:

my_page.get_requested_file();

To get the actual file name of the displayed VT page, use:

2-26 Specman Beta Features

 Using the Visualization Toolkit
VT Page States

my_page.get_file();

In the example above, the actual file name can be different from the requested file name.

For example, if the file you requested is not found along SPECMAN_PATH, then VT sets the actual file
of this page to that of a special “url_not_found” file, which VT generates.

See Also
• get_requested_url() on page 2-188
• get_requested_file() on page 2-189
• get_requested_anchor() on page 2-191
• get_requested_html_body() on page 2-192
• get_url() on page 2-195
• get_file() on page 2-196
• get_anchor() on page 2-197
• get_actual_html_body() on page 2-198

2.3.5.7 Incorrect Content Settings

The following errors occur on incorrect configuration of VT page content:

• *** Error: Cannot open a new page before setting a file or HTML body
Issued if the page is about to be displayed but the page content is not set
• *** Error: Illegal NULL file name
Issued if the page file name is set to NULL or an empty string
• *** Error: Cannot call ‘method-name’ after the page was opened
Issued if the page content is set after the page is displayed

2.3.6 VT Page States

Some VT page methods apply only to VT pages in a specific state. A VT page can be in one of the
following states:

• Unopened—A VT page is in the unopened state during its creation and until it is displayed.
• Open —When the page is displayed.

Specman Beta Features 2-27

Using the Visualization Toolkit
VT Page Method Scope

• current—When the page is the top page in the VT window

• not-current—When the page is not the top page in the VT window
• Closed—When the binding window is closed all of the pages in that window also become closed.
A closed page cannot be reopened.

See Also
• “VT Page Method Scope” on page 2-28

2.3.7 VT Page Method Scope

Whether or not you can use a particular VT page method depends on the state of the page:

• Methods that configure and display the VT page can only be called for an unopened page.
• Methods that perform actions on a VT page can only be called on the current page.
• Methods that query the state of a VT page can be called at any time.
For detailed information on each of the VT page methods, see “VT Page API Methods” on page 2-165.

See Also
• “Errors for Inappropriate Use of VT Page Methods” on page 2-28

2.3.7.1 Errors for Inappropriate Use of VT Page Methods

The following errors result from trying to use VT page methods on pages that are not in the appropriate
state:

• *** Error: Cannot call ‘method-name’ after the page was opened
Issued if a method that can only be used on an opened page is called for a page that is already open.
• *** Error: Cannot call ‘method-name’ before the page was opened
Issued if a method that can only be used on an open page is called for an unopened page.
• *** Error: Cannot call ‘method-name’ after the page was closed
Issued if a method is called for a closed page.

2-28 Specman Beta Features

 Using the Visualization Toolkit
Searching for Text in VT Pages

2.3.8 Searching for Text in VT Pages

To search the current VT page for a given string you can use the VT page methods find() and find_by().
Matching results are highlighted.

For example, to search for the text “my_text” in the current page my_page, do as follows:
my_page.find("my_text");

This will do the default search, which marks all occurrences of the text found, searches for whole words
only and is not case sensitive.

To refine the search, use the VT page find_by() method.

Note These methods can only be applied on the current VT page.

See Also
• find() on page 2-199
• find_by() on page 2-200
• “VT Page States” on page 2-27

2.3.9 Jumping to Anchor Locations in HTML Pages

You can use the VT page method go_to_anchor() to jump to an anchor (a location) in an HTML page
and mark text near that anchor.

The syntax of this method is:

vt-page.go_to_anchor(anchor-name: string, mark: bool, text: string): string

For example, to jump to an anchor named “my_anchor” and mark the text “my_text” after the anchor do
as follows:
my_page.go_to_anchor("my_anchor", TRUE, "my_text");

The process for jumping to an anchor and marking text has the following logic:

1. An anchor matching anchor-name is searched in the HTML page.

2. If no matching anchor is found, return.

3. If an anchor is found, VT jumps to it.

4. If mark is FALSE, return.

5. If text is empty (“”), then VT uses “*” as the default text.

Specman Beta Features 2-29

Using the Visualization Toolkit
Setting and Getting the Values of HTML Components

6. VT searches for a word matching text after the anchor.

7. If no matching string is found, return.

8. If a matching string is found, VT marks the first matching word.

Any call to go_to_anchor() removes all previous marks, even if the new call does not find or mark any
text.

Note This method can only be applied to the current VT page of type HTML.

See Also
• go_to_anchor() on page 2-201
• html_anchor() on page 2-80
• “VT Page States” on page 2-27

2.3.10 Setting and Getting the Values of HTML Components

When the content of a VT page is HTML, you can set and get values of specific components inside the
HTML page. This is done using the component’s name, which you define as explained in “Creating
HTML Input Components” on page 2-46.

The following VT page methods set and get the values of HTML components. These methods can be
used for text fields, text areas, check boxes, combo boxes and list boxes.

• set_widget_value() on page 2-203

This method sets a value into an HTML component.
• get_widget_value() on page 2-205
This method gets the content of an HTML component.

Those methods can only be applied to a current VT page.

If the HTML component name is not unique, then VT changes the duplicate names and issues a warning.
For example, if VT finds two check boxes with the same name, “box”, it changes the second name to
“box_1”.

Note The methods above cannot be used for HTML buttons or hyperlinks.

See Also
• “Creating HTML Input Components” on page 2-46

2-30 Specman Beta Features

 Using the Visualization Toolkit
Saving and Restoring Page Data

• “Referencing HTML Widget Values” on page 2-39

2.3.11 Saving and Restoring Page Data

You can interact with HTML pages to supply information that can be used by subsequent pages. This
includes interactions such as filling text fields, checking boxes, and so on. When VT goes from one page
to the next, it saves those properties, so that if you decide to go back to the previous page all of the data
you entered is still displayed.

The following data is saved and restored:

• Values in text widgets

• Selections in combo boxes and list boxes
• Checked states in check boxes
• Color (foreground, background) of all widgets
• Enabled state of all widgets
• Editable state of text widgets
• Last anchor location
• Highlight marks
• Scrollbar position
• Enable state of menu commands
Note To clear all data you need to reload the page.

2.4 VT Manager
VT Manager has many useful utilities that can help build VT applications. VT manager is implemented
in a predefined global object named vt.

This section covers the following topics:

• “Opening and Showing VT Pages” on page 2-32

• “Converting Template Files to HTML Files” on page 2-32
• “Creating HTML Code for Different VT Components” on page 2-33
• “Opening VT Pages in an External Browser” on page 2-34
• “Using VT for Textual Search” on page 2-35

Specman Beta Features 2-31

Using the Visualization Toolkit
Opening and Showing VT Pages

• “VT Colors and Styles” on page 2-35

• “Using VT Manager History Methods” on page 2-36

See Also
• “VT Manager API Utility Methods” on page 2-111

2.4.1 Opening and Showing VT Pages

VT Manager has several shortcut methods for opening and showing VT pages.

For example, to show the “my_file.e” file in a VT window of kind MY_WINDOW and a title of “My
Page” do as follows:
vt.show_page_with_title("my_file.e", MY_WINDOW, "My Page");
Note The page that VT will use is the default ANY_PAGE VT page.

See Also
• show_page() on page 2-60
• show_page_with_title() on page 2-61
• open_page() on page 2-62
• open_page_with_title() on page 2-64
• “Creating and Displaying New VT Pages” on page 2-20

2.4.2 Converting Template Files to HTML Files

VT Manager supplies several methods that can be used to convert template files to HTML files or to a
list of string.

After converting the template file to an HTML file, you can show the converted file in a VT window
using the VT page set_file() method. For details see “Showing Template Files” on page 2-25.

Note You can also convert a list of string to an HTML file.

See Also
• template_to_html() on page 2-66
• template_to_list() on page 2-67

2-32 Specman Beta Features

 Using the Visualization Toolkit
Creating HTML Code for Different VT Components

• list_to_html() on page 2-68

• set_file() on page 2-172
• “Using Specman to Create HTML Documents” on page 2-37

2.4.3 Creating HTML Code for Different VT Components

VT supplies many methods for creating HTML code that can be embedded in a template file or used in
a list of string. This HTML code represents HTML components and hyperlinks.

For example:

• To create an HTML button that when clicked will print information on the current page do as follows:
var button_code: string = vt.btn_command("print %_page")

• To create a new line do as follows:

var newline_code: string = vt.HTML_NEWLINE;

• To create a hyperlink that when clicked will open the databrowser with a sys instance, do as follows:
var hyperlink_code: string = vt.lnk_instance(sys, "Show sys");

This HTML code can be stored in a list of string or a template file and then shown in VT.

• To create a list of string from the above HTML code and then show it in VT, do as follows:
//create the list of strings
var lst_html : list of string;
lst_html.add(button_code);
lst_html.add(vt.HTML_NEWLINE);
lst_html.add(hyperlink_code);

//create the VT page

var my_page := new MY_PAGE vt_page;
my_page.set_html_body(lst_html);
my_page.show();

• To create a template file from the above code and then show it in VT, do as follows:
1 //create the Template file and save it "my_template.html"
<(vt.btn_command("print %_page", "Print"))>
<(vt.HTML_NEWLINE)>
<(vt.lnk_instance(sys, "Show sys"))>

2 //create the VT page

var my_page := new MY_PAGE vt_page;

Specman Beta Features 2-33

Using the Visualization Toolkit
Opening VT Pages in an External Browser

my_page.set_file(vt.template_to_html("my_template.html));
my_page.show();

See Also
• “Using Specman to Create HTML Documents” on page 2-37
• “VT Manager API Methods for Creating HTML Component Code” on page 2-69

2.4.4 Opening VT Pages in an External Browser

The show_url_in_browser() Method

You can request that a specific page will open in an external browser. The default browser used is
Netscape but you can use the SPECMAN_WEB_BROWSER environment variable to set the external
browser.

To open a VT page in an external browser use the following VT manager methods:

show_url_in_browser() and show_file_in_browser().

Or you can use the VT Manager methods that create HTML code, lnk_url_in_browser() and
btn_url_in_browser(), to create hyperlinks and buttons that when clicked, will open the requested file
or URL in an external browser.

For example, to create a hyperlink that will open the Verisity web site do as follows:
//create the HTML body
var lst_html: list of string;
lst_html.add(vt.lnk_url_in_browser("www.verisity.com", "Verisity.com"));

//create the page

var my_page := new MY_PAGE vt_page;
my_page.set_html_body(lst_html);
my_page.show();

See Also
• show_url_in_browser() on page 2-110
• show_file_in_browser() on page 2-111
• lnk_url_in_browser() on page 2-74
• btn_url_in_browser() on page 2-85

2-34 Specman Beta Features

 Using the Visualization Toolkit
Using VT for Textual Search

Using the Browser Action in a VT Window

Each VT window has a predefined menu command, Web Browser, which opens an external browser
with the current page of the VT window. That feature is useful especially for printing, since VT does not
have any printing capabilities. Other uses might include displaying HTML source code, sending the VT
page as an email, or improving the visual display.

Once the VT page is opened in the external browser, it loses any connection to Specman. All the
hyperlinks and buttons that execute Specman commands are still displayed, but they do not function.

See Also
• “Predefined Menus and Menu Commands” on page 2-9

2.4.5 Using VT for Textual Search

You can use VT to perform a textual search along a specified path.

For example, to search for the string “foo” in all e files along SPECMAN_PATH do as follows:
vt.show_search("*.e", "foo")

If there are many results VT will open a new VT window and show the results in that window.

See Also
• show_search() on page 2-65

2.4.6 VT Colors and Styles

This section covers the following topics:

• “Predefined Colors” on page 2-35

• “Using Styles to Colorize Text in Specview” on page 2-36

2.4.6.1 Predefined Colors

VT defines a new enumerated type vt_color with a set of predefined colors. These colors can be used in
various VT methods.

For example, to add a box with green background color to a stripe chart do as follows,
stripe.add_box("Kind", p.kind, GREEN);

Specman Beta Features 2-35

Using the Visualization Toolkit
Using VT Manager History Methods

Each color has a special code representation that can be used either in UNIX or in HTML directly, in an
#rrggbb format.

For example, the code for the color DARK_BLUE is #000080. This alternative representation can be
used directly in HTML:
<font color="#000080">This text will be colored dark blue</font>

Or in UNIX:
xterm -bg #000080

The corresponding code color can be retrieved by VT using the method get_color_code().

See Also
• get_color_code() on page 2-116

2.4.6.2 Using Styles to Colorize Text in Specview

VT Styles is a predefined mixture of background and foreground colors. VT Styles can be used to print
colorized text in Specview.

The enumerated type vt_style provides many usable styles. To use the vt_style type for printing
colorized text, use the VT Manager method text_style().

For example:
print vt.text_style(RED, "text");

To see a list of all available styles use the VT manager method show_styles().

Note VT colors and styles are written in upper-case letters

See Also
• text_style() on page 2-119
• show_styles() on page 2-122

2.4.7 Using VT Manager History Methods

VT Manager provides several methods that allow you to query the state of opened windows and pages:

• To get a list of all opened windows use VT Manager method get_all_windows().

• To get a list of all opened pages use VT Manager method get_all_pages().

2-36 Specman Beta Features

 Using the Visualization Toolkit
Using Specman to Create HTML Documents

For example, to get the number of opened window of kind MY_WINDOW do as follows:
var all_windows : list of vt_window = vt.get_all_windows();
var my_windows: list of vt_window;

if (! all_windows.is_empty()){
my_windows = all_windows.all(it.get_kind() == MY_WINDOW);
};

See Also
• get_all_windows() on page 2-123
• get_all_pages() on page 2-123

2.5 Using Specman to Create HTML Documents

An HTML document consists of three kinds of HTML building blocks: text, hyperlinks and widgets.

VT manager provides e methods that create the HTML building blocks without the need to understand
the specific HTML language syntax.

After you create the HTML building blocks you put them together in an HTML document consisting of
windows and pages.

This section covers the following topics:

• HTML Hyperlinks, Widgets and Commands on page 2-37

• Creating HTML Building Blocks on page 2-44
• Creating an HTML Document on page 2-48

2.5.1 HTML Hyperlinks, Widgets and Commands

This section covers the following topics:

• HTML Hyperlinks and Anchors on page 2-38

• HTML Widgets on page 2-38
• HTML Spaces and Newlines on page 2-39
• Referencing HTML Widget Values on page 2-39
• Associating Specman Commands with HTML Widgets and Hyperlinks on page 2-41

Specman Beta Features 2-37

Using the Visualization Toolkit
HTML Hyperlinks, Widgets and Commands

• Showing Tooltips Over HTML Widgets and Hyperlinks on page 2-44

2.5.1.1 HTML Hyperlinks and Anchors

HTML hyperlinks are used for navigating to other HTML pages, or for executing Specman commands.
HTML anchors are used for marking locations inside a page which can then be navigated to from other
hyperlinks.

Example 1
To create a hyperlink that when clicked will open another page named “my_file2.html” in the
MY_WINDOW VT window, do as follows:
var lnk_code: string = vt.lnk_page("my_file2.html", MY_WINDOW);

Example 2
To create an anchor named: “my_anchor” do as follows:
var anchor_code: string = vt.html_anchor(“my_anchor”);
Note After you create the anchor you need to place it at the desired location in the HTML page. For
example, an anchor at the top of the document will be at the start of the HTML code.

2.5.1.2 HTML Widgets

HTML widgets are GUI components that are used to present data and for interaction with the end user.
The following types are available:

• Text widgets: Text fields and text areas

• Buttons
• Selection boxes: List boxes and combo boxes
• Toggle buttons: Check boxes and groups of check boxes (member)
• Hidden widgets
When you create an HTML widget you give it a unique name. This name might be used to access the
value of the widget.

Example
To create a text field with name “text1” do as follows:

2-38 Specman Beta Features

 Using the Visualization Toolkit
HTML Hyperlinks, Widgets and Commands

var code: string = vt.inp_textfield("text1", "", 10);

Note If VT finds more than one HTML widget with the same name, VT changes the duplicate names
and issues a warning about the changes made.

2.5.1.3 HTML Spaces and Newlines

When you create an HTML document from a list of string or by using the text expansion constructs,
spaces and new lines are ignored. To add spaces and new lines to your HTML content you can use
special VT manager fields:

• To add a space to the HTML, use:

vt.HTML_SPACE

• To add a new line to the HTML, use:

vt.HTML_NEWLINE

Example 1 Using a new line in a list of string

var lst_html: list of string;
lst_html.add(“line 1”);
lst_html.add(vt.HTML_NEWLINE);
lst_html.add(“line 2”);

Example 2 Using new lines and spaces in an inline text expansion construct
<<#:
choose a color: <(vt.HTML_NEWLINE)>
<(vt.inp_combobox(“combo1”,{“red”;”blue”;”green”;”yellow”},”red”))>
<(vt.HTML_NEWLINE)>
and press the button <(vt.HTML_SPACE)><(vt.HTML_SPACE)>
<(vt.btn_command(“out(\”%combo1\”)”, “Print Color”))>
end #;

See Also
• HTML_NEWLINE on page 2-69
• HTML_SPACE on page 2-70

2.5.1.4 Referencing HTML Widget Values

When defining Specman commands for buttons or hyperlinks, you can refer to data inside various
HTML widgets in the HTML page using the notation %<widget-name>. The widget name is the unique
name you gave to the widget when you created it.

Specman Beta Features 2-39

Using the Visualization Toolkit
HTML Hyperlinks, Widgets and Commands

When the user clicks on the button or hyperlink, VT replaces the %<widget-name> with the content of
that widget before executing the button or hyperlink command.

HTML widgets return these values (as strings):

• Text field: The text inside the text field

• Text area: The text inside the text area
• Button: The text in the button
• Combo box: The selected value (the item that is currently shown in the combo box)
• List box: The selected values in the list (the items that are highlighted)
• Check box: TRUE if checked, FALSE otherwise
• Member: All the checked items in the member group
• Hidden: The value set in the hidden widget

Example 1
In the HTML, a text field called “my_seed” is defined where the end user enters the seed, and a button
is defined that executes a test command with that seed:
html_textfield_code: string = vt.inp_textfield("my_seed", "", 10);
html_button_code: string = vt.btn_command("test -seed = %my_seed", "Test
with seed");

Example 2
An HTML combo box named “colors” shows a list of available colors. A button prints a string in the
selected color using the vt.text_style() method.
html_combobox_code: string = vt.inp_combobox("colors",
{"RED";"GREEN";"BLUE"}, "GREEN");
html_button_code: string = vt.btn_command("out(vt.text_style(%colors,
\"colored text\"))", "print text");
Note To reference the character “%” in a button or hyperlink definition, use %%.

See Also
• inp_textfield() on page 2-89
• btn_command() on page 2-82

2-40 Specman Beta Features

 Using the Visualization Toolkit
HTML Hyperlinks, Widgets and Commands

• get_widget_value() on page 2-205

• VT Colors and Styles on page 2-35

2.5.1.5 Associating Specman Commands with HTML Widgets and

Hyperlinks
You can associate a Specman command with an HTML widget or a hyperlink. This command will be
invoked when you click the widget (like clicking a button) or click the hyperlink.

The command can be any legal Specman command.

You can use the following VT manager general command methods:

• vt.btn_command(command: string, label: string): string on page 2-83

• vt.lnk_command(command: string, text: string): string on page 2-72
Or you can use a more specific VT manager method that activates a specific command (see Example 3
below).

Example 1
To invoke the Specman print command when you press an HTML button, do as follows:
var button_code: string = vt.btn_command("print 5", "press button");

Example 2
To load a VT page with content “my_file.e” file and open it in MY_WINDOW VT window, do as
follows:
var lnk_code: string = vt.lnk_command("vt.show_page(\"my_file.e\"",
MY_WINDOW));

Example 3
To open the data browser on sys do as follows:
var button_code: string = vt.btn_instance(sys, "open sys");

Using Quotes Inside HTML Commands

In your HTML command, if you have a quote inside another quote (nested quotes), you must escape the
inner quote with a backslash, “\”. Another option is to use the “#” character instead of the inner quote.

Specman Beta Features 2-41

Using the Visualization Toolkit
HTML Hyperlinks, Widgets and Commands

Example 1
var html_code: string = vt.lnk_command("print \"clicked\"", "print");

Example 2
var html_code: string = vt.btn_command("out(#do it#)", "do it");

Using VT Symbols Inside HTML Commands

You can use VT symbols inside HTML commands by using the %<symbol-name> notation. When the
command is evaluated, the %<symbol-name> is replaced with the symbol value. You can use predefined
symbols like “_page” and “_window” as well as custom symbols.

Example 1
To print the current page file name do as follows:
var command: string = "print %_page.get_file_name()";
var html_code: string = vt.lnk_command(command, "print file");

Example 2
Assume you have a symbol called “my_appl” that has a value of the struct instance sys.appl (using the
vt.instance_to_string(sys.appl) utility method). You can create a command that calls a method in the
struct instance pointed by the symbol. You can also pass parameters to this method.
var command: string = "%_my_appl.foo()";
var html_code: string = vt.lnk_command(command, "call sys.appl.foo()");

See Also
• VT Symbols on page 2-11
• vt.instance_to_string(instance: any_struct): string on page 2-116

Referencing HTML Widgets Values Inside HTML Commands

You can reference values of HTML widgets inside an HTML command, using the %<widget-name>
notation.

Example
Assume you have a text field called “text1” in which the end user writes the file that is to be loaded. To
create an HTML button that when clicked loads the file name from the text field, do as follows:

2-42 Specman Beta Features

 Using the Visualization Toolkit
HTML Hyperlinks, Widgets and Commands

var command: string = "load %text1";

var html_code: string = vt.btn_command(command, "load file");
Note You can only reference widgets that are in the current page.

See Also
• Referencing HTML Widget Values on page 2-39

Calling Struct Instance Methods from HTML Commands

You can call methods in a struct instance from your HTML command by using the
vt.instance_to_string() method.
struct my_appl {
create_html_button() is {
var command: string =
"vt.instance_to_string(me).add(5,10)";
var html_code: string = vt.btn_command(command, "call add( )");
};
add(num1: int, num2: int) is {
print (num1 + num2);
};
};

See Also
• vt.instance_to_string(instance: any_struct): string on page 2-116

Using Existing Actions to Create HTML Commands

To use an action defined in the menu bar from a button or hyperlink, use the notation !<action-title>
instead of the Specman command.

Example
To define a custom action called “Show Sys” and create a button that invokes this action, do as follows:
//define the VT window
extend MY_WINDOW vt_window {
configure is also {
//create the action
add_menu_item("data", "Show Sys", "", "show data sys", NULL, "");
};
};

Specman Beta Features 2-43

Using the Visualization Toolkit
Creating HTML Building Blocks

//create the html code

var button_code: string = vt.btn_command("!Show Sys", "show data sys");

See Also
• Adding Menus and Menu Commands on page 2-11

2.5.1.6 Showing Tooltips Over HTML Widgets and Hyperlinks

VT can show tooltips over HTML hyperlinks and widgets. To show a tooltip, add the “title” attribute to
an HTML tag that represents a hyperlink or form component (for example, a button or text field).

Examples
To add a tooltip to a hyperlink:
<a href="xxx.html" title = "tooltip over hyperlink">

To add a tooltip to a button:

<input type="button" title = "tooltip over button">

2.5.2 Creating HTML Building Blocks

VT manager has many helper methods for creation of HTML building blocks like hyperlinks, widgets
and images. These methods return strings or lists of strings that can be used to create the HTML code.

This section covers the following topics:

• Creating HTML Hyperlinks and Anchors on page 2-44

• Creating HTML Buttons on page 2-45
• Creating HTML Input Components on page 2-46
• Creating Visualization Stripe Chart Components on page 2-46
• Creating Other HTML Components on page 2-48

2.5.2.1 Creating HTML Hyperlinks and Anchors

HTML hyperlinks are used for navigating to other HTML pages, or for executing Specman commands.
HTML anchors are used for navigation inside a page.

2-44 Specman Beta Features

 Using the Visualization Toolkit
Creating HTML Building Blocks

Example 1
To create a hyperlink that when clicked will invoke the Specman print command, do as follows:
var html_code: string = vt.lnk_command("print 5", "press me");

Example 2
To create an anchor named “anc-1” and to create a hyperlink that when clicked will jump to that anchor,
do as follows:
//create the anchor
var anchor_code: string = vt.html_anchor("anc-1", "");

//create the hyperlink

var lnk_code: string = vt.lnk_anchor("anc-1", "jump to anchor", "")

The following hyperlink and anchor creation methods are available. All hyperlink creation methods start
with the prefix “lnk_”:

• lnk_command() on page 2-72

• lnk_search() on page 2-73
• lnk_url_in_browser() on page 2-74
• lnk_instance() on page 2-76
• lnk_page() on page 2-77
• lnk_page_with_title() on page 2-78
• html_anchor() on page 2-80
• lnk_anchor() on page 2-80
• lnk_file() on page 2-215
• lnk_template() on page 2-216

2.5.2.2 Creating HTML Buttons

The VT methods shown below create HTML buttons. Buttons are used for executing commands, exactly
like hyperlinks.

All the button creation methods are identical to the hyperlink creation methods, except that they have a
prefix “btn_”. The behavior is the same.

The following button creation methods are available:

Specman Beta Features 2-45

Using the Visualization Toolkit
Creating HTML Building Blocks

• btn_command() on page 2-82

• btn_search() on page 2-83
• btn_url_in_browser() on page 2-85
• btn_instance() on page 2-86
• btn_page() on page 2-87
• btn_page_with_title() on page 2-88
• btn_file() on page 2-217
• btn_template() on page 2-218

2.5.2.3 Creating HTML Input Components

The VT methods listed below create HTML input components, such as text fields, combo boxes, and
check boxes. Those components are usually used for holding end user input, and in some cases also for
executing commands.

Each input component must have a name. This name is required to allow the application developer to
reference it in order to get or set its value.

The following HTML input components creation methods are available. All input component creation
methods starts with the prefix “inp_”:

• inp_textfield() on page 2-89

• inp_textarea() on page 2-91
• inp_combobox() on page 2-92
• inp_checkbox() on page 2-94
• inp_member() on page 2-95
• inp_hidden() on page 2-97

2.5.2.4 Creating Visualization Stripe Chart Components

A stripe chart is a multi-colored stripe of boxes, each of which has a title on top and a value below it.
Boxes are placed horizontally in a stripe, and you can also specify that a gap will be left before some
specific box, or that the whole stripe will be indented.

This is very useful for showing frames, packets, cells, and so in, in a protocol. For example, each frame
could be a stripe. If a frame has sub-parts (for example, if it gets split into packets), then each packet
could be another stripe, indented under the frame’s stripe.

2-46 Specman Beta Features

 Using the Visualization Toolkit
Creating HTML Building Blocks

To display a stripe:

1. Create a new instance of the predefined vt_stripe struct:

var s: vt_stripe = new;

2. Add boxes and dividers to it:

s.add_box("Kind", p.kind, GREEN);
s.add_divider();

3. Return the list of string that depicts the stripe:

var html_list: list of string;
html_list.add(vt.html_stripe(s, 2);

4. Clear the stripe for reuse, if desired:

s.clear();

Example
<'
var strings: list of string;
var s: vt_stripe = new;
for each (p) in packets do {
s.clear();
s.add_box("Kind", p.kind, GREEN);
s.add_box("Full length", p.len, BLUE);
... -- More s.add_box() calls
strings.add(vt.html_stripe(s, 0));
-- Add a zero-indentation stripe containing all those boxes
};
-- Now use, for example, <(strings)> in your HTML file
'>

The following are the predefined methods of vt_stripe:

• add_box() on page 2-99

• add_divider() on page 2-100
• add_field_boxes() on page 2-101
• clear() on page 2-102
• html_stripe() on page 2-98

Specman Beta Features 2-47

Using the Visualization Toolkit
Creating an HTML Document

2.5.2.5 Creating Other HTML Components

You can create other HTML components such as images, tabular reports and command output. You can
also create HTML newlines, spaces and horizontal lines.

Example
To create an HTML image and add a new line after it, do as follows:
var image_code: string = vt.html_image("my_icon.gif");
var newline_code: string = vt.HTML_NEWLINE;

The following are the additional HTML component creation methods:

• HTML_NEWLINE on page 2-69

• HTML_SPACE on page 2-70
• HTML_HORIZONTAL_LINE on page 2-71
• html_image() on page 2-109
• html_command_output() on page 2-103
• html_report() on page 2-104
• html_body() on page 2-105
• html_modules() on page 2-106

2.5.3 Creating an HTML Document

After you build the HTML code, you must create an HTML document from it.

This section covers the following topics:

• Working with Lists of Strings on page 2-48

• Using Text Expansion Constructs on page 2-49
• Working with HTML Template Files on page 2-51

2.5.3.1 Working with Lists of Strings

You can create a list of strings and add to it all of the HTML building blocks, and then create an HTML
document from it by using the VT page method set_html_body() on page 2-176, or by using the VT
manager method list_to_html() on page 2-68.

2-48 Specman Beta Features

 Using the Visualization Toolkit
Creating an HTML Document

Example
create_html_list(): list of string is {
var lst_html: list of string;
lst_html.add("Enter file name:");
lst_html.add(vt.HTML_SPACE);
lst_html.add(vt.inp_textfield("text1", "", 10));
lst_html.add(vt.HTML_NEWLINE);
lst_html.add("Press button to load file:");
lst_html.add(vt.btn_command("load %text1", "load file"));
result = lst_html;
};
show_html() is {
var my_page: A_PAGE vt_page = new;
my_page.set_html_body(create_html_list());
my_page.show();
};

See Also
• Showing HTML Files on page 2-25
• list_to_html() on page 2-68

2.5.3.2 Using Text Expansion Constructs

The syntax <(e-expression)> is replaced by the (string) value of the e expression when found inside one
of the following expansion constructs:

<<#: (inline text expansion)

<< file-name (file text expansion)

These two expressions return the expanded text as a list of string.

Notes
• HTML files created with HTML editors sometimes convert “<” to “&lt;” and “>” to “&gt;”, so
Specman accepts &lt and &gt as replacements in the “<(...)>” syntax.
• In HTML, blank spaces do not matter, so it is not necessary to start your lines from column 1. In e
source code, blank spaces do matter.
• Expansion preserves indentation:
In the following code, assuming field_defs is a list, each line in the list is indented four spaces:
struct <(name)> {

Specman Beta Features 2-49

Using the Visualization Toolkit
Creating an HTML Document

<(field_defs)> -- four spaces precede <(field_defs)>

};

The Inline Text Expansion Expression, “<<#: ... end #”

The expression, <<#: expands inline text and returns it as a list of string. The syntax <(e-expression)> is
replaced by the (string) value of the e expression. You can embed VT manager HTML creation methods
in the text and it will be expanded to a list of string that will be the HTML code.

Example 1
var lines: list of string = << #:
I can count to <(2 + 2)> easily.
Look at struct <(packet.data_item_name)>.
end #;

Example 2
create_the_html_code(): list of string is {
var combo_name : string = "combo1";
var combo_items: list of string = {"red"; "green"; "blue"};
var combo_initial_value: string = "red";
var button_command: string = "print %name";
var button_text: string = "show color";

var lines: list of string = << #:

choose a color from the combo box:
<(vt.inp_combobox(combo_name, combo_items, combo_initial_value))>
press the button to see the color:
<(vt.btn_command(button_command, button_text))>
end #;

result = lines;
};

The File Text Expansion Expression: “<< file-name”

This expression, << file-name, expands the lines in the specified file as a list of string.

Example
lines.add(<< joe_template.e);

Expanding Files in the Context of a Struct Instance

The following methods expand a file in the context of a srtuct-instance:

2-50 Specman Beta Features

 Using the Visualization Toolkit
Creating an HTML Document

• expand_file() on page 2-112

• expand_file_to_file() on page 2-113
You can use these methods to create the list of string or an HTML file.

2.5.3.3 Working with HTML Template Files

An HTML template file is an HTML file with embedded special inline text expansion constructs. After
you create the template file you can use Specman to expand the template into a proper HTML file, and
then display this file in the VT window.

Example
The following is an HTML template file named “foo.html”:
To load this file, click <(vt.lnk_command("load foo.e", "Load file"))>
To get information about unit instance, click <(vt.lnk_command("apropos
\"unit instance\" ", "Unit Instance Info"))>

When you expand the template file, Specman replaces the part in “<(..)>” with the result of evaluating
vt.lnk_command(). The result is an HTML string representing a hyperlink:
To load this file, click Load file

The words “Load file” are a hyperlink that sends Specman the command “load foo.e”, when clicked.

Note You may prefer to hide this text in a method as follows:

<(sys.the_method(method-contents))>

Creating an HTML Template File

HTML template files can be created using the ordinary methods of HTML creation, including:

• Using Netscape Composer

This is the simplest way, and the most accessible. In Netscape Composer, you can use tables and
nested tables as a way of organizing information. You can also use features like color and centering
to influence the result. For example, if you color the following in green:
<font color="red"> <(vt.report(...))> </font>
Then the resulting report is also in green.
• Using an ASCII editor
HTML files are ASCII files, and can be edited using any text editor.

Specman Beta Features 2-51

Using the Visualization Toolkit
Creating an HTML Document

• Using the hls format (in emacs)

You can write the document in a format called .hls, and use an emacs elisp file to convert it to
HTML.
escape/x load-file hls.el
escape/x hls-html
The “hls-html” command takes the current buffer (with a “.hls” extension) and creates an HTML
file from it. The syntax is:
• <c> for title
• <1>, <2>, ... for chapters and sections
• <‘“…”’> for a quoted section
• “-” or “o” for a bullet
• All other characters are taken as is
• Using Microsoft tools
Microsoft Word is a suitable tool for creating HTML. Word tables become HTML tables.
Note You must tell Word to save images in a subdirectory and to only use constructs that work in
Netscape.

You can also use PowerPoint to create presentations and convert them into HTML. You can then
transfer them to UNIX and put them in your file system.
Note Do not embed “<(...)>” within PowerPoint presentations.

Expanding HTML Template Files into “Proper” HTML Files

VT manager has methods to expand the HTML template file into a proper HTML file that can be opened
in a VT window. When expanding the template file, Specman replaces all of the special expansion
constructs with the string values they return.

Use the following VT manager methods to expand template files:

• template_to_html() on page 2-66

• template_to_list() on page 2-67
• list_to_html() on page 2-68

See Also
• Showing Template Files on page 2-25

2-52 Specman Beta Features

 Using the Visualization Toolkit
Visualization Toolkit Example

2.6 Visualization Toolkit Example

The sample e code below applies some of the VT methods. Sample outputs are shown in the following
section.

The top part of the example simply defines a packet type with several fields, and produces a list of five
to ten packet instances. The remainder of the code, following the “-- Packet Viewer --” line, creates
viewer windows and HTML source, and an HTML browser page for the packet data.

Complete information about the VT methods used in this example is contained in “Visualization Toolkit
Method Reference” on page 2-58.

This section contains the following topics:

• “Sample e Code” on page 2-53

• “Packet Viewer Example Output” on page 2-56

2.6.1 Sample e Code

<'
// struct packet definition
struct vt_packet {
kind: [good, bad] ;
%addr: uint (bits : 2) ;
%len: uint (bits : 6) ;
%data: list of byte ;
%parity: byte ;
};

extend sys {
vt_packets: list of vt_packet;
keep vt_packets.size() in [5..10];
};

'>
-- Packet Viewer --
<'

extend vt_page_kind: [PACKETS_LIST_PAGE, PACKET_DETAILS_PAGE];

extend vt_window_kind: [PACKET_VIEWER_WINDOW];

extend PACKET_VIEWER_WINDOW vt_window {

configure() is also {
// geometry
set_location(250, 100);
set_size(600, 500);

Specman Beta Features 2-53

Using the Visualization Toolkit
Sample e Code

// menus
add_menu("Packets");
add_menu_item("Packets", "Show Packets", "Show all packets",
"%appl.show_packets()", NULL, "Show Packets");
add_menu_separator("Packets");
add_toolbar_separator();
add_menu_item("Packets", "Show Packet Definition",
"Show e code of packet definition",
"source packet", NULL, "Packet Def");

// symbols
set_symbol_value("appl", "sys.packet_viewer");

// title
set_title_prefix("Packet Viewer");
};
};

struct packet_viewer {

// create the HTML for the list of packets page

create_packets_list_html_body(): list of string is {

// print the header of page

result.add(appendf("List of packets contains %s packets:",
str_dec(sys.vt_packets.size())));
if (sys.vt_packets.is_empty()) {
return result;
};

// go over all packets and add a line for each one

var line: string;
var pkt_name: string;
var cmd: string;
var pkt_link: string;
for each (pkt) in sys.vt_packets {
pkt_name = vt.instance_to_string(pkt);
pkt_link = vt.lnk_instance(pkt, pkt_name);
cmd = appendf("%%appl.show_packet_details(%s)", pkt_name);
line = appendf("%s %s %s", vt.btn_command(cmd, "Show Details"),
pkt.kind.as_a(string), pkt_link);

result.add(line);
};
};

2-54 Specman Beta Features

 Using the Visualization Toolkit
Sample e Code

// create the HTML for a packet details page

create_packet_details_html_body(pkt: vt_packet): list of string is {

// print the header of page

result.add(append("Packet details: ", pkt));
result.add("");

if (pkt == NULL) {
return result;
};

// print the details

var pkt_name: string = vt.instance_to_string(pkt);
var pkt_link: string = vt.lnk_instance(pkt, pkt_name);
var data_ls: list of string = pkt.data.apply(it.as_a(string));
var data_str: string = str_join(data_ls, " ");
result.add(append("Name: ", pkt_link));
result.add(append("kind: ", pkt.kind));
result.add(append("%addr: ", pkt.addr));
result.add(append("%len: ", pkt.len));
result.add(append("%data: ", data_str));
result.add(append("%parity: ", pkt.parity));
};

// open the Show Packets page

show_packets() is {
var page:= new PACKETS_LIST_PAGE vt_page with {
.set_window_kind(PACKET_VIEWER_WINDOW);
.set_html_body(
sys.packet_viewer.create_packets_list_html_body());
.set_title(append("List Of Packets"));
};
page.show();
};

// open the Packet Details page

show_packet_details(pkt: vt_packet) is {
var page:= new PACKET_DETAILS_PAGE vt_page with {
.set_window_kind(PACKET_VIEWER_WINDOW);
.set_html_body(
sys.packet_viewer.create_packet_details_html_body(pkt));
.set_title(append("Packet Details - ", pkt));
};

page.show();
};
};

Specman Beta Features 2-55

Using the Visualization Toolkit
Packet Viewer Example Output

extend sys {
!packet_viewer;

init() is also {
packet_viewer = new packet_viewer;
};

run() is also {
packet_viewer.show_packets();
};
};
'>

2.6.2 Packet Viewer Example Output

When the vt_example.e code is run, it displays the Packet Viewer window shown in Figure 2-2.

Figure 2-2 Example Packet Viewer Window

Selecting Web Browser in the Packet Viewer window View menu opens a web browser with the contents
shown in Figure 2-3.

2-56 Specman Beta Features

 Using the Visualization Toolkit
Packet Viewer Example Output

Figure 2-3 Example HTML Output

Clicking the Show Details button to the left of the vt_packet-@0 link in the Packet Viewer window
displays the Packet Details window shown in Figure 2-4.

Figure 2-4 Example Packet Details

Clicking the blue vt_packet-@0 link in the Packet Viewer window displays the Specman Data Browser
window shown in Figure 2-5.

Specman Beta Features 2-57

Using the Visualization Toolkit
Visualization Toolkit Method Reference

Figure 2-5 Example Packet Data Browser

2.7 Visualization Toolkit Method Reference

The Visualization Toolkit (VT) provides tools for creating custom windows based on HTML files. The
predefined VT methods are described in the following sections:

• “VT Manager API Methods for Opening VT Windows” on page 2-59

• “VT Manager API Methods for Creating HTML Files” on page 2-66
• “VT Manager API Methods for Creating HTML Component Code” on page 2-69
• “HTML Helper Methods” on page 2-69
• “Hyperlink Methods” on page 2-72
• “HTML Widget Methods” on page 2-81
• “Advanced Methods” on page 2-98

2-58 Specman Beta Features

 Using the Visualization Toolkit
VT Manager API Methods for Opening VT Windows

• “VT Manager API Methods for Using External Browsers” on page 2-109
• “VT Manager API Utility Methods” on page 2-111
• “VT Window API Methods” on page 2-125
• “Window Configuration Method” on page 2-125
• “Window Graphic Properties Methods” on page 2-127
• “Methods to Set Window Attributes” on page 2-127
• “Methods to Display Window Status” on page 2-132
• “Methods to Display Window Information” on page 2-137
• “Menu Bar and Toolbar Preparation Methods” on page 2-144
• “Window Symbols Methods” on page 2-157
• “Window Closing Methods” on page 2-163
• “VT Page API Methods” on page 2-165
• “Configure Method” on page 2-166
• “Methods to Set Page Attributes” on page 2-168
• “Methods to Set Page Contents” on page 2-171
• “Methods to Display Pages” on page 2-179
• “Methods to Display Page Status” on page 2-181
• “Methods to Display Page Information” on page 2-184
• “Methods to Display the Page Contents” on page 2-195
• “Interactive Calls to Pages” on page 2-199
• “Methods to Set and Get Widget Contents” on page 2-203

2.7.1 VT Manager API Methods for Opening VT Windows

This section contains the following reference pages:

• show_page() on page 2-60

• show_page_with_title() on page 2-61
• open_page() on page 2-62

Specman Beta Features 2-59

Using the Visualization Toolkit
show_page()

• open_page_with_title() on page 2-64

• show_search() on page 2-65

2.7.2 show_page()

Purpose
Create a default VT page and display it

Category
Predefined method

Syntax
vt.show_page(file-name: string, window-kind: vt_window_kind)

Syntax example:
show_page("my_file.fil", PACKET_VIEWER_WINDOW);

Parameters

file-name The file to display in the VT window

window-kind The VT window subtype for the window

Description
This method creates an ANY_PAGE page with the specified window kind and displays the contents of
the specified file in the window.

Example
The following example locks a window of kind A_WINDOW, which prevents subsequent pages with
that window kind from opening in that window.
// Lock the window, assume it is of kind A_WINDOW
var locked:= a_window.is_locked();

2-60 Specman Beta Features

 Using the Visualization Toolkit
show_page_with_title()

if(! locked) {
a_window.set_locked(TRUE);
};

// A new page with same window kind will open in a new window
vt.show_page("my_file.e", A_WINDOW);

2.7.3 show_page_with_title()

Purpose
Create a default VT page and display it

Category
Predefined method

Syntax
vt.show_page_with_title(file-name: string, window-kind: vt_window_kind, title: string)

Syntax example:
show_page_with_title("my_file.fil", PACKET_VIEWER_WINDOW, "My packet
viewer");

Parameters

file-name The file to display in the VT window

window-kind The VT window subtype for the window

title The title for the VT window

Description
This method creates an ANY_PAGE page with the specified window kind and title, and displays the
contents of the specified file in the window.

Specman Beta Features 2-61

Using the Visualization Toolkit
open_page()

Example
extend vt_window_kind: [PACKET_WINDOW];
vt.show_page_with_title("packet.html", PACKET_WINDOW, "Show Packets");

2.7.4 open_page()

Purpose
Create a default VT page and return a pointer to it

Category
Predefined method

Syntax
vt.open_page(file-name: string, window-kind: vt_window_kind): vt_page

Syntax example:
var my_page: vt_page;
my_page = vt.open_page("my_file.fil", PACKET_VIEWER_WINDOW);

Parameters

file-name The file to display in the VT window

window-kind The VT window subtype for the window

Description
This method creates an ANY_PAGE page with the specified window kind and returns a pointer to the
page.

Example 1
Open a VT page from an HTML file:
var my_file: string = "my_file.html";
var my_page: vt_page = vt.open_page(my_file, MY_WINDOW);

2-62 Specman Beta Features

 Using the Visualization Toolkit
open_page()

Example 2
Open a VT page from an HTML template file:
var my_file: string = vt.template_to_html("my_template.html");
var my_page: vt_page = vt.open_page(my_file, MY_WINDOW);

Example 3
Open a VT page from a list of string:
var lst_html: list of string;
lst_html.add("open_page() example");
var my_file: string = vt.list_to_html(lst_html);
var my_page: vt_page = vt.open_page(my_file, MY_WINDOW);

Example 4
Open a VT page from an inline text expansion construct:
var lines: list of string = <<#:
Choose a color:
<(vt.inp_combobox("combo1", {RED;GREEN;BLUE}, "RED"))>
end #;

var my_file: string = vt.list_to_html(lst_html);

var my_page: vt_page = vt.open_page(my_file, MY_WINDOW);

See Also
• open_page_with_title() on page 2-64
• lnk_page() on page 2-77
• lnk_page_with_title() on page 2-78
• btn_page() on page 2-87
• btn_page_with_title() on page 2-88

Specman Beta Features 2-63

Using the Visualization Toolkit
open_page_with_title()

2.7.5 open_page_with_title()

Purpose
Create a default VT page and return a pointer to it

Category
Predefined method

Syntax
vt.open_page_with_title(file-name: string, window-kind: vt_window_kind, title: string): vt_page

Syntax example:
var my_page: vt_page;
my_page = open_page_with_title("my_file.fil", PACKET_VIEWER_WINDOW, "My
packet viewer");

Parameters

file-name The file to display in the VT window

window-kind The VT window subtype for the window

title The title for the VT window

Description
This method creates an ANY_PAGE page with the specified window kind and title, and returns a pointer
to the page.

Example
var lst_html: list of string;
lst_html.add(vt.inp_textfield("text1", "", 10));
var my_file: string = vt.list_to_html(lst_html);
var title: string = "open_page_with_title() example";
var my_page: vt_page = vt.open_page_with_title(my_file, MY_WINDOW, title);

2-64 Specman Beta Features

 Using the Visualization Toolkit
show_search()

See Also
• open_page() on page 2-62

2.7.6 show_search()

Purpose
Open a VT window for a search result

Category
Predefined method

Syntax
vt.show_search(file-wildcard: string, search-string: string)

Syntax example:
vt.show_search("*.e", "foo");

Parameters

file-wildcard A match string for the names of the files to be searched

search-string A Specman style match string

Description
Shows the results of a text search, possibly in a VT window.

VT searches for each occurrence of the search string in each of the matching files along
SPECMAN_PATH. Specman-style regular expressions are used in the search string, but the string does
not have to match the whole line. The search results are displayed as follows:

• If several files are found, Specman creates an HTML file with a list of clickable lines containing the
file names, and opens a VT window with that file.
• If only one occurrence is found, then Specman opens a source window and jumps to the source line
directly.

Specman Beta Features 2-65

Using the Visualization Toolkit
VT Manager API Methods for Creating HTML Files

• Otherwise, if no occurrence of the text is found, Specman issues an error message.

Example
vt.show_source("*.e", "/HTML_*/");

See Also
• lnk_search() on page 2-73
• btn_search() on page 2-83

2.7.7 VT Manager API Methods for Creating HTML Files

This section contains the following reference pages:

• template_to_html() on page 2-66

• template_to_list() on page 2-67
• list_to_html() on page 2-68

2.7.8 template_to_html()

Purpose
Convert an HTML template to an HTML file

Category
Predefined method

Syntax
vt.template_to_html(template-file): string

Syntax example:
var s: string;
s = vt.template_to_html(mytemp.html);

2-66 Specman Beta Features

 Using the Visualization Toolkit
template_to_list()

Parameters

template-file The name of the HTML template to convert

Description
Converts an HTML template into an HTML file in a temp directory and returns a string containing the
new file’s name.

Example
var p: vt_page = new;
var file_name: string = vt.template_to_html(template_file.html);
p.set_file(file_name);
p.show()

2.7.9 template_to_list()

Purpose
Convert an HTML template to HTML code

Category
Predefined method

Syntax
vt.template_to_list(template-file): list of string

Syntax example:
var sl: list of string;
sl = vt.template_to_list(mytemp.html);

Parameters

template-file The name of the HTML template to convert

Specman Beta Features 2-67

Using the Visualization Toolkit
list_to_html()

Description
Converts an HTML template into a list of string of HTML code that can be used to create an HTML file.
Returns a list of string.

Example
var p: vt_page = new;
var l: list of string = vt.template_to_list(template_file.html);
p.set_html_body(l);
p.show()

2.7.10 list_to_html()

Purpose
Convert HTML code to an HTML file

Category
Predefined method

Syntax
vt.list_to_html(lines): string

Syntax example:
var file_name: string = vt.list_to_html(l);

Parameters

lines A list of strings to convert to HTML

Description
Converts a list of string of HTML code into an HTML file in a temp directory, and returns a string
containing the new file’s name.

2-68 Specman Beta Features

 Using the Visualization Toolkit
VT Manager API Methods for Creating HTML Component Code

Example
var l: list of string;
l.add("<body bgcolor="#FDE4CC>");
l.add("<h2><font color="bllue">VT Class Browser</font></h2");
var file_name: string = vt.list_to_html(l);
var p: vt_page = new;
p.set_file(file_name);
p.show();

2.7.11 VT Manager API Methods for Creating HTML

Component Code
This section contains the following topics:

• “HTML Helper Methods” on page 2-69

• “Hyperlink Methods” on page 2-72
• “HTML Widget Methods” on page 2-81
• “Advanced Methods” on page 2-98

2.7.12 HTML Helper Methods

This section contains the following topics:

• HTML_NEWLINE on page 2-69

• HTML_SPACE on page 2-70
• HTML_HORIZONTAL_LINE on page 2-71

2.7.13 HTML_NEWLINE

Purpose
Inserts a new line in HTML

Category
Predefined field

Specman Beta Features 2-69

Using the Visualization Toolkit
HTML_SPACE

Syntax
vt.HTML_NEWLINE: string

Syntax example:
var s: string;
s = vt.HTML_NEWLINE;

Description
This method creates HTML code for a new line.

Example
var a_list: list of string;
a_list.add("To see sys:");
a_list.add(vt.HTML_NEWLINE);
a_list.add(vt.lnk_command("show data sys", "Show Sys"))
var a_page: vt_page = new;
a_page.set_html_body(a_list);
a_page.show();

2.7.14 HTML_SPACE

Purpose
Inserts a space in HTML

Category
Predefined field

Syntax
vt.HTML_SPACE: string

Syntax example:
var s: string;
s = vt.HTML_SPACE;

2-70 Specman Beta Features

 Using the Visualization Toolkit
HTML_HORIZONTAL_LINE

Description
This field creates HTML code for a blank space.

Example
var lst_html: list of string;
lst_html.add(vt.inp_textfield("text1", "", 10));
lst_html.add(vt.HTML_SPACE);
lst_html.add(vt.HTML_SPACE);
lst_html.add(vt.btn_command("load %text1", "load file"));

See Also
• HTML_HORIZONTAL_LINE on page 2-71
• HTML_NEWLINE on page 2-69

2.7.15 HTML_HORIZONTAL_LINE

Purpose
Inserts a horizontal space in HTML

Category
Predefined field

Syntax
vt.HTML_HORIZONTAL_LINE: string

Syntax example:
s: string;
s = vt.HTML_HORIZONTAL_LINE;

Description
This field creates HTML code for a horizontal space.

Specman Beta Features 2-71

Using the Visualization Toolkit
Hyperlink Methods

Example
var lst_html: list of string;
lst_html.add("List of Tests");
lst_html.add(vt.HTML_HORIZONTAL_LINE);
lst_html.add(vt.inp_textarea("textarea1", "", 10, 5));

See Also
• HTML_SPACE on page 2-70

2.7.16 Hyperlink Methods

This section contains the following reference pages:

• lnk_command() on page 2-72

• lnk_search() on page 2-73
• lnk_url_in_browser() on page 2-74
• lnk_instance() on page 2-76
• lnk_page() on page 2-77
• lnk_page_with_title() on page 2-78
• html_anchor() on page 2-80
• lnk_anchor() on page 2-80

2.7.17 lnk_command()

Purpose
Make a hyperlink that executes a Specman command

Category
Predefined method

Syntax
vt.lnk_command(command: string, text: string): string

2-72 Specman Beta Features

 Using the Visualization Toolkit
lnk_search()

Syntax example:
To see sys, click <(vt.lnk_command("show data sys", "Show Sys"))>.

Parameters

command A Specman command

text The text for the hyperlink

Description
Makes text a hyperlink that when clicked executes the specified Specman command. Returns a string.

The default text is the command name. Quotes are allowed.

The command is executed as if it was entered by the end user. Thus, commands such as reload or
restore are allowed.

Example
// Create the html body
var a_list: list of string;
a_list.add("VT example");
a_list.add(vt.lnk_command("show data sys", "Show Data"));

// Set the html body

a_page.set_html_body(a_list);

2.7.18 lnk_search()

Purpose
Make a hyperlink that performs a text search

Category
Predefined method

Specman Beta Features 2-73

Using the Visualization Toolkit
lnk_url_in_browser()

Syntax
vt.lnk_search(file-wildcard: string, search-string: string, text: string): string

Syntax example:
To see all matches of 'foo', click <(vt.lnk_search("*.e", "foo", "here"))>.

Parameters

file-wildcard The file to search. Use a wild card to search in multiple files.

search-string The text to search for.

text The text for the hyperlink.

Description
Makes text a hyperlink that when clicked performs a text search for the specified search string on the
specified files. Returns a string.

This is implemented by nesting show_search() on page 2-65 in lnk_command() on page 2-72.

Example
var my_file: string = "my_file.e";
var text: string = append("open ", my_file);
var html_code: string = vt.lnk_page(my_file, MY_WINDOW, text);

var lst_html: list of string;

lst_html.add(html_code);

See Also
• show_search() on page 2-65

2.7.19 lnk_url_in_browser()

Purpose
Make a hyperlink that shows a URL in an external browser

2-74 Specman Beta Features

 Using the Visualization Toolkit
lnk_url_in_browser()

Category
Predefined method

Syntax
vt.lnk_url_in_browser(url: string, text: string): string

Syntax example:
You may want to visit
<(vt.lnk_url_in_browser("http://www.VerificationVault.com", "The
Vault"))>

Parameters

url The URL to show

text The text for the hyperlink

Description
Makes text a hyperlink that when clicked shows the specified URL in an external Web browser. Returns
a string.

This method is implemented by nesting show_url_in_browser() on page 2-110 in lnk_command() on

page 2-72.

Example
// Create the HTML body
var lst_html: list of string;
lst_html.add(vt.lnk_url_in_browser("www.verisity.com", "Verisity.com"));

// Create the page

var my_page := new MY_PAGE vt_page;
my_page.set_html_body(lst_html);
my_page.show();

Specman Beta Features 2-75

Using the Visualization Toolkit
lnk_instance()

2.7.20 lnk_instance()

Purpose
Make a hyperlink that opens the Data Browser for a struct or unit instance

Category
Predefined method

Syntax
vt.lnk_instance(instance: any_struct, title: string): string

Syntax example:
To browse current packet click <(vt.lnk_instance(curr_packet, "Current
Packet"))>

Parameters

instance The struct or unit instance to show

title The title for the hyperlink

Description
Makes title a hyperlink that when clicked opens the Data Browser on the specified instance. The return
type is string.

If no title is specified, then the string returned by vt.instance_to_string(instance) is used, for example,
"packet-@12". See instance_to_string() on page 2-116.

This is useful especially in vt.report() or vt.html_stripe(), where you want one of the columns to be a
hyperlink to the corresponding struct.

This is implemented by nesting the show data command in lnk_command() on page 2-72.

Example
struct vt_packet {
%addr: uint (bits: 2);

2-76 Specman Beta Features

 Using the Visualization Toolkit
lnk_page()

%data: list of byte;

};
struct packet_viewer {
create_packet_details_html_body(pkt: vt_packet): list of string is {
// Print the header of the page
result.add(append("Packet details: ", pkt));
result.add("");
if (pkt == NULL) {
return result;
};

// Print the details

var pkt_name: string = vt.instance_to_string(pkt);
var pkt_link: string = vt.lnk_instance(pkt, pkt_name);

result.add(append("Name: ", pkt_link));

result.add(append("%addr ", pkt.addr));
};
};

2.7.21 lnk_page()

Purpose
Create HTML code for a link to a VT page

Category
Predefined method

Syntax
vt.lnk_page(file-name: string, kind: vt_window_kind, text: string): string

Syntax example:
var s: string;
s = vt.lnk_page("my_file", A_WINDOW, "To my page");

Specman Beta Features 2-77

Using the Visualization Toolkit
lnk_page_with_title()

Parameters

file-name The file to display in the VT page

kind The VT window kind to which the link applies

text Text for the link

Description
This method returns HTML code representing a hyperlink which, when clicked, displays a VT page
using show_page().

Example
Add a VT page hyperlink to a list of string:
var my_file: string = "my_file.e";
var text: string = append("open ", my_file);
var html_code: string = vt.lnk_page(my_file, MY_WINDOW, text);

var lst_html: list of string;

lst_html.add(html_code);

See Also
• open_page() on page 2-62

2.7.22 lnk_page_with_title()

Purpose
Create HTML code for a link to a VT page

Category
Predefined method

Syntax
vt.lnk_page_with_title(file-name: string, kind: vt_window_kind, title: string, text: string): string

2-78 Specman Beta Features

 Using the Visualization Toolkit
lnk_page_with_title()

Syntax example:
var s: string;
s = vt.lnk_page_with_title("my_file", A_WINDOW, "My Page", "To my page");

Parameters

file-name The file to display in the VT page

kind The VT window kind to which the link applies

title The title for the page

text Text for the link

Description
This method returns HTML code representing a hyperlink which, when clicked, displays a VT page
using show_page(). The page has the title specified with title.

Example
Embed a VT page hyperlink in an inline text expansion construct:
var my_file: string = "my_file.e";
var title: string = "lnk_page_with_title() example";
var text: string = "show file"
var html_code: string = vt.lnk_page_with_title(my_file, MY_WINDOW, title,
text);

var lines: list of string = <<#:

To view the file <(my_file)>
<(html_code)>
end #;

See Also
• open_page_with_title() on page 2-64

Specman Beta Features 2-79

Using the Visualization Toolkit
html_anchor()

2.7.23 html_anchor()

Purpose
Create an anchor that can be referenced by other links

Category
Predefined method

Syntax
vt.html_anchor(name: string, text: string): string

Syntax example:
var s: string;
s = vt.html_anchor("terminology", "Terminology");

Parameters

name The name for the anchor

text The text for the anchor

Description
Create an anchor with the specified text that can be referenced from other links by the specified name.
Returns a string.

Example
anchor_code = vt.html_anchor("terminology", "Terminology");

2.7.24 lnk_anchor()

Purpose
Make a hyperlink that jumps to an anchor when clicked

2-80 Specman Beta Features

 Using the Visualization Toolkit
HTML Widget Methods

Category
Predefined method

Syntax
vt.lnk_anchor(anchor_name: string, text: string, tooltip: string): string

Syntax example:
var s: string;
s = vt.lnk_anchor("terminology", "Jump to Terminology", "Jump to anchor");

Parameters

name The name of the anchor to jump to

text The text for the hyperlink

tooltip The tooltip over the hyperlink

Description
Create a hyperlink that jumps to an anchor when clicked.

Example
var a_page: A_PAGE vt_page = new;
var lst_html: list of string;
var anchor_code: string = vt.html_anchor("top", "<< top anchor >>");
var lnk_anchor_code: string = vt.lnk_anchor("top", "jump to top","");
lst_html.add(anchor_code);
for i from 1 to 20 {
lst_html.add(vt.HTML_NEWLINE);
};
lst_html.add(lnk_anchor_code);
a_page.set_html_body(lst_html);
a_page.show();

2.7.25 HTML Widget Methods

This section contains the following reference pages:

Specman Beta Features 2-81

Using the Visualization Toolkit
btn_command()

Button Methods
• btn_command() on page 2-82
• btn_search() on page 2-83
• btn_url_in_browser() on page 2-85
• btn_instance() on page 2-86
• btn_page() on page 2-87
• btn_page_with_title() on page 2-88

Text Methods
• inp_textfield() on page 2-89
• inp_textarea() on page 2-91

Combo Box Method

• inp_combobox() on page 2-92

List Box Method

• inp_listbox() on page 2-93

Check Box Methods

• inp_checkbox() on page 2-94
• inp_member() on page 2-95

Hidden Control Method

• inp_hidden() on page 2-97

2.7.26 btn_command()

Purpose
Make a button

2-82 Specman Beta Features

 Using the Visualization Toolkit
btn_search()

Category
Predefined method

Syntax
vt.btn_command(command: string, label: string): string

Syntax example:
html_code = vt.btn_command("sys.do_tests(%tests)", "Do those commands")

Parameters

command The command to execute. Quotes are allowed.

label The label for the button.

Description
Makes text a button which, when clicked, executes the specified Specman command. The default text is
the command name. The return type is string.

Example
create_html_body(): list of string is {
var lines: list of string = <<#:
<center><h3>Simple VT Page</h3></center>
<(vt.btn_command("print %_page", "print page"))>
end #;
result = lines;
};

2.7.27 btn_search()

Purpose
Make a button to perform a text search

Specman Beta Features 2-83

Using the Visualization Toolkit
btn_search()

Category
Predefined method

Syntax
vt.btn_search(files: string, search-string: string, text: string): string

Syntax example:
To see all matches of 'foo', click <(vt.btn_search("*.e", "foo", "here"))>.

Parameters

file-wildcard The files to search. Use a wild card to search in multiple files.

search-string The text to search for.

text The text for the button.

Description
Makes a hyperlink to a button to perform a text search. Returns a string.

Example
//from my_template.html

To search for occurrences of word "is also" in e files

along SPECMAN_PATH do:

<(vt.btn_search("*.e", "is also", "search.."))>

See Also
• lnk_search() on page 2-73

2-84 Specman Beta Features

 Using the Visualization Toolkit
btn_url_in_browser()

2.7.28 btn_url_in_browser()

Purpose
Make a button to show a URL in a browser

Category
Predefined method

Syntax
vt.btn_url_in_browser(url: string, text: string): string

Syntax example:
You may want to visit
<(vt.btn_url_in_browser("http://www.VerificationVault.com",
"The Vault"))>

Parameters

url The URL to open

text The text for the button

Description
Makes a hyperlink to a button to open a URL in an external browser. Returns a string.

Example
var my_url: string = "www.verisity.com";
var html_code: string = vt.btn_url_in_browser(my_url, "verisity web site");

var lst_html: list of string;

lst_html.add(html_code);

Specman Beta Features 2-85

Using the Visualization Toolkit
btn_instance()

See Also
• show_url_in_browser() on page 2-110
• lnk_url_in_browser() on page 2-74

2.7.29 btn_instance()

Purpose
Make a button to open an instance in the Data Browser

Category
Predefined method

Syntax
vt.btn_instance(instance: any_struct, title: string): string

Syntax example:
To browse current packet click <(vt.btn_instance(curr_packet,
"Current Packet"))>

Parameters

instance The struct or unit instance to display

title The title for the button

Description
Makes a hyperlink to a button to display a struct or unit instance in the Data Browser. Returns a string.

Example
Add a button instance widget to a list of string:
var html_code: string = vt.btn_instance(sys, "show sys");

var lst_html: list of string;

2-86 Specman Beta Features

 Using the Visualization Toolkit
btn_page()

lst_html.add("To show sys:");

lst_html.add(vt.HTML_NEWLINE);
lst_html.add(html_code);

See Also
• lnk_instance() on page 2-76

2.7.30 btn_page()

Purpose
Make a button that opens a VT page

Category
Predefined method

Syntax
vt.btn_page(file-name: string, kind: vt_window_kind, text: string): string

Syntax example:
var s: string;
s = vt.btn_page("my_file", A_WINDOW, "To my page");

Parameters

file-name The file to display in the VT page

kind The VT window kind to which the link applies

text Text for the link

Description
This method returns HTML code representing a button, which when clicked displays a VT page using
show_page() on page 2-60.

Specman Beta Features 2-87

Using the Visualization Toolkit
btn_page_with_title()

Example
Embed a button instance widget in an HTML template file:
//from my_template.html

To open file press button:

<(vt.HTML_NEWLINE)>
<(vt.btn_page("my_file.e", MY_WINDOW, "open file"))>

See Also
• lnk_page() on page 2-77

2.7.31 btn_page_with_title()

Purpose
Create HTML code for a button to a VT page

Category
Predefined method

Syntax
vt.btn_page_with_title(file-name: string, kind: vt_window_kind, title: string, text: string): string

Syntax example:
var s: string;
s = vt.btn_page_with_title("my_file", A_WINDOW, "My Page", "To my page");

Parameters

file-name The file to display in the VT page

kind The VT window kind to which the link applies

title The title for the page

2-88 Specman Beta Features

 Using the Visualization Toolkit
inp_textfield()

text Text for the link

Description
This method returns HTML code representing a button, which when clicked displays a VT page using
show_page() on page 2-60. The page has the title specified with title.

Example
Embed a button page widget in an inline text expansion construct:
var my_file: string = "my_file.html";
var title: string = "btn_page() Example";
var text: string = "show HTML file"
var html_code: string = vt.btn_page_with_title(my_file, MY_WINDOW, title,
text);

var lines: list of string = <<#:

To view the file <(my_file)> in a new window with title <(title)>
press the button:
<(html_code)>
end #;

See Also
• lnk_page_with_title() on page 2-78

2.7.32 inp_textfield()

Purpose
Create a single-line text box

Category
Predefined method

Syntax
vt.inp_textfield(name: string, initial-value: string, len: int): string

Specman Beta Features 2-89

Using the Visualization Toolkit
inp_textfield()

Syntax example:
var s: string;
s = vt.inp_textfield("Packet kind", "unknown", 10);

Parameters

name The name for the text box.

initial-value The initial content of the text box.

len The number of characters the text box may hold.

Description
Creates a single-line text box with the specified initial value, name, and length (in characters). If length
is -1, then the length is determined by the length of the initial value, but with minimum of five
characters. Returns a string.

Example
The following example changes the values of several HTML widgets inside the current page.
var a_page: A_PAGE vt_page = new

// Create the HTML widgets

var lst_html: list of string;
lst_html.add(vt.inp_textfield("text-1", "", 20))
lst_html.add(vt.inp_combobox("combo-1", {"green"; "red"; "blue"}, "red"));
lst_html.add(vt.inp_checkbox("check-1", FALSE);

// Open the page

a_page.set_html_body(lst_html);
a_page.show();

// Set the value of the text field named "text-1" to be "packet-@1"

a_page.set_widget_value("text-1", "packet-@1");

// Set the selected value of the combo box named "combo-1" to be "green”
a_page.set_widget_value("combo-1", "green");

// Set the value of the check box named "check-1" to be TRUE (selected)
a_page.set_widget_value("check-1", TRUE);

2-90 Specman Beta Features

 Using the Visualization Toolkit
inp_textarea()

2.7.33 inp_textarea()

Purpose
Create a multi-line text box

Category
Predefined method

Syntax
vt.inp_textarea(name: string, initial-value: string, len: int, lines: int): string

Syntax example:
var s: string;
s = vt.inp_textarea("Packet data","unknown",8, 4);

Parameters

name The name for the text box.

initial-value The initial content of the text box.

len The length of the lines in the text box.

lines The number of lines in the text box.

Description
Creates a multi-line text box with the specified initial value, name, length (in characters), and number of
lines. If length is -1, then the length is determined by the length of the initial value, but with minimum
of five characters. If lines is -1, then it will have three lines. Returns a string.

Example
Embed a text area widget in an inline text expansion construct:

Specman Beta Features 2-91

Using the Visualization Toolkit
inp_combobox()

var lines: list of string = <<#:

See the description in the text area:
<(vt.inp_textarea("textarea1","inp_textarea() example",10,5))>
end #;

2.7.34 inp_combobox()

Purpose
Create a combo box

Category
Predefined method

Syntax
vt.inp_combobox(name: string, choices: list of string, initial-value: string): list of string

Syntax example:
var sl: list of string;
sl = vt.inp_combobox("which", {"sys"; "sys.packet"; "sys.cell"}, "sys");

Parameters

name The name of the combo box.

choices The list of choices to be provided in the combo box.

initial-value The initial (default) choice.

Description
Creates a combo box (also called a select widget) with the specified choices. The name (for %<name>
replacement) is the specified name. The initial chosen value must be one of the choices. Returns a string.

Note If the initial value is not specified, choices[0] is used.

2-92 Specman Beta Features

 Using the Visualization Toolkit
inp_listbox()

Example
Select a struct:
<(vt.inp_combobox("which", {"sys"; "sys.packet"; "sys.cell"}, "sys"))>
Then click here: <(vt.btn_command("print %which", "print it"))>.

2.7.35 inp_listbox()

Purpose
Create a list box

Category
Predefined method

Syntax
vt.inp_listbox(name: string, command: string, values: list of string, initial_value: string, visible_rows:
int, width: int, multiple_selection: bool, tooltip: string): string

Syntax example:
var s: string;
s = vt.inp_listbox("list1", "print 5", {"A";"B";"C"}, "C", 8, 10, TRUE,
"");

Parameters

name The name of the list

command The command to be done upon selection change

values The list of choices to be provided in the list box

initial_value The initial (default) choice

visible_rows The height of the list box

width The width of the list box (in characters)

Specman Beta Features 2-93

Using the Visualization Toolkit
inp_checkbox()

multiple_ Whether the list allows single selection or multiple selections

selection

tooltip The tooltip to be shown over the list

Description
Create a list box (also called a select widget) with the specified choices (values). The name can be used
to reference the widget value, by using %<name> notation. A warning is issued if the initial value is not
in the list of choices. If you do not want an initial selection, use NULL. By default the list will have eight
rows, be as wide as the widest text, and allow single selection only.

Example
var a_page: A_PAGE vt_page = new;
var lst_html: list of string;
var anchor_code: string = vt.html_anchor("top", "<< top anchor >>");
var lnk_anchor_code: string = vt.lnk_anchor("top", "jump to top","");
lst_html.add(anchor_code);
for i from 1 to 20 {
lst_html.add(vt.HTML_NEWLINE);
};
lst_html.add(lnk_anchor_code);
a_page.set_html_body(lst_html);
a_page.show();

2.7.36 inp_checkbox()

Purpose
Create a check box

Category
Predefined method

Syntax
vt.inp_checkbox(name: string, initially-selected: bool): string

Syntax example:

2-94 Specman Beta Features

 Using the Visualization Toolkit
inp_member()

var s: string;
s = vt.inp_checkbox("with_onions", FALSE);

Parameters

name The name of the check box.

initially-selected The initial (default) selection.

Description
Creates a check box whose name (for %<name> replacement) is the specified name. If initially-selected
is TRUE, the check box is initially checked; otherwise it is unchecked. Returns a string.

The %<name> value contains either the string TRUE or the string FALSE.

Example
<(vt.inp_checkbox("with_onions", FALSE))> I want it with onions.
To order, click here:
<(vt.btn_command("sys.send_pizza(%with_onions)", "Send it"))>

2.7.37 inp_member()

Purpose
Create a group of check boxes

Category
Predefined method

Syntax
vt.inp_member(name: string, value: string, initially-selected: bool): string

Syntax example:
var s: string;
s = vt.inp_member("toppings", "olives", FALSE;

Specman Beta Features 2-95

Using the Visualization Toolkit
inp_member()

Parameters

name The name of the group of check boxes.

value The name or value of a choice to be presented in the check box.

initially-selected The initial setting of the choice.

Description
When you call vt.inp_member() several times with the same name, you create a multiple-selection
group. Each call creates a check box, and using the %<name> notation returns a list of all the value
strings that were checked. The initially-selected boolean determines if this one is preselected. If no item
is selected, the %<name> value returns the empty list ({}). Returns a string.

Example 1
<(vt.inp_member("toppings", "onions", FALSE))> Add onions
<(vt.inp_member("toppings", "olives", FALSE))> Add olives
<(vt.inp_member("toppings", "anchovies", FALSE))> Add anchovies
To order, click here:
<(vt.btn_command("sys.send_pizza(%toppings)", "Send it"))>

This assumes that the following definition has already been loaded:
type toppings_type: [onions, olives, anchovies];
extend sys {
send_pizza(toppings: list of toppings_kind) is {...};
};

Example 2
Another typical usage is creating a table. Assume that there is a list of tests that were run previously, and
you want to display them so that the end user can select which ones to rerun. A piece of the code might
look like this:
var l: list of string;
for each in my_tests do {
var s: string = append(vt.inp_member("tests", dec(index), FALSE),
.name);
l.add(s);
};

2-96 Specman Beta Features

 Using the Visualization Toolkit
inp_hidden()

l.add(<<#:
<(vt.btn_command("sys.do_tests(%tests)", "Do those commands"))>
end #); -- sys.do_tests() is called with the list of test indices

2.7.38 inp_hidden()

Purpose
Create a hidden control

Category
Predefined method

Syntax
vt.inp_hidden(name: string, value: string): string

Syntax example:
var s: string;
s = vt.inp_hidden("cur_dir", get_the_dir());

Parameters

name The name for the hidden control.

value The value of the hidden control.

Description
Creates a hidden control to contain the specified value and make it accessible via the %<name>
notation. Returns a string.

Example
<(vt.inp_hidden("cur_dir", get_the_dir()))>

To run it:

Specman Beta Features 2-97

Using the Visualization Toolkit
Advanced Methods

<(vt.btn_command("sys.foo(\"%cur_dir\", %xx, \"%yy\")", "run it"))>

2.7.39 Advanced Methods

This section contains the following reference pages:

• html_stripe() on page 2-98

• add_box() on page 2-99
• add_divider() on page 2-100
• add_field_boxes() on page 2-101
• clear() on page 2-102
• html_command_output() on page 2-103
• html_report() on page 2-104
• html_body() on page 2-105
• html_modules() on page 2-106
• inp_file() on page 2-107
• html_image() on page 2-109

2.7.40 html_stripe()

Purpose
Create HTML code to show a stripe

Category
Predefined method

Syntax
vt.html_stripe(stripe: vt_stripe, indent: int): list of string

Syntax example:
var sl: list of string;
sl = vt.html_stripe(ht_st, 18);

2-98 Specman Beta Features

 Using the Visualization Toolkit
add_box()

Parameters

stripe The name of the vt_stripe instance.

indent The number of pixels to indent the stripe from the left.

Description
Creates the required HTML code for showing a stripe. Returns a list of string.

This method returns HTML code (represented as a list of string) that shows a stripe containing all the
boxes defined in it. indent specifies at what level this stripe resides (0 or more). The whole stripe is
indented to the right accordingly.

Example
var strings: list of string;
var s: vt_stripe = new;
for each (p) in packets do {
s.clear();
s.add_box("Kind", p.kind, GREEN);
s.add_box("Full length", p.len, BLUE);
// Add a zero-indentation stripe containing all those boxes
strings.add(html_stripe(s, 0));
};

2.7.41 add_box()

Purpose
Define a box for the current stripe

Category
Predefined method

Syntax
vt-stripe.add_box(title: string, value: expression, color: vt_color)

Specman Beta Features 2-99

Using the Visualization Toolkit
add_divider()

Syntax example:
var stripe: vt_stripe;
stripe.add_box("Packet kind", kind, GREEN);

Parameters

title The title for the box.

value An expression whose value is assigned to the box.

color The color for the box.

Description
Defines a new box for the current stripe with the specified title, value, and color.

Notes
• color can be any color in type vt_color (see get_color_code() on page 2-116). The following colors
serve as good background colors: WHITE, PINK, ORANGE, YELLOW, GREEN, BLUE, PURPLE,
GRAY.
• title and value can be of any type and are converted to string (or list of string). If you want to force
a particular radix, use, for example, stripe.add_box("CRC", hex(p.crc), GRAY);
• vt_stripe.add_box() does not return a value. It adds information to the specific vt_stripe struct, to
be uesd by html_stripe().

Example
var stripe: vt_stripe;
stripe.add_box("Packet kind", kind, GREEN);

2.7.42 add_divider()

Purpose
Add a divider between boxes

2-100 Specman Beta Features

 Using the Visualization Toolkit
add_field_boxes()

Category
Predefined method

Syntax
vt-stripe.add_divider()

Syntax example:
var stripe: vt_stripe;
stripe.add_divider();

Description
Adds a divider between boxes.

Example
var stripe: vt_stripe;
stripe.add_box("Packet kind", kind, GREEN);
stripe.add_divider();

2.7.43 add_field_boxes()

Purpose
Create a row of boxes

Category
Predefined method

Syntax
vt-stripe.add_field_boxes(struct-instance: any_struct, fields-wildcard: string, physical-only: bool,
color: vt_color)

Syntax example:
var stripe: vt_stripe;

Specman Beta Features 2-101

Using the Visualization Toolkit
clear()

stripe.add_field_boxes(packet, kind, TRUE, GREEN);

Parameters

struct-instance The name of the struct or unit instance for which the fields will be shown.

field-wildcard The fields to be shown.

physical-only Enter TRUE to show physical fields only, or enter FALSE to show both
physical fields and virtual fields.

color The color for the field boxes.

Description
Creates a contiguous list of boxes, from left to right, one for each matching field in the struct instance.
Each box has the name of the field as the title and the value of the field as value. Matching means that
the full field name matches field-wildcard, and that the field is physical (if physical-only is TRUE). Note
that fields under a when subtype are not displayed if that when subtype is not open, even if the field
names match the field wild card. The created cells get the specified color as background. Return type is
list of string.

Note Currently, physical-only must be set to TRUE. When it is FALSE, this should show all the scalar
fields in the struct.

Example
var stripe: vt_stripe;
stripe.add_box("Packet", p, GREEN);
stripe.add_field_boxes(packet, data*, TRUE, RED);

2.7.44 clear()

Purpose
Clear a vt_stripe

Category
Predefined method

2-102 Specman Beta Features

 Using the Visualization Toolkit
html_command_output()

Syntax
vt-stripe.clear()

Syntax example:
var stripe: vt_stripe;
stripe.clear();

Description
Clears the content of the vt_stripe. This is useful in case you want to reuse the same vt_stripe several
times.

Example
var stripe: vt_stripe;
for each (p) in packets do {
stripe.clear();
stripe.add_box("Kind", p.kind, GREEN);
strings.add(html_stripe(stripe, 0));
};

2.7.45 html_command_output()

Purpose
Insert a text area in an HTML file to contain the output of a command

Category
Predefined method

Syntax
vt.html_command_output(command: string, lines: int, chars: int): list of string

Syntax example:
var sl: list of string;
sl = vt.html_command_output("show break", 3, 20);

Specman Beta Features 2-103

Using the Visualization Toolkit
html_report()

Parameters

command The command whose output is to be displayed.

lines The number of lines for the text area.

chars The width in characters of the text area.

Description
Inserts a text area of the specified size (lines times chars) containing the output of the specified
command. Return type is list of string.

Example
<(vt.html_command_output("show break", 3, 20))>

2.7.46 html_report()

Purpose
Create a report in tabular form

Category
Predefined method

Syntax
vt.html_report(list-expression: exp, list-of-titles: list of string, expression: list of exp, ...): list of string

Syntax example:
var sl: list of string;
sl = vt.html_report(connections, {}, .type, .in_vci, .in_vpi, .port);

Parameters

list-expression An expression for a list to be displayed as a table.

2-104 Specman Beta Features

 Using the Visualization Toolkit
html_body()

list-of-titles A list of headings for the table.

expression A list of expressions whose values are to be displayed.

Description
Creates a tabular report. This is a macro and is similar to the report action in Specman. You pass it a list
expression, a titles list and then expressions (normally starting with “.”) relative to the current item, and
it creates an HTML table. Return type is list of string.

Example 1
<(vt.html_report(connections, {}, .type, .in_vci, .in_vpi, .port))>

This draws a table with four columns. The “connections” argument is interpreted in the context of sys
(that is, sys.connections).

If the list-of-titles parameter is an empty list (“{}”), as in the example above, then the titles for all
columns are the actual expressions (with the initial “.”, if any, removed). If it is not an empty list, then it
should be a list of n literal strings, where n is the number of expressions.

Example 2
<(vt.html_report(cells, {"Kind"; "Size in bits"}, .kind, .get_size()))>

This draws a two-column table with Kind and Size in bits as the headers. All cells in the first column are
red.

2.7.47 html_body()

Purpose
Embed an HTML file in a larger file

Category
Predefined method

Specman Beta Features 2-105

Using the Visualization Toolkit
html_modules()

Syntax
vt.html_body(html-file): string

Syntax example:
var s: string;
s = vt.html_body("my_switch.html");

Parameters

html-file The name of the HTML file to embed in the current file.

Description
Embeds an HTML file in a larger file. Embedding works best inside a table entry, for example, when
you want to show a system that is itself composed of sub-systems, for each of which you already have a
visualizer. Return type is string.

Example
<(vt.html_body("my_switch.html"))>

2.7.48 html_modules()

Purpose
Create a list of e modules as hyperlinks

Category
Predefined method

Syntax
vt.html_modules(name-wildcard: string): list of string

Syntax example:
var sl: list of string;

2-106 Specman Beta Features

 Using the Visualization Toolkit
inp_file()

sl = vt.html_modules("packet*");

Parameters

name-wildcard The wildcard name for the modules to be hyperlinked.

Description
Creates a list of e modules as hyperlinks, returning the file names for all end-user source modules
matching name-wildcard. Each acts as a hyperlink to the corresponding file. Return type is list of string.

Example
Show all modules in a VT page:
var my_page: MY_PAGE vt_page = new;
my_page.set_html_bosy(vt.html_modules("*"));
my_page.show();

2.7.49 inp_file()

Purpose
Create a file control

Category
Predefined method

Syntax
vt.inp_file(file-name: string, value: string, length: int, extension: string, direction: string): string

Syntax example:
var s: string;
s = vt.inp_file("xxx", "foo.e", 25, "*.e", "/proj/specman_elite");

Specman Beta Features 2-107

Using the Visualization Toolkit
inp_file()

Parameters

file-name The label for a text field into which the value and length are written.

value The name of a file that will be written into the text field.

length The length in characters of the text field.

extension The extension to be used with the file-name.

directory The directory in which the file specified by file-name resides.

Description
This method creates a file control with an application similar to the HTML tag <input type=“file”>. The
file control has a text field and a browse button. Clicking the button opens a file chooser dialog that
enables you to select a file, and the result is put into a text field.

Example 1
The following example results in a text field named “xxx”, containing “foo.e”, 25 characters long, with
extension “.e” and in the directory /proj/specman_elite.
var s: string;
s = vt.inp_file("xxx", "foo.e", 25, ".e", "/proj/specman_elite");

Example 2
Add a file chooser control to a list of string:
var html_code: string = vt.inp_file("fc1", "", 20, "*.e",
"/proj/specman_elite");

var lst_html: list of string;

lst_html.add("Choose file:");
lst_html.add(vt.HTML_NEWLINE);
lst_html.add(html_code);

2-108 Specman Beta Features

 Using the Visualization Toolkit
html_image()

2.7.50 html_image()

Purpose
Display an image in an HTML file

Category
Predefined method

Syntax
vt.html_image(image-file: string): string

Syntax example:
var s: string;
s = vt.html_image("logo.jpg");

Parameters

image-file The name of the image file to display.

Description
Displays the requested image at that location in the HTML file. The method searches along the
SPECMAN_PATH for the image-file. Return type is string.

Example
Schematically, a router looks like this: <br>
<(vt.html_image("eb_router/router.gif"))>

2.7.51 VT Manager API Methods for Using External Browsers

This section contains the following reference pages:

• show_url_in_browser() on page 2-110

• show_file_in_browser() on page 2-111

Specman Beta Features 2-109

Using the Visualization Toolkit
show_url_in_browser()

2.7.52 show_url_in_browser()

Purpose
Open a URL in an external browser

Category
Predefined method

Syntax
vt.show_url_in_browser(url: string)

Syntax example:
vt.show_url_in_browser("http://www.verisity.com");

Parameters

url The URL to open.

Description
Opens a URL in an external Web browser. The URL can be of any protocol, such as file:/ or http:/.

The environment variable SPECMAN_WEB_BROWSER specifies which browser will be used. The
default is Netscape.

If you want to cause a new browser window to be opened, rather than reusing an already opened browser
window, set the environment variable SN_NEW_HELP_WIN to TRUE.

You can use lnk_url_in_browser() on page 2-74 or btn_url_in_browser() on page 2-85 to create a
shortcut to open a browser.

Example
Using the show_url_in_browser() method in a menu command:
extend MY_WINDOW vt_window {
configure() is also {
add_menu_item("Web","Sites","Verisity web site",

2-110 Specman Beta Features

 Using the Visualization Toolkit
show_file_in_browser()

"vt.btn_url_in_browser(\"www.verisity.com\")",
"icon_verisity.gif", "Verisity");
};
};

2.7.53 show_file_in_browser()

Purpose
Open a file in an external browser

Category
Predefined method

Syntax
vt.show_file_in_browser(file-name: string)

Syntax example:
vt.show_file_in_browser("top/verif.html");

Parameters

file-name The name of the file to open.

Description
Opens a file in an external Web browser. The file name can be package relative. It is searched for along
the SPECMAN_PATH.

See Also
• show_url_in_browser() on page 2-110

2.7.54 VT Manager API Utility Methods

The following predefined methods of the VT Manager API are described in this section:

Specman Beta Features 2-111

Using the Visualization Toolkit
expand_file()

• expand_file() on page 2-112

• expand_file_to_file() on page 2-113
• get_absolute_name() on page 2-115
• instance_to_string() on page 2-116
• get_color_code() on page 2-116
• text_style() on page 2-119
• show_styles() on page 2-122
• get_all_windows() on page 2-123
• get_all_pages() on page 2-123

2.7.55 expand_file()

Purpose
Write the contents of a text file into a struct context

Category
Predefined method

Syntax
vt.expand_file(file-name: string, instance: struct_instance): list of string

Syntax example:
var l: list of string;
l = vt.expand_file("header.txt", details);

Parameters

file-name The name of the file whose contents are to be expanded in the struct
instance.

instance The name of the struct instance into which the file contents are to be
expanded.

2-112 Specman Beta Features

 Using the Visualization Toolkit
expand_file_to_file()

Description
This method makes the contents of a text file look like a struct instance. The fields of the struct instance
are expanded into corresponding fields in the file. Return type is a list of string.

Example
Suppose we have a file named header.txt, which contains the following:
// File: <(file_name)>
// Author: <(author)>
// Description: <(description)>

Also, suppose we have a struct named file_details, defined as follows:

struct file_details {
file_name: string;
author: string;
description: string;
};

Then, the following code creates a header by putting the contents of header.txt into the fields of an
instance of the file_details struct named details:
mk_header() is {
var details := new file_details with {
.file_name = "myfile.e";
.author = "eMike";
.description = "This is a small e file";
};
var header: list of string = vt.expand_file("header.txt", details);
};

2.7.56 expand_file_to_file()

Purpose
Write the contents of a text file into a struct and save it into a new file

Category
Predefined method

Specman Beta Features 2-113

Using the Visualization Toolkit
expand_file_to_file()

Syntax
vt.expand_file_to_file(orig-file-name: string, new-file-name: string, instance: struct_instance)

Syntax example:
vt.expand_file_to_file("packet_template.e", "packet.e", packet_details);

Parameters

orig-file-name The name of the file whose contents are to be expanded in the new file.

new-file-name The name of the file into which the orig-file-name contents are to be
written.

instance The name of the struct instance into which the file contents are to be
expanded.

Description
This method expands the contents of a struct instance into corresponding fields of a text file, and then
writes the struct instance to a new file. This is very useful for converting template files into e code.

Example
Suppose we have a file named header.txt, which contains the following:
// File: <(file_name)>
// Author: <(author)>
// Description: <(description)>

Also, suppose we have a struct named file_details, defined as follows:

struct file_details {
file_name: string;
author: string;
description: string;
};

Then, the following code puts the contents of header.txt into the fields of an instance of the file_details
struct named details, and saving the struct instance in a file named new_header_file.txt:
mk_file() is {
var details := new file_details with {
.file_name = "myfile.e";

2-114 Specman Beta Features

 Using the Visualization Toolkit
get_absolute_name()

.author = "eMike";
.description = "This is a small e file";
};
var header_file: file = vt.expand_file_to_file("header.txt",
"new_header_file.txt", details);
};

2.7.57 get_absolute_name()

Purpose
Convert a package-relative file or directory name to an absolute name

Category
Predefined method

Syntax
vt.get_absolute_name(file-name: string): string

Syntax example:
var s: string;
s = vt.get_absolute_name("top.e");

Parameters

file-name The package-relative directory or file name to convert.

Description
Converts a package relative file or directory name into an absolute name. Return type is string.

Example
vt.get_absolute_name("myfile.e") ==> "/cad/work/myfile.e"

Specman Beta Features 2-115

Using the Visualization Toolkit
instance_to_string()

2.7.58 instance_to_string()

Purpose
Convert a Specman struct or unit instance to a string

Category
Predefined method

Syntax
vt.instance_to_string(instance: any_struct): string

Syntax example:
var s: string;
s = vt.instance_to_string("sys.packet");

Parameters

instance The name of the struct.

Description
Converts a Specman struct or unit instance into a string value. This is very useful when defining symbols
or creating Specman commands. Return type is string.

Example
vt.instance_to_string(sys) ==> "sys-@0"

2.7.59 get_color_code()

Purpose
Get the code for a color

2-116 Specman Beta Features

 Using the Visualization Toolkit
get_color_code()

Category
Predefined method

Syntax
vt.get_color_code(color: vt_color): string

Syntax example:
var s: string;
s = vt.get_color_code(CYAN);

Parameters

color The color for which you want to get the code.

Description
Shows the code for a VT color. Return type is string.

VT colors and their codes are shown below. There are 11 basic colors. Each basic color, except BLACK
and WHITE, has a light and dark version. GRAY also has a very light version.

Black and White:

Color Code

BLACK #000000

WHITE #ffffff

Other Colors:

Light Code

LIGHT_GRAY #c0c0c0

LIGHT_RED #ffc0c0

LIGHT_ORANGE #ffe0c0

Specman Beta Features 2-117

Using the Visualization Toolkit
get_color_code()

Light Code

LIGHT_YELLOW #ffffc0

LIGHT_GREEN #c0ffc0

LIGHT_CYAN #c0ffff

LIGHT_BLUE #c0c0ff

LIGHT_MAGENTA #ffc0ff

LIGHT_PURPLE #e0a0ff

Normal Code

GRAY #808080

RED #ff0000

ORANGE #ffa500

YELLOW #ffff00

GREEN #00ff00

CYAN #00ffff

BLUE #0000ff

MAGENTA #ff00ff

PURPLE #a020f0

Dark Code

DARK_GRAY #404040

DARK_RED #800000

DARK_ORANGE #ff8000

DARK_YELLOW #808000

DARK_GREEN #008000

DARK_CYAN #008080

2-118 Specman Beta Features

 Using the Visualization Toolkit
text_style()

Dark Code

DARK_BLUE #000080

DARK_MAGENTA #800080

DARK_PURPLE #8010a0

Very Light Code

VERY_LIGHT_ #f0f0f1
GRAY

Example
vt.get_color_code(RED) ==> #FF0000;

2.7.60 text_style()

Purpose
Print colorized text

Category
Predefined method

Syntax
vt.text_style(style: vt_style, text: string): string

Syntax example:
var s: string;
s = print(vt.text_style(CYAN, "Showing packets"));

Specman Beta Features 2-119

Using the Visualization Toolkit
text_style()

Parameters

style The name of the color to use for the text.

text The text to print.

Description
Creates a string in a special format, which has the style’s background and foreground colors, when
printed in Specview.

The list of available styles is identical to the list of colors, as follows:

Light Styles

Style Name Foreground Color Background Color

LIGHT_GRAY BLACK LIGHT_GRAY

LIGHT_RED BLACK LIGHT_RED

LIGHT_ORANGE BLACK LIGHT_ORANGE

LIGHT_YELLOW BLACK LIGHT_YELLOW

LIGHT_GREEN BLACK LIGHT_GREEN

LIGHT_CYAN BLACK BLACK

LIGHT_BLUE BLACK LIGHT_BLUE

LIGHT_MAGENTA BLACK LIGHT_MAGENTA

LIGHT_PURPLE BLACK LIGHT_PURPLE

Normal Styles

Style Name Foreground Color Background Color

GRAY GRAY WHITE

RED RED WHITE

ORANGE ORANGE WHITE

YELLOW BLACK YELLOW

2-120 Specman Beta Features

 Using the Visualization Toolkit
text_style()

Style Name Foreground Color Background Color

GREEN GREEN WHITE

CYAN BLACK CYAN

BLUE BLUE WHITE

MAGENTA MAGENTA WHITE

PURPLE PURPLE WHITE

Dark Styles

Style Name Foreground Color Background Color

DARK_GRAY DARK_GRAY WHITE

DARK_RED DARK_RED WHITE

DARK_ORANGE DARK_ORANGE WHITE

DARK_YELLOW DARK_YELLOW WHITE

DARK_GREEN DARK_GREEN WHITE

DARK_CYAN DARK_CYAN WHITE

DARK_BLUE DARK_BLUE WHITE

DARK_MAGENTA DARK_MAGENTA WHITE

DARK_PURPLE DARK_PURPLE WHITE

Other Styles

Style Name Foreground Color Background Color

BLACK BLACK WHITE

WHITE BLACK WHITE

VERY_LIGHT_GRAY BLACK VERY_LIGHT_GRAY

Specman Beta Features 2-121

Using the Visualization Toolkit
show_styles()

Example
out(vt.text_style(RED, "This is red text"));

Note Use show_styles() on page 2-122 to view all of the available styles.

2.7.61 show_styles()

Purpose
Display VT styles

Category
Predefined method

Syntax
vt.show_styles()

Syntax example:
vt.show_styles();

Description
This method displays a list of all VT styles.

Example
The following defines a VT window subclass with a user-defined menu command that shows all
available VT styles. A toolbar button is not added.
extend A_WINDOW vt_window {
configure() is also {
add_menu_item("Tools", "Show VT Styles", "Show All Available VT
styles", "vt.show_styles()", "icon_styles.gif", "");
};
};

2-122 Specman Beta Features

 Using the Visualization Toolkit
get_all_windows()

2.7.62 get_all_windows()

Purpose
Display a list of all open VT windows

Category
Predefined method

Syntax
vt.get_all_windows(): list of vt_window

Syntax example:
var my_open_windows: list of vt_window;
my_open_windows_list = get_all_windows();

Description
This method returns a list of all open VT windows. Do not modify this list.

Example
The following finds all open windows of kind MY_WINDOW.
var my_windows : list of vt_window;

// Get all open VT windows of kind MY_WINDOW

my_windows = vt.get_all_windows().all(.get_kind() == MY_WINDOW);

2.7.63 get_all_pages()

Purpose
Display a list of all open VT pages

Specman Beta Features 2-123

Using the Visualization Toolkit
get_all_pages()

Category
Predefined method

Syntax
vt.get_all_pages(): list of vt_page

Syntax example:
var my_open_pages: list of vt_page;
my_open_pages_list = get_all_pages();

Description
This method returns a list of all open VT pages in all VT windows. Do not modify this list.

Example
The following prints the number of pages in the first VT window of kind A_WINDOW.
// Get the list of all open VT windows
var all_windows: list of vt_window = vt.get_all_windows();

if (! all_windows.is_empty()) {
// Get the first window of kind A_WINDOW
var a_window: vt_window = all_windows.first(it.get_kind() ==
A_WINDOW);

if (a_window != NULL) {
// Get all the VT pages in that window
var all_pages: list of vt_page = a_window.get_all_pages();

if (! all_pages.is_empty()) {
// Print the number of pages in that window
print all_pages.size();
};
};
};

2-124 Specman Beta Features

 Using the Visualization Toolkit
VT Window API Methods

2.7.64 VT Window API Methods

The visibility of the window should be checked using the is_visible() method before any of the other VT
Window API methods is used, since only is_visible can be used without warnings on visible windows.

The following methods apply to all windows that have the same window kind as the window in which
they are used:

• vt_window.set_location()
• vt_window.set_size()
• vt_window.add_menu(
• vt_window.add_menu_item()
• vt_window.add_menu_separator()
• vt_window.add_toolbar_separator()
• vt_window.set_navigation_buttons()
• vt_window.set_lock_button()

This section contains the following topics:

• “Window Configuration Method” on page 2-125

• “Window Graphic Properties Methods” on page 2-127
• “Menu Bar and Toolbar Preparation Methods” on page 2-144
• “Menu Bar and Toolbar Preparation Methods” on page 2-144
• “Window Symbols Methods” on page 2-157
• “Window Closing Methods” on page 2-163

2.7.65 Window Configuration Method

This section contains the following reference page:

• configure() on page 2-125

2.7.66 configure()

Purpose
Calls other methods to set up a VT window

Specman Beta Features 2-125

Using the Visualization Toolkit
configure()

Category
Predefined method

Syntax
configure() is also {configuration-code}

Syntax example:
configure() is also {set_location(250, 100); set_size(600, 500);};

Parameters

configuration-code A block of VT window method calls that configure the features of the VT
window.

Description
This is an empty method that you fill in with code to set up a VT window object. You fill the method
with calls to other VT window predefined methods to achieve the desired behavior of the VT window.

This method can only be called before the VT window is displayed.

Example 1
The following example defines a vt_window subclass of kind A_WINDOW and uses the configure()
method to initialize the location and size of the window, and to add a menu named Packets with a Show
Packets command.
extend vt_window_kind: [A_WINDOW];

extend A_WINDOW vt_window {

configure() is also {
set_location(250, 100);
set_size(600, 500);
add_menu("Packets");
add_menu_item("Packets", "Show Packets", "Show Packets",
"sys.show_packets()", "", "");
};
};

2-126 Specman Beta Features

 Using the Visualization Toolkit
Window Graphic Properties Methods

Example 2
extend vt_window_kind: [PACKET_VIEWER_WINDOW];
extend PACKET_VIEWER_WINDOW vt_window {
configure() is also {
set_location(250, 100);
set_size(600, 500);
add_menu("Packets");
add_menu_item("Packets", "Show Packets");
};
};

2.7.67 Window Graphic Properties Methods

This section contains the following topics.

• “Methods to Set Window Attributes” on page 2-127

• “Methods to Display Window Status” on page 2-132
• “Methods to Display Window Information” on page 2-137
• “Interactive Calls to Windows” on page 2-143
• “Menu Bar and Toolbar Preparation Methods” on page 2-144

2.7.68 Methods to Set Window Attributes

• set_location() on page 2-127
• set_size() on page 2-128
• set_locked() on page 2-129
• set_title_prefix() on page 2-131

2.7.69 set_location()

Purpose
Specify the location of a window

Specman Beta Features 2-127

Using the Visualization Toolkit
set_size()

Category
Predefined method

Syntax
vt-window.set_location(x: int, y: int)

Syntax example:
var a_window: vt_window;
a_window.set_location(18, 18);

Parameters

x The x-coordinate for the top-left corner of the window, in pixels.

y The y-coordinate for the top-left corner of the window, in pixels

Description
Sets the location of the top-left corner of the window, in pixels from the top-left corner of the screen.
This must be done before the window is made visible.

Example
The following example defines a vt_window subclass and sets the location of the top-left corner of the
window to be (100,100) in pixels.
extend A_WINDOW vt_window {
configure() is also {
set_location(100, 100);
};
};

2.7.70 set_size()

Purpose
Specify the size of a window

2-128 Specman Beta Features

 Using the Visualization Toolkit
set_locked()

Category
Predefined method

Syntax
vt-window.set_size(width: int, height: int)

Syntax example:
var a_window: vt_window;
a_window.set_size(216, 216);

Parameters

width The width in pixels of the window.

height The height in pixels of the window.

Description
Sets the width and height of the window, in pixels. This must be done before the window is made visible.

Example
The following example defines a vt_window subclass and sets the width and height of the window to be
(width=500, height=400) in pixels.
extend A_WINDOW vt_window {
configure() is also {
set_size(500, 400);
};
};

2.7.71 set_locked()

Purpose
Locks the window

Specman Beta Features 2-129

Using the Visualization Toolkit
set_locked()

Category
Predefined method

Syntax
vt-window.set_locked(locked: bool)

Syntax example:
var a_window: vt_window;
a_window.set_locked(TRUE);

Parameters

locked Use TRUE to lock the VT window, or use FALSE to unlock it.

Description
With an argument of TRUE, locks the window. With an argument of FALSE, unlocks the window.
Locking a VT window prevents it from being reused or having its contents changed.

This method can only be called after the window is displayed.

Example
The following example locks a window of kind A_WINDOW which prevents subsequent pages with
that window kind, to open in that window.
// Lock the window, assume it is of kind A_WINDOW
var locked:= a_window.is_locked();

if(! locked) {
a_window.set_locked(TRUE);
};

// A new page with same window kind will open in a new window
vt.show_page("my_file.e", A_WINDOW);

See Also
• is_locked() on page 2-135

2-130 Specman Beta Features

 Using the Visualization Toolkit
set_title_prefix()

• is_lockable() on page 2-136

• set_lockable() on page 2-152

2.7.72 set_title_prefix()

Purpose
Specify the window prefix for the title of a window

Category
Predefined method

Syntax
vt-window.set_title_prefix(prefix: string)

Syntax example:
var a_window: vt_window;
a_window.set_title_prefix("Packets");

Parameters

prefix The text for the window title prefix.

Description
Sets the prefix for the title text for the window. The text specified with set_title_prefix() on page 2-131
is appended to this text to form the complete window title.

This method can only be called before the VT window is displayed.

Example
The following example defines a vt_window subclass with a title_prefix of: "Packet Window".
extend A_WINDOW vt_window {
configure() is also {
set_title_prefix("Packet Window");

Specman Beta Features 2-131

Using the Visualization Toolkit
Methods to Display Window Status

};
};

See Also
• set_title() on page 2-170

2.7.73 Methods to Display Window Status

This section contains the following reference pages.

• is_visible() on page 2-132

• is_opened() on page 2-133
• is_closed() on page 2-134
• is_locked() on page 2-135
• is_lockable() on page 2-136

2.7.74 is_visible()

Purpose
Check whether a window is visible

Category
Predefined method

Syntax
vt-window.is_visible(): bool

Syntax example:
var a_window: vt_window;
a_window.is_visible();

2-132 Specman Beta Features

 Using the Visualization Toolkit
is_opened()

Description
Checks whether a window is visible.

Example
var handle: vt_window =
vt.open_file("rank_appl/rank.html", "rank", FALSE);
if (not handle.is_visible()) {
handle.set_title("Ranking Window");
handle.set_visible(TRUE);
}
else{
//return or issue an error
};

2.7.75 is_opened()

Purpose
Check whether a window is open

Category
Predefined method

Syntax
vt-window.is_opened(): bool

Syntax example:
var opened: bool;
var a_window: vt_window;
opened = vt_window.is_opened();

Description
Returns TRUE if the window is open, or returns FALSE if the window is not open. When a window is
visible, it is open.

Specman Beta Features 2-133

Using the Visualization Toolkit
is_closed()

This method can be called at any time except after the window has been closed.

Example
The following example checks whether a window is opened, and if so prints the actual file name of the
current page.
var opened: bool = a_window.is_opened();
if (opened) {
//print actual file name
print a_window.get_current_page().get_file_name();
};

2.7.76 is_closed()

Purpose
Check whether a window is closed

Category
Predefined method

Syntax
vt-window.is_closed(): bool

Syntax example:
var closed: bool;
var a_window: vt_window;
closed = a_window.is_closed()

Description
Returns TRUE if the window is closed, or returns FALSE if the window is not closed.

This method can be called at any time except after the window has been closed.

2-134 Specman Beta Features

 Using the Visualization Toolkit
is_locked()

Example
The following example checks whether a window is closed, and if not closes the window.
var closed: bool = a_window.is_closed();
if (! closed) {
a_window.close();
};

2.7.77 is_locked()

Purpose
Check whether a window is locked

Category
Predefined method

Syntax
vt-window.is_locked(): bool

Syntax example:
var locked: bool;
var a_window: vt_window;
locked = a_window.is_locked();

Description
Returns TRUE if the window is locked, or returns FALSE if the window is not locked.

This method can be called at any time except after the window has been closed.

Example
The following example checks whether a window is locked, and if so unlocks it.
var locked: bool = a_window.is_locked();
if (locked) {
a_window.set_locked(FALSE);

Specman Beta Features 2-135

Using the Visualization Toolkit
is_lockable()

};

2.7.78 is_lockable()

Purpose
Check whether a window is lockable

Category
Predefined method

Syntax
vt-window.is_lockable(): bool

Syntax example:
var lockable: bool;
var a_window: vt_window;
lockable = a_window.is_lockable();

Description
Returns TRUE if the window is lockable, or returns FALSE if the window is not lockable. Lockable
windows have Lock buttons, while unlockable windows have none.

This method can be called at any time except after the window has been closed.

Example
The following example checks whether a VT window is lockable and if so, locks the window.
var has_lock: bool = a_window.is_lockable();

if (! has_lock){
out("This VT window is not lockable");
} else {
a_window.set_locked(TRUE);
};

2-136 Specman Beta Features

 Using the Visualization Toolkit
Methods to Display Window Information

2.7.79 Methods to Display Window Information

• get_current_page() on page 2-137
• get_all_pages() on page 2-138
• get_kind() on page 2-139
• get_size() on page 2-140
• get_location() on page 2-141
• get_title_prefix() on page 2-142

2.7.80 get_current_page()

Purpose
Display the current VT window page

Category
Predefined method

Syntax
vt-window.get_current_page(): vt_page

Syntax example:
var packet_page: vt_page;
packet_page = a_window.get_current_page();

Description
This method returns the current page of the VT window.

This method can only be called after the window is displayed.

Example
The following example prints information about the current page of the first opened window of type
A_WINDOW.

Specman Beta Features 2-137

Using the Visualization Toolkit
get_all_pages()

// Get the list of all open VT windows

var all_windows: list of vt_window = vt.get_all_windows();

if (! all_windows.is_empty()){
// Get the first window of kind A_WINDOW
var a_window : vt_window = all_windows.first(it.get_kind() ==
A_WINDOW);

if (a_window != NULL) {
// Print the current page in that window
print a_window.get_current_page();
};
};

See Also
• get_all_pages() on page 2-138

2.7.81 get_all_pages()

Purpose
Display all VT window pages

Category
Predefined method

Syntax
vt-window.get_all_pages(): list of vt_page

Syntax example:
var all_pages_list: list of vt_page;
all_pages_list = a_window.get_all_pages();

Description
This method returns a list of all VT window pages.

2-138 Specman Beta Features

 Using the Visualization Toolkit
get_kind()

This method can only be called after the window is displayed.

Example
The following example prints the number of pages in the first VT window of kind A_WINDOW.
// Get the list of all open VT windows
var all_windows: list of vt_window = vt.get_all_windows();

if (! all_windows.is_empty()) {
// Get the first window of kind A_WINDOW
var a_window: vt_window = all_windows.first(it.get_kind() ==
A_WINDOW);

if (a_window != NULL) {
// Get all the VT pages in that window
var all_pages: list of vt_page = a_window.get_all_pages();

if (! all_pages.is_empty()) {
// Print the number of pages in that window
print all_pages.size();
};
};
};

See Also
• get_current_page() on page 2-137

2.7.82 get_kind()

Purpose
Display the window kind

Category
Predefined method

Syntax
vt-window.get_kind( ): vt_window_kind

Specman Beta Features 2-139

Using the Visualization Toolkit
get_size()

Syntax example:
var wkind: vt_window_kind;
wkind = vt_window.get_kind();

Description
This method returns the VT window kind. The kind is determined by the setting of the enumerated kind
field in current instance of the vt_window struct.

This method can be called at any time except after the window has been closed.

Example
The following example finds all open windows of kind MY_WINDOW.
var my_windows : list of vt_window;
// Get all open VT windows of kind MY_WINDOW
my_windows = vt.get_all_windows().all(.get_kind() == MY_WINDOW);

2.7.83 get_size()

Purpose
Get the window’s size

Category
Predefined method

Syntax
vt-window.set_get_size(): vt_size

Syntax example:
var wsize: vt_size;
wsize = a_window.get_size();

2-140 Specman Beta Features

 Using the Visualization Toolkit
get_location()

Description
This method returns the size of the window.

This method can only be called after the window is displayed.

Example
The following example opens a VT page in a VT window of type A_WINDOW and prints the size of the
window.
// Open a page
var a_page : A_PAGE vt_page = new;
a_page.set_file(".");
a_page.set_window_kind(A_WINDOW);
a_page.show();

// Print the window size

print a_page.get_window().get_size();

See Also
• set_size() on page 2-128
• get_location() on page 2-141

2.7.84 get_location()

Purpose
Get the window’s location

Category
Predefined method

Syntax
vt-window.get_location(): vt_location

Syntax example:
var wlocation: vt_location;

Specman Beta Features 2-141

Using the Visualization Toolkit
get_title_prefix()

wlocation = a_window.get_location();

Description
This method returns the coordinates of the upper-right corner of the window.

This method can only be called after the window is displayed.

Example
The following example opens a VT page in a VT window of type A_WINDOW and prints the location
of the window.
// Open a page
var a_page : A_PAGE vt_page = new;
a_page.set_file(".");
a_page.set_window_kind(A_WINDOW);
a_page.show();

// Print the window location

print a_page.get_window().get_location();

See Also
• set_location() on page 2-127
• get_size() on page 2-140

2.7.85 get_title_prefix()

Purpose
Display the first part (prefix) of the window title

Category
Predefined method

Syntax
vt-window.get_title_prefix(): string

2-142 Specman Beta Features

 Using the Visualization Toolkit
Interactive Calls to Windows

Syntax example:
var win_prefix: string;
win_prefix = a_window.get_title_prefix();

Description
Displays the prefix part of the window title. The window title consists of a prefix and a main part, which
you specify using set_title() on page 2-170.

This method can be called at any time except after the window has been closed.

Example
The following example prints the VT window title prefix.
var title_prefix: string = a_window.get_title_prefix();
out("The VT window Title-Prefix is: ", title_prefix);

See Also
• set_title() on page 2-170

2.7.86 Interactive Calls to Windows

This section contains the following reference page:

• to_front() on page 2-143

2.7.87 to_front()

Purpose
Bring the window to the front

Category
Predefined method

Specman Beta Features 2-143

Using the Visualization Toolkit
Menu Bar and Toolbar Preparation Methods

Syntax
vt-window.to_front()

Syntax example:
var a_window: vt_window;
a_window.to_front();

Description
Brings the window to the front, on top of all other windows.

Example
The following example brings the first window of kind A_WINDOW to the front.
// Get the list of all open VT windows
var all_windows: list of vt_window = vt.get_all_windows();

if (! all_windows.is_empty()){
// Get the first window of kind A_WINDOW
var a_window: vt_window = all_windows.first(it.get_kind() ==
A_WINDOW);

if (a_window != NULL) {
a_window.to_front();
};
};

2.7.88 Menu Bar and Toolbar Preparation Methods

This section contains the following reference pages:

• add_menu() on page 2-145

• add_menu_item() on page 2-146
• add_menu_separator() on page 2-148
• add_toolbar_separator() on page 2-149
• enable_action() on page 2-150
• hide_navigation_buttons() on page 2-152

2-144 Specman Beta Features

 Using the Visualization Toolkit
add_menu()

• set_lockable() on page 2-152

2.7.89 add_menu()

Purpose
Add a new menu

Category
Predefined method

Syntax
vt-window.add_menu(menu-name: string)

Syntax example:
var a_window: vt_window;
a_window.add_menu("Tools");

Parameters

menu-name The text for the menu title.

Description
Add a menu to the menu bar to the right of the existing menus.

Example
The following example defines a vt_window subclass with a user-defined menu named “Packets”.
extend A_WINDOW vt_window {
configure() is also {
add_menu("Packets");
};
};

Specman Beta Features 2-145

Using the Visualization Toolkit
add_menu_item()

2.7.90 add_menu_item()

Purpose
Add a new action

Category
Predefined method

Syntax
win.add_menu_item(menu-name: string, title: string, tool-tip: string, specman-command: string,
icon-file: string, toolbar-title: string)

Syntax example:
me.add_menu_item("Tools", "Print", "Print Window","print %_window",
"icon_print.gif", "Print");

Parameters

menu-name The name of the menu to which the menu command is to be added.

title The title of the menu command.

tool-tip The text for the tooltip for the menu command.

specman-command The Specman command which the menu command invokes.

icon-file The name of the file that contains the graphic for the menu command icon.

toolbar-title The text for the toolbar title, if the menu command is to be added to the
toolbar.

Description
Adds a new action, which is defined by the specified Specman command. This action is added as a new
menu command under the specified menu, with the specified title, with the icon defined in the specified
icon file. The tooltip is the balloon help that appears when the mouse is above this menu command.

In addition, if the toolbar title parameter is specified, a new toolbar button is added to the toolbar with
the specified title; otherwise, no toolbar button is added.

2-146 Specman Beta Features

 Using the Visualization Toolkit
add_menu_item()

When the end user clicks the menu command or toolbar button, the specified command is executed.

Notes
• Each new menu command is always added at the bottom of the requested menu, with one exception:
Following Specview conventions, the Lock and Close toolbar buttons are always at the bottom of
the File menu. Thus, new menu commands that are added to the File menu are inserted before the
Lock menu item.
• Each new toolbar button is added to the right of the previous buttons with one exception: Following
Specview conventions, the Lock and Close toolbar buttons are right aligned. Thus, the custom toolbar
buttons are added starting to the right of the Find button.
• The menu command title shows the action name, while the toolbar button text can be any convenient
title. Typically, it is a shorter name.
• All actions are enabled by default.

Example 1
The following example defines a vt_window subclass with a user-defined menu command that opens the
Data Browser on the sys struct.
extend A_WINDOW vt_window {
configure() is also {
add_menu_item("Tools", "Show Data", "Open Data Browser with sys
struct", "show data sys", "icon_show_data.gif", "Show sys");
};
};

Example 2
The following example defines a vt_window subclass with a user-defined menu command that shows all
available VT styles.

A toolbar button is not added.

extend A_WINDOW vt_window {
configure() is also {
add_menu_item("Tools", "Show VT Styles", "Show All Available VT
styles", "vt.show_styles()", "icon_styles.gif", "");
};
};

Specman Beta Features 2-147

Using the Visualization Toolkit
add_menu_separator()

Example 3
The following example defines a vt_window subclass with a user-defined menu command that
calculates the sum of two numbers.

Assume that we have an instance of struct calculator named “calc” under sys.
struct calculator {
sum(num1: int, num2: int):int is {
result = num1 + num2;
};
};

extend A_WINDOW vt_window {

configure() is also {
add_menu_item("Calculator", "Sum", "Sum of two numbers", "print
sys.calc.sum(5, 7)", "icon_sum.gif", "Sum");
};
};

2.7.91 add_menu_separator()

Purpose
Add a new menu separator

Category
Predefined command

Syntax
vt-window.add_menu_separator(menu-name: string)

Syntax example:
var a_window: vt_window;
a_window.add_menu_separator("Members");

2-148 Specman Beta Features

 Using the Visualization Toolkit
add_toolbar_separator()

Parameters

menu-name The menu to which a separator is to be added.

Description
Adds a new separator to the named menu.

Example
The following example defines a vt_window subclass and adds two menu commands to the “Tools”
menu, with a separator between them.

extend A_WINDOW vt_window {

configure() is also {
add_menu_item("Tools", "Print", "Print Window","print %_window",
"icon_print.gif", "");
add_menu_separator("Tools");
add_menu_item("Tools", "Print", "Print Page","print %_page",
"icon_print.gif", "");
};
};

2.7.92 add_toolbar_separator()

Purpose
Add a separator to the toolbar

Category
Predefined method

Syntax
vt-window.add_toolbar_separator()

Syntax example:
var a_window: vt_window;
a_window.add_toolbar_separator();

Specman Beta Features 2-149

Using the Visualization Toolkit
enable_action()

Description
Adds a new separator to the toolbar. Each new separator is added to the right of the last button
(excluding Lock and Close).

Example
The following example defines a vt_window subclass and adds two tool bar buttons with a separator
between them.
extend A_WINDOW vt_window {
configure() is also {
add_menu_item("Tools", "Print", "Print Window","print %_window",
"icon_print.gif", "Print Window");
add_toolbar_separator();
add_menu_item("Tools", "Print", "Print Page","print %_page",
"icon_print.gif", "Print Page");
};
};

2.7.93 enable_action()

Purpose
Enable or disable a VT window menu action

Category
Predefined method

Syntax
vt-window.enable_action(action-title: string, enabled: bool)

Syntax example:
var a_window: vt_window;
a_window.enable_action("Show packets", FALSE);

2-150 Specman Beta Features

 Using the Visualization Toolkit
enable_action()

Parameters

action-title The title for the action used in the menu. This is not necessarily the same
as the title used for the action in the toolbar.

enabled Enter FALSE to disable the action. The default is TRUE (the action is
enabled).

Description
Enables or disables an action you have added to a VT window menu. This method can be called at any
time except after the window is closed, in the window’s configure() method, for example, or
dynamically after the window is displayed.

This method can only be applied to user-defined actions. It cannot be applied to predefined VT actions
such as Lock or Close.

This method can be called at any time except after the window has been closed.

Example 1
The following disables two user-defined menu commands: "Print Window" and "Print Page" in the
configure() method.
extend A_WINDOW vt_window {
configure() is also {
// Add custom menu commands
add_menu_item("Tools", "Print Window", "Print Window","print
%_window", "icon_print.gif", "");
add_menu_item("Tools", "Print Page", "Print Page", "print %_page",
"icon_print.gif", "");

// Disable custom menu commands

enable_action("Print Window", FALSE);
enable_action("Print Page", FALSE);
};
};

Example 2
The following example enables actions dynamically (at run time).
a_window.enable_action("Print Window", TRUE);
a_window.enable_action("Print Page", TRUE);

Specman Beta Features 2-151

Using the Visualization Toolkit
hide_navigation_buttons()

2.7.94 hide_navigation_buttons()

Purpose
Hide Prev and Next buttons in a VT window

Category
Predefined method

Syntax
vt-window.hide_navigation_buttons()

Syntax example:
var a_window: vt_window;
a_window.hide_navigation_buttons();

Description
Enables or disables adding of Prev and Next navigation buttons in a VT window.

Example
The following example defines a vt_window subclass without navigation buttons.
extend A_WINDOW vt_window {
configure() is also {
hide_navigation_buttons();
};
};

2.7.95 set_lockable()

Purpose
Determine whether the Lock command is included on a VT window

2-152 Specman Beta Features

 Using the Visualization Toolkit
Methods for Adding Secondary Toolbars

Category
Predefined method

Syntax
vt-window.set_lockable(lockable: bool)

Syntax example:
var a_window: vt_window;
a_window.set_lockable(FALSE);

Parameters

lockable Enter FALSE to omit the Lock command. The default is TRUE (a Lock
command is available).

Description
Includes or excludes a Lock command on a VT window.

Example
The following example defines a vt_window subclass without a lock button.

extend A_WINDOW vt_window {

configure() is also {
set_lockable(FALSE);
};
};

2.7.96 Methods for Adding Secondary Toolbars

This section contains the following reference pages:

• add_secondary_toolbar() on page 2-154

• add_menu_item_to_secondary_toolbar() on page 2-155
• add_separator_to_secondary_toolbar() on page 2-156

Specman Beta Features 2-153

Using the Visualization Toolkit
add_secondary_toolbar()

2.7.97 add_secondary_toolbar()

Purpose
Add a secondary toolbar to a window

Category
Predefined method

Syntax
vt-window.add_secondary_toolbar(toolbar-names: list of string)

Syntax example:
add_secondary_toolbar("tb_sec1");

Parameters

toolbar-name The name for the secondary toolbar.

Description
Adds secondary toolbars to a VT window. This method must be used in the window configuration. Each
toolbar must have a unique name.

Example
extend vt_window_kind: [MY_WINDOW];
extend MY_WINDOW vt_window {
configure() is also {
add_secondary_toolbar({"tb_sec1"; "tb_sec2"})
};
};

See Also
• add_menu_item_to_secondary_toolbar() on page 2-155

2-154 Specman Beta Features

 Using the Visualization Toolkit
add_menu_item_to_secondary_toolbar()

• add_separator_to_secondary_toolbar() on page 2-156

2.7.98 add_menu_item_to_secondary_toolbar()

Purpose
Add a menu item to a secondary toolbar

Category
Predefined method

Syntax
vt-window.add_menu_item_to_secondary_toolbar(toolbar-name: string, menu-name: string, title:
string, tooltip: string, command: string, icon-file: string, toolbar-title: string)

Syntax example:
add_menu_item_to_secondary_toolbar("tb_sect1", "File", "Print", "Print 5",
"print 5", "icon_print.gif", "Print");

Parameters

toolbar-name The name for the secondary toolbar.

menu-name The name of the menu to which the item is being added.

title The title of the item in the menu.

tooltip The text for the menu item tooltip.

command The command that the menu item executes.

icon-file The name of the file that contains the icon graphic for the menu item

toolbar-title The name of the secondary toolbar into which the menu item is to be
added.

Specman Beta Features 2-155

Using the Visualization Toolkit
add_separator_to_secondary_toolbar()

Description
Adds a menu item to a secondary toolbar. This method must be used in the window configuration. If no
secondary toolbar matching the toolbar-name parameter is found a warning is issued.

Example
extend vt_window_kind: [MY_WINDOW];
extend MY_WINDOW vt_window {
configure() is also {
add_secondary_toolbar({"tb_sec1"})
add_menu_item_to_secondary_toolbar("tb_sec1", "File",
"Print", "Print 5", "print 5", "icon_print.gif", "Print");
};
};

See Also
• add_secondary_toolbar() on page 2-154
• add_separator_to_secondary_toolbar() on page 2-156

2.7.99 add_separator_to_secondary_toolbar()

Purpose
Add a toolbar separator to a secondary toolbar

Category
Predefined method

Syntax
vt-window.add_separator_to_secondary_toolbar(toolbar-name: string)

Syntax example:
add_separator_to_secondary_toolbar(secondary_toolbar_name);

2-156 Specman Beta Features

 Using the Visualization Toolkit
Window Symbols Methods

Parameters

toolbar-name The name of the toolbar to which the separator is to be added.

Description
Adds a toolbar separator to a secondary toolbar. This method must be used in the window configuration.
If no secondary toolbar matching the toolbar-name parameter is found a warning is issued.

Example
extend vt_window_kind: [MY_WINDOW];
extend MY_WINDOW vt_window {
configure() is also {
var secondary_toolbar_name:= "sec1";
add_secondary_toolbar({secondary_toolbar_name});
add_menu_item_to_secondary_toolbar(secondary_toolbar_name,
"File", "Print", "Print 5", "print 5", "icon_print.gif",
"Print");
add_separator_to_secondary_toolbar(secondary_toolbar_name);
};
};

See Also
• add_secondary_toolbar() on page 2-154
• add_menu_item_to_secondary_toolbar() on page 2-155

2.7.100 Window Symbols Methods

This section contains the following reference pages:

• set_symbol_value() on page 2-158

• set_symbol_values() on page 2-159
• get_symbol_value() on page 2-161
• get_symbol_values() on page 2-162

Specman Beta Features 2-157

Using the Visualization Toolkit
set_symbol_value()

2.7.101 set_symbol_value()

Purpose
Set a symbol value

Category
Predefined method

Syntax
vt-window.set_symbol_value(name: string, value: string)

Syntax example:
var a_window: vt_window;
a_window.set_symbol_value("appl", "sys.packet_viewer");

Parameters

name The symbol name.

value The value to set for the symbol.

Description
This method sets a value for a specified symbol of a VT window subtype. If the symbol does not exist,
this method adds a new symbol with the specifed name. All pages can use the symbol. You can use
get_symbol_value() on page 2-161 to get the value of a symbol.

This method can only be called before the VT window is displayed.

Example 1
The following example sets a symbol named “packet_id” to have the value of sys.green_packet.id.

Assume that there is an instance “green_packet” under sys that has a field name “id”.
extend A_WINDOW vt_window {
configure() is also {
set_symbol_value("packet_id", "sys.green_packet.id");

2-158 Specman Beta Features

 Using the Visualization Toolkit
set_symbol_values()

};
};

Example 2
This example sets a symbol named “appl” to point to and instance named sys.appl”.

Assume that there is an instance of “appl” under sys.

extend A_WINDOW vt_window {
configure() is also {
set_symbol_value("appl", vt.instance_to_string(sys.appl));
};
};

Example 3
The following example sets a symbol named “pwd” to point to the current directory, from where
Specman was invoked.
extend A_WINDOW vt_window {
configure() is also {
set_symbol_value("pwd", files.curr_full_dir());
};
};

See Also
• set_symbol_values() on page 2-159
• get_symbol_value() on page 2-161

2.7.102 set_symbol_values()

Purpose
Set values for a list of symbols

Specman Beta Features 2-159

Using the Visualization Toolkit
set_symbol_values()

Category
Predefined method

Syntax
vt-window.set_symbol_values(names: list of string, values: list of string)

Syntax example:
var a_window: vt_window;
a_window.set_symbol_values({"appl_1"; val1, "appl_2"; val_2});

Parameters

names The names of the symbols.

values The values to set for the symbols.

Description
This method sets the values of a list of symbols of the window. If any symbol in the specified list does
not exist, then a new symbol is added for it. All pages can use the symbols.

This method can only be called before the VT window is displayed.

Example
The following example creates a symbol named last_pkt to represent vt.instance_to_string(last_pkt),
and similarly creates symbols named “curr_pkt” and “next_pkt” to represent the other, corresponding
vt.instance_to_string() calls.
extend A_WINDOW vt_window {
configure() is also {
a_window.set_symbol_values({"last_pkt"; "curr_pkt";"next_pkt"},
{vt.instance_to_string(last_pkt);
vt.instance_to_string(curr_pkt);
vt.instance_to_string(next_pkt);
);
};
};

2-160 Specman Beta Features

 Using the Visualization Toolkit
get_symbol_value()

See Also
• set_symbol_value() on page 2-158
• get_symbol_value() on page 2-161

2.7.103 get_symbol_value()

Purpose
Get the value of a symbol

Category
Predefined method

Syntax
vt-window.get_symbol_value(symbol: string): string

Syntax example:
extend PACKET_VIEWER_WINDOW vt_window {
get_sym() is {
var sym: string;
sym = a_window.get_symbol_value("appl");
print sym;
};
};

Parameters

symbol The symbol whose value is to be returned.

Description
This method returns the value of a symbol defined for the VT window.

This method can be called at any time except after the window has been closed.

Specman Beta Features 2-161

Using the Visualization Toolkit
get_symbol_values()

Example 1
The following example prints the value of the pre-defined symbol “_window_kind”.
print a_window.get_symbol_value("_window_kind");

Example 2
The following example prints the value of a user-defined symbol “packet_id”.
print a_window.get_symbol_value("packet_id");

2.7.104 get_symbol_values()

Purpose
Get a list of symbol values

Category
Predefined method

Syntax
vt-window.get_symbol_values(names: list of string): list of string

Syntax example:
var syms: list of string;
syms = a_window.get_symbol_values("apps");

Parameters

names The names of symbols whose values are to be returned.

Description
This method returns a list of values of the symbols in the names list. If a symbol in the list does not exist,
an empty string is returned.

2-162 Specman Beta Features

 Using the Visualization Toolkit
Window Closing Methods

Example
extend PACKET_VIEWER_WINDOW vt_window {
get_syms(pvals) is {
var syms: list of string;
syms = a_window.get_symbol_values("apps");
print syms;
};
};

See Also
• get_symbol_value() on page 2-161
• set_symbol_value() on page 2-158
• set_symbol_values() on page 2-159

2.7.105 Window Closing Methods

This section contains the following reference pages:

• set_pre_close_command() on page 2-163

• close() on page 2-165

2.7.106 set_pre_close_command()

Purpose
Sets a callback upon closing a VT window

Category
Predefined method

Syntax
vt-window.set_pre_close_command(specman-command: string)

Syntax example:
var a_window: vt_window;

Specman Beta Features 2-163

Using the Visualization Toolkit
set_pre_close_command()

a_window.set_pre_close_command("print closing_notice");

Parameters

specman-command A Specman command that is to be used as the closing command.

Description
This method binds a callback for notification up execution of the Close action for the window.

This method can only be called before the VT window is displayed.

Example 1
The following example prints a message to the screen when the window is closed.
extend A_WINDOW vt_window {
configure() is also {
set_pre_close_command("out(\"VT window closed\")");
};
};

Example 2
The following example calls the sys.manager method named “notify_window_closed()”, passing it the
window reference when the window is closed.

Assume we have an instance named “manager” under sys.

extend A_WINDOW vt_window {
configure() is also {
set_pre_close_command("sys.manager.notify_window_closed(%_window));
};
};

See Also
• close() on page 2-165

2-164 Specman Beta Features

 Using the Visualization Toolkit
close()

2.7.107 close()

Purpose
Close the window

Category
Predefined method

Syntax
vt-window.close()

Syntax example:
a_window.close();

Description
This method closes the VT window.

Example
The following example closes the first window from the list of all opened VT windows.
// Get the list of all open VT windows
var all_windows: list of vt_window = vt.get_all_windows();

if (! all_windows.is_empty()){
all_windows[0].close();
};

2.7.108 VT Page API Methods

This section contains the following topics:

• “Configure Method” on page 2-166

• “Methods to Set Page Attributes” on page 2-168
• “Methods to Set Page Contents” on page 2-171

Specman Beta Features 2-165

Using the Visualization Toolkit
Configure Method

• “Methods to Display Pages” on page 2-179

• “Methods to Display Page Status” on page 2-181
• “Methods to Display Page Information” on page 2-184
• “Methods to Display the Page Contents” on page 2-195
• “Interactive Calls to Pages” on page 2-199
• “Methods to Set and Get Widget Contents” on page 2-203

2.7.109 Configure Method

This section contains the following reference page:

• configure() on page 2-166

2.8 configure()

Purpose
Calls other methods to set up a VT page

Category
Predefined method

Syntax
configure() is also {configuration-code};

Syntax example:
configure() is also {set_window_kind(PACKET_VIEWER_WINDOW);};

Description
This is an empty method that you fill in with code to set up a VT page object. You fill the method with
calls to other VT page predefined methods to achieve the desired behavior of the VT page.

This method can only be called before the page is displayed.

2-166 Specman Beta Features

 Using the Visualization Toolkit
configure()

Example 1
The following defines a vt_page subtype of kind A_PAGE and uses the configure() method to set the
window kind, file content and page title.
extend vt_window_kind: [A_WINDOW];
extend vt_page_kind: [A_PAGE];

extend A_PAGE vt_page {

configure() is also {
set_window_kind(A_WINDOW);
set_file(".");
set_title("Packet");
};
};

Example 2
The following defines a vt_page subtype of kind A_PAGE without setting the window kind. The page
will be opened in the default ANY_WINDOW window.
extend vt_page_kind: [A_PAGE];

//The page definition

extend A_PAGE vt_page {
configure() is also {
set_file(".");
};
};
// The page is opened in the default ANY_WINDOW window
struct top {
run() is also {
var a_page: A_PAGE vt_page = new;
a_page.show();
};
};
extend sys {top};

Example 3
The following creates a vt_page subtype of kind A_PAGE without using the configure method.
extend vt_window_kind: [A_WINDOW];
extend vt_page_kind: [A_PAGE];

// Create the page

struct top {

Specman Beta Features 2-167

Using the Visualization Toolkit
Methods to Set Page Attributes

run() is also {
var a_page := new A_PAGE vt_page with {
.set_window_kind(A_WINDOW);
.set_file(".");
};
a_page.show()
};
};
extend sys {top};

Example 4
The following creates a default vt_page without defining a page subtype (and without using the
configure method).

The default ANY_PAGE subtype is used.

extend vt_window_kind: [A_WINDOW];
struct top {
run() is also {
var a_page: vt_page = new;
a_page.set_file(".");
a_page.set_window_kind(A_WINDOW);
a_page.show();
};
};
extend sys {top};

2.8.1 Methods to Set Page Attributes

This section contains the following reference pages:

• set_window_kind() on page 2-168

• set_title() on page 2-170

2.8.2 set_window_kind()

Purpose
Set the window kind for the page

2-168 Specman Beta Features

 Using the Visualization Toolkit
set_window_kind()

Category
Predefined method

Syntax
vt-page.set_window_kind(window-kind: vt_window_kind)

Syntax example:
set_window_kind(PACKET_VIEWER_WINDOW);

Parameters

window-kind The window kind enumerated value to set this page to.

Description
This method sets the VT page to the specified vt_window_kind. The vt_window_kind is an enumerated
value specified in the window’s kind field.

This method can only be called before the page is displayed.

Example 1
The following example creates a vt_page subtype of kind A_PAGE. The configure() method is used to
set the window kind to A_WINDOW.
extend vt_window_kind: [A_WINDOW];
extend vt_page_kind: [A_PAGE];

extend A_PAGE vt_page {

configure() is also {
set_window_kind(A_WINDOW);
};
};

Example 2
The following example creates a vt_page subtype of kind A_PAGE and sets the window kind to
A_WINDOW before the page is displayed, without using the configure() method.
extend vt_window_kind: [A_WINDOW];

Specman Beta Features 2-169

Using the Visualization Toolkit
set_title()

extend vt_page_kind: [A_PAGE];

var a_page: A_PAGE vt_page = new;

a_page.set_window_kind(A_WINDOW);

Example 3
The following example creates a vt_page subtype of kind A_PAGE without setting the window kind.
The page will be opened in the default ANY_WINDOW window.
extend vt_page_kind: [A_PAGE];

var a_page: A_PAGE vt_page = new;

a_page.set_file("~");
a_page.show();

2.8.3 set_title()

Purpose
Set the title of the page

Category
Predefined method

Syntax
vt-page.set_title(title: string)

Syntax example:
set_title("Packet Data Page");

Parameters

title The title you want to give to the page.

2-170 Specman Beta Features

 Using the Visualization Toolkit
Methods to Set Page Contents

Description
This method sets the title for the VT page.

This method can only be called before the page is displayed.

Example
The following example defines a vt_page subtype of kind A_PAGE and sets the page title to be “My
Page”.
extend A_PAGE vt_page {
configure () is also {
set_title("My Page");
};
};

See Also
• set_title_prefix() on page 2-131

2.8.4 Methods to Set Page Contents

This section contains the following reference pages:

• set_url() on page 2-171

• set_file() on page 2-172
• set_anchor() on page 2-175
• set_html_body() on page 2-176

2.8.5 set_url()

Purpose
Set the URL for the file for the page

Category
Predefined method

Specman Beta Features 2-171

Using the Visualization Toolkit
set_file()

Syntax
vt-page.set_url(url: string)

Syntax example:
set_url("top.html");

Parameters

url The name of the file this page displays

Description
This method specifies the URL of the file the VT page will display. VT cannot open a web URL, so an
error is issued if you use a web URL.

This method can only be called before the page is displayed.

Example
The following example defines a vt_page subtype and sets the page content to be a URL.
extend A_PAGE vt_page {
configure () is also {
set_url("file:/proj/specman/my_file.html#my_anchor");
};
};

2.8.6 set_file()

Purpose
Set the file for the page

Category
Predefined method

2-172 Specman Beta Features

 Using the Visualization Toolkit
set_file()

Syntax
vt-page.set_file(file-name: string)

Syntax example:
set_file("packet.html");

Parameters

file-name The name of the file for the page. Do not use an empty string, ““, or
NULL.

Description
This method specifies the name of the file to display on this VT page. The file can be of type HTML,
text, image, directory, and so on.

This method can only be called before the page is displayed.

Example 1
The following example defines a vt_page subtype and sets the page content to be an HTML file. The full
file name is supplied.
extend A_PAGE vt_page {
configure () is also {
set_file("/proj/specman/my_file.html");
};
};

Example 2
The following example defines a vt_page subtype and sets the page content to be an HTML file. A
relative file name along SPECMAN_PATH is supplied.
extend A_PAGE vt_page {
configure () is also {
set_file("my_file.html");
};
};

Specman Beta Features 2-173

Using the Visualization Toolkit
set_file()

Example 3
The following example defines a vt_page subtype and sets the page content to be e file. Assume that
“e/my_file.e” is on SPECMAN_PATH.
extend A_PAGE vt_page {
configure () is also {
set_file("e/my_file.e");
};
};

Example 4
The following example defines a vt_page subtype and sets the page content to be an the current
directory.
extend A_PAGE vt_page {
configure () is also {
set_file(".");
};
};

Example 5
The following example defines a vt_page subtype and sets the page content to be an image. Assume that
“images/icon_red.gif” is on SPECMAN_PATH.
extend A_PAGE vt_page {
configure () is also {
set_file("images/icon_red.gif");
};
};

Example 6
The following example defines a vt_page subtype and sets the page content to be a template file.
Assume that “my_template.html” is on SPECMAN_PATH.
extend A_PAGE vt_page {
configure () is also {
set_file(vt.template_to_html("my_template.html");
};
};

2-174 Specman Beta Features

 Using the Visualization Toolkit
set_anchor()

2.8.7 set_anchor()

Purpose
Set the anchor for an HTML page

Category
Predefined method

Syntax
vt-page.set_anchor(anchor: string)

Syntax example:
set_anchor("Title");

Parameters

anchor The HTML anchor for the page

Description
This method sets the HTML anchor for the VT page. The HTML page will open on the anchor you
specified as the anchor parameter.

This method must be used in conjunction with set_file() on page 2-172 or set_html_body() on page
2-176.

This method can only be called before the page is displayed.

Example
The following example defines a vt_page subtype and sets the page content to be an HTML file with an
anchor named “my_anchor” as the starting page location.
extend A_PAGE vt_page {
configure() is also {
set_file("my_file.html");
set_anchor("my_anchor");
};

Specman Beta Features 2-175

Using the Visualization Toolkit
set_html_body()

};

2.8.8 set_html_body()

Purpose
Set the body of the HTML

Category
Predefined method

Syntax
vt-page.set_html_body(body: list of string)

Syntax example:
set_html_body(sys.packet_viewer.create_packet_details_html_body(pkt));

Parameters

body A list of strings that specify the body of the HTML.

Description
This method sets the body of the HTML. When the VT page is open, VT completes the wrapping of
HTML code according to the title, background, foreground, and so on, and will create a new HTML file.
That new file is displayed in the VT window.

The list of strings can be created using text expansion constructs and VT template methods. See “Using
Text Expansion Constructs” on page 2-49.

This method can only be called before the page is displayed.

Example 1
The following example defines a vt_page subtype and sets the page content to be a list of string that
shows the packet details.

2-176 Specman Beta Features

 Using the Visualization Toolkit
set_html_body()

struct vt_packet {
kind: [good, bad];
%addr: uint (bits: 2);
%len: uint (bits: 6);
%data: list of byte;
%parity: byte;
};
struct packet_viewer {
create_packet_details_html_body(pkt: vt_packet): list of string is {
// Print the header of the page
result.add(append("Packet details: ", pkt));
result.add("");
if (pkt == NULL) {
return result;
};

// Print the details

var pkt_name: string = vt.instance_to_string(pkt);
var pkt_link: string = vt.lnk_instance(pkt, pkt_name);
var data_ls: list of string = pkt.data.apply(it.as_a(string));
var data_str: string = str_join(data_ls, " ");

result.add(append("Name: ", pkt_link));

result.add(append("kind: ", pkt.kind));
result.add(append("%addr ", pkt.addr));
result.add(append("%len ", pkt.len));
result.add(append("%data ", data_str));
result.add(append("%parity ", pkt.parity));
};
};

Example 2
The following example creates a list of string that contains the HTML body by using the inline text
expansion expression “<<#:”.
create_html_body(): list of string is {
var lines: list of string = <<#:
<center><h3>Simple VT Page</h3></center>
<(vt.btn_command("print %_page", "print page"))>
end #;
result = lines;
};

Specman Beta Features 2-177

Using the Visualization Toolkit
set_html_body()

Example 3
The following example creates a list of string that contains the HTML body by using the file expansion
expression “<< from-file”.
create_html_body(): list of string is {
var lines: list of string;
lines.add(<< my_template.e);
result = lines;
};

Example 4
The following example creates the HTML body from the result of expanding the lines in a file, in the
context of the current instance.

Assume that there is a file named “header.txt”:

// --
// File: <(file-name)>
// Author: <(author)>
// Description: <(description)>
// --

Also assume that there is a struct named “file_details”:

struct file_details {
file_name: string;
author: string;
description: string;
}

The page definition is:

extend A_PAGE vt_page {
configure() is also {
var details := new file_details with {
.file_name = "myfile.e";
.author = "eMike";
.description = "This is a small e file";
};
set_html_body(set_html_body(vt.expand_file("header.txt", details));
};
};

2-178 Specman Beta Features

 Using the Visualization Toolkit
Methods to Display Pages

2.8.9 Methods to Display Pages

This section contains the following reference pages:

• show() on page 2-179

• show_in_new_window() on page 2-180

2.8.10 show()

Purpose
Display the page

Category
Predefined method

Syntax
vt-page.show()

Syntax example:
show();

Description
This method displays the VT page in an existing window, if possible. Otherwise, it displays the page in
a new window.

This method can only be called before the page is displayed.

Example
// The page definition
extend A_PAGE vt_page (
configure() is also {
set_file("my_file.html");
};
};

// Show the page

Specman Beta Features 2-179

Using the Visualization Toolkit
show_in_new_window()

var a_page: A_PAGE vt_page = new;

a_page.show();

2.8.11 show_in_new_window()

Purpose
Display the page in a new window

Category
Predefined method

Syntax
vt-page.show_in_new_window()

Syntax example:
show_in_new_window();

Description
This method creates a new VT window and displays the VT page on top of that window.

This method can only be called before the page is displayed.

Example
The following example defines a vt_page subtype and shows the page in a new window.
// The page definition
extend A_PAGE vt_page (
configure() is also {
set_file("my_file.html");
set_title("My e file");
};
};

// Show the page in a new window

var a_page: A_PAGE vt_page = new;

2-180 Specman Beta Features

 Using the Visualization Toolkit
Methods to Display Page Status

a_page.show_in_new_window();

2.8.12 Methods to Display Page Status

This section contains the following reference pages:

• is_pre_opened() on page 2-181

• is_opened() on page 2-182
• is_current() on page 2-183
• is_closed() on page 2-184

2.8.13 is_pre_opened()

Purpose
Show whether the page is created but not open

Category
Predefined method

Syntax
vt-page.is_pre_opened():bool

Syntax example:
var pre_opened: bool;
pre_opened = is_pre_opened();

Description
This method returns TRUE if the VT page has been created but not opened yet, or returns FALSE if the
VT page has opened.

Specman Beta Features 2-181

Using the Visualization Toolkit
is_opened()

Example
The following example checks whether a page is unopened, and if so sets the window kind and page
title.
var unopened: bool = a_page.is_pre_opened();
if (unopened) {
a_page.set_window_kind(A_WINDOW);
a_page.set_title("My Page");
};

2.8.14 is_opened()

Purpose
Show whether the page is already open

Category
Predefined method

Syntax
vt-page.is_opened(): bool

Syntax example:
var opened: bool;
opened = is_opened();

Description
This method returns TRUE if the VT page has been opened, or FALSE if the VT page has not been
opened.

Example
The following example checks whether a page is open, and if so prints the actual file name and locks the
page.
var open: bool = a_page.is_opened();

2-182 Specman Beta Features

 Using the Visualization Toolkit
is_current()

if (open) {
print a_page.get_file_name();
a_page.set_locked(TRUE);
};

2.8.15 is_current()

Purpose
Show whether the page is open and is the current page

Category
Predefined method

Syntax
vt-page.is_current():bool

Syntax example:
var current: bool;
current = is_current();

Description
This method returns TRUE if the VT page is open and is the current page in the containing VT window.

Example
The following example checks whether a page is the current page, and if so sets the text in a text field
named “text1” to the value “sys”, and finds the text “packet” on that page.
var current: bool = a_page.is_current();
if (current) {
a_page.set_widget_value("text1", "sys");
a_page.find("packet");
};

Specman Beta Features 2-183

Using the Visualization Toolkit
is_closed()

2.8.16 is_closed()

Purpose
Show whether the window is closed

Category
Predefined method

Syntax
vt-page.is_closed(): bool

Syntax example:
var closed: bool;
closed = is_closed();

Description
This method returns TRUE if the containing VT window is closed, or FALSE if the window is not
closed.

Example
The following example checks whether a page is closed, and if so prints details about the window.
var closed: bool = a_page.is_closed();
if (closed) {
var a_window: vt_window = a_page.get_window();
out("The following window is closed: ",
vt.instance_to_string(a_window)
);
};

2.8.17 Methods to Display Page Information

This section contains the following reference pages:

• get_window_kind() on page 2-185

2-184 Specman Beta Features

 Using the Visualization Toolkit
get_window_kind()

• get_kind() on page 2-186

• get_id() on page 2-187
• get_requested_url() on page 2-188
• get_requested_file() on page 2-189
• get_requested_anchor() on page 2-191
• get_requested_html_body() on page 2-192
• get_title() on page 2-193
• get_window() on page 2-194

2.8.18 get_window_kind()

Purpose
Display the window kind

Category
Predefined method

Syntax
vt-page.get_window_kind(): vt_window_kind

Syntax example:
var a_kind: vt_window_kind;
a_kind = a_page.get_window_kind();

Description
This method returns the VT window kind of the VT page.

This method can be called at any time except after the window is closed.

Specman Beta Features 2-185

Using the Visualization Toolkit
get_kind()

Example
The following example gets all pages that are displayed in a window ofkind A_WINDOW. For each
such page the title is printed.
var pages: list of vt_page;
pages = vt.get_all_pages().all(.get_window_kind() == A_WINDOW);

for each (page) in pages do {

print page.get_title();
};

2.8.19 get_kind()

Purpose
Display the page kind

Category
Predefined method

Syntax
vt-page.get_kind( ): vt_page_kind

Syntax example:
var a_kind: vt_page_kind;
a_kind = a_page.get_kind()

Description
This method returns the VT page kind. The kind is determined by the setting of the enumerated kind
field in current instance of the vt_page struct.

This method can be called at any time except after the window is closed.

2-186 Specman Beta Features

 Using the Visualization Toolkit
get_id()

Example
The following example gets all pages of kind A_PAGE and title “VT page” displayed in a specific VT
window. For each such page the actual file name is printed.
var pages: list of vt_page;
pages = a_window.get_all_pages().all(.get_kind() == A_PAGE and
.get_title() == "VT page");

for each (page) in pages do {

print page.get_file_name();
};

2.8.20 get_id()

Purpose
Display the page ID

Category
Predefined method

Syntax
vt-page.get_id(): string

Syntax example:
var id: string;
id = get_id();

Description
This method returns the unique ID of the VT page. The ID is set by VT.

This method can be called at any time except after the window is closed.

Example
The following example prints the current page ID.

Specman Beta Features 2-187

Using the Visualization Toolkit
get_requested_url()

var current_page_id: string = a_window.get_current_page().get_id();

print current_page_id;
};

2.8.21 get_requested_url()

Purpose
Display the URL of the page

Category
Predefined method

Syntax
vt-page.get_requested_url(): string

Syntax example:
var url: string;
url = get_requested_url();

Description
This method returns the URL set by set_url() on page 2-171 for the current VT page.

The URL returned by this method might be different from the URL returned by get_url() on page 2-195.
For example, if you request that VT open a page with a URL that is not found along SPECMAN_PATH,
then VT sets the actual URL of that page to be that of a special url_not_found file that VT creates.

Relative files along SPECMAN_PATH become full-path URLs. The current anchor is also kept in
get_anchor() on page 2-197.

This method can be called at any time except after the window is closed.

Example 1
The following example creates a VT page and sets the URL (which is an HTML file with an anchor). It
then prints the requested URL.
// The page definition

2-188 Specman Beta Features

 Using the Visualization Toolkit
get_requested_file()

extend A_PAGE vt_page {

configure() is also {
set_url("file:/proj/specman/my_file.html#my_anchor");
};
};

// Open the page

var a_page: A_PAGE vt_page = new;
a_page.show();

// Print the requested URL. It should be

// "file:/proj/specman/my_file.html#my_anchor"
print a_page.get_requested_url();
};

Example 2
The following example checks whether the requested URL of a page is the same as the actual URL
shown in that page.
var requested_url: string = a_page.get_requested_url();
var actual_url: string = a_page.get_url();

if (requested_url != actual_url) then {

print "The requested URL is different from the actual URL";
};

2.8.22 get_requested_file()

Purpose
Display the file name for the page

Category
Predefined method

Syntax
vt-page.get_requested_file(): string

Syntax example:

Specman Beta Features 2-189

Using the Visualization Toolkit
get_requested_file()

var filename: string;

filename = get_requested_file();

Description
This method returns the filename set by set_file() on page 2-172 for the current VT page.

The file returned by this method might be different from the file returned by get_file() on page 2-196.
For example, if you request that VT open a page with a file that is not found along SPECMAN_PATH,
then VT sets the actual file of that page to be that of a special file_not_found file that VT creates.

Relative files along SPECMAN_PATH become full-path URLs. The current anchor is also kept in
get_anchor() on page 2-197.

This method can be called at any time except after the window is closed.

Example 1
The following example creates a VT page containing an e file, then it prints the requested file name.
Assume that the file named “my_file.e” is in the directory named “/proj/specman”.
// The page definition
extend A_PAGE vt_page {
configure() is also {
set_file("my_file.e");
};
};

// Open the page

var a_page: A_PAGE vt_page = new;
a_page.show();

// Print the requested file. It should be

// "/proj/specman/my_file.e"
print a_page.get_requested_file();
};

Example 2
The following example gets the requested VT page file and checks whether it is an HTML file.
var requested_file: string = a_page.get_requested_file();

if (requested_file ~ "/[.]htm[l]?$/") then {

print "The requested file is an HTML file";

2-190 Specman Beta Features

 Using the Visualization Toolkit
get_requested_anchor()

};

2.8.23 get_requested_anchor()

Purpose
Display the anchor name

Category
Predefined method

Syntax
vt-page.get_requested_anchor(): string

Syntax example:
var an_anchor:string;
an_anchor = get_requested_anchor();

Description
This method returns the anchor name set by set_anchor() on page 2-175 for the current VT page.

The anchor returned by this method might be different from the anchor returned by get_anchor() on
page 2-197. For example, if you request that VT open a page with an anchor that is not found along
SPECMAN_PATH, then VT sets the actual anchor of that page to be that of a special anchor_not_found
file that VT creates.

Relative files along SPECMAN_PATH become full-path URLs. The current anchor is also kept in
get_anchor() on page 2-197.

This method can be called at any time except after the window is closed.

Example
The following example creates a VT page with HTML content and a specific anchor location.
// The page definition
extend A_PAGE vt_page {

Specman Beta Features 2-191

Using the Visualization Toolkit
get_requested_html_body()

configure() is also {
set_file("my_file.html");
set_anchor("my_anchor");
};
};

// Open the page

var a_page: A_PAGE vt_page = new;
a_page.show();

// Print the requested anchor. It should be "my_anchor"

print a_page.get_requested_anchor();

2.8.24 get_requested_html_body()

Purpose
Display the HTML body

Category
Predefined method

Syntax
vt-page.get_requested_html_body(): list of string

Syntax example:
body: list of string;
body = get_requested_html_body();

Description
This method returns the HTML body set by set_html_body() on page 2-176 for the current VT page.

This method can be called at any time except after the window is closed.

Example
The following example gets the requested HTML body and prints it.

2-192 Specman Beta Features

 Using the Visualization Toolkit
get_title()

var requested_html_body: list of string;

requested_html_body = a_page.get_requested_html_body();

print requested_html_body;

2.8.25 get_title()

Purpose
Display the page title

Category
Predefined method

Syntax
vt-page.get_title(): string

Syntax example:
var title: string;
title = get_title();

Description
This method returns the title of the VT page.

This method can be called at any time except after the window is closed.

Example
The following example gets the page title and the window title prefix, and prints the full window title.
var title: string = a_page.get_title();
var title_prefix: string = a_page.get_window().get_title_prefix();
var full_title: string = append(title_prefix, " ", title);

out("The VT window full title is: ", full_title);

Specman Beta Features 2-193

Using the Visualization Toolkit
get_window()

2.8.26 get_window()

Purpose
Display the window the page is bound to

Category
Predefined method

Syntax
vt-page.get_window(): vt_window

Syntax example:
a_page.get_window().to_front();

Description
This method returns the VT window the current page is displayed in.

This method can be called at any time except after the window is closed.

Example
The following example opens a VT page and uses the get_window() method of that page to disable a
user-defined window action.
// The window definition
extend A_WINDOW vt_window {
configure() is also {
// Add a user-defined menu command
add_menu_item("show", "show sys", "open data browser on sys‘”, show
data sys");
};
};

// The page definition

extend A_PAGE vt_page {
configure() is also {
set_file(".");
set_window_kind(A_WINDOW);

2-194 Specman Beta Features

 Using the Visualization Toolkit
Methods to Display the Page Contents

};
};

// Open the page

var a_page: A_PAGE vt_page = new;

// Get the window

var a_window: vt_window = a_page.get_window();

// Disable the "show sys" action

a_window.enable_action("show sys", FALSE);

2.8.27 Methods to Display the Page Contents

This section contains the following reference pages:

• get_url() on page 2-195

• get_file() on page 2-196
• get_anchor() on page 2-197
• get_actual_html_body() on page 2-198

2.8.28 get_url()

Purpose
Display the URL of the page

Category
Predefined method

Syntax
vt-page.get_url(): string

Syntax example:
a_page.set_url(a_second_page.get_url());

Specman Beta Features 2-195

Using the Visualization Toolkit
get_file()

Description
This method returns the URL of the VT page.

This method can only be called after the page is opened.

Example
The following example prints the actual URL of an open VT page. Assume that we have an HTML file
named “my_file.html” under “/proj/specman”.
// Create the VT page
var a_page: A_PAGE vt_page = new;
a_page.set_file("my_file.html");
a_page.set_anchor("my_anchor");
a_page.show();

// Jump to anchor "my_anchor"

a_page.go_to_anchor("my_anchor", FALSE, "");

// Print the URL. It should be "file:/proj/specman/my_file.html#my_anchor"

print a_page.get_url();

2.8.29 get_file()

Purpose
Display the file name for the page

Category
Predefined method

Syntax
vt-page.get_file(): string

Syntax example:
var filename: string;
filename = get_file();

2-196 Specman Beta Features

 Using the Visualization Toolkit
get_anchor()

Description
This method returns the name of the file for the VT page.

This method can only be called after the page is opened.

Example
The following example pirnts the actual file name of an open VT page.
// Create the VT page
var a_page: A_PAGE vt_page = new;
a_page.set_file("/proj/specman/");
a_page.show();

// Print the actual file/directory name. It should be "/proj/specman"

print a_page.get_file_name();

2.8.30 get_anchor()

Purpose
Display the anchor location of the page

Category
Predefined method

Syntax
vt-page.get_anchor(): string

Syntax example:
var an_anchor: string;
an_anchor = get_anchor();

Description
This method returns the current anchor location of the VT page.

This method can only be called after the page is opened.

Specman Beta Features 2-197

Using the Visualization Toolkit
get_actual_html_body()

Example
The following example prints the actual anchor name of an open VT page.
// Create the VT page
var a_page: A_PAGE vt_page = new;
a_page.set_file("my_file.html");
a_page.set_anchor("my_anchor");
a_page.show();

// Print the actual anchor name. It should be "my_anchor"

print a_page.get_anchor();

2.8.31 get_actual_html_body()

Purpose
Display the HTML body of the Page

Category
Predefined method

Syntax
vt-page.get_actual_html_body(): list of string
Syntax example:body: list of string;
body = a_page.get_actual_html_body();

Description
This method returns the HTML body of the current VT page.
The HTML body is defined as all the content between the HTML <body> and </body> tags.
Unlike the get_requested_html_body() method that will return the HTML body only if you use the
set_html_body() nethod, this method will return the HTML body for all HTML pages (no matter how
you set the page content).

This method can be called only on the current VT page.

Note This method is relevant for HTML pages only.

2-198 Specman Beta Features

 Using the Visualization Toolkit
Interactive Calls to Pages

Example
The following example gets the actual HTML body and prints it.
var a_page: A_PAGE vt_page = new;
a_page.set_file("my_file.html");
page.show();

var html_body: list of string;

html_body = a_page.get_actual_html_body();

print html_body;

2.8.32 Interactive Calls to Pages

This section contains the following reference pages:

• find() on page 2-199

• find_by() on page 2-200
• go_to_anchor() on page 2-201

2.8.33 find()

Purpose
Find text in the page

Category
Predefined method

Syntax
vt-page.find(text: string)

Syntax example:
find("packet name");

Specman Beta Features 2-199

Using the Visualization Toolkit
find_by()

Parameters

text The text to search for.

Description
This method searches the VT page for the stated text, and highlights it.

This method can only be called when the page is the current page in the window.

Example
The following example searches the file “my_file.e” for the text “packet” in the current page, “a_page”.
// Create the VT page
var a_page: A_PAGE vt_page = new;
a_page.set_file("my_file.e");
a_page.show();

// Find the text "packet" (all occurrences, partial, and not case sensitive)
a_page.find("packet");

2.8.34 find_by()

Purpose
Find text in the page

Category
Predefined method

Syntax
vt-page.find_by(text: string, first-only: bool, whole: bool, case-sensitive: bool)

Syntax example:
find_by("Packets", TRUE, FALSE, TRUE);

2-200 Specman Beta Features

 Using the Visualization Toolkit
go_to_anchor()

Parameters

text The text to search for.

first-only Find only the first occurrence of the text.

whole Find only the entire text, disregarding partial occurrences.

case-sensitive Do a case-sensitive search.

Description
This method searches for text in the page, using the specified search parameters, and hightlights it.

This method can only be called when the page is the current page in the window.

Example 1
The following example searches the current page, “a_page”, for the first occurrence of the text “packet”,
finding only the entire text, and not case sensitive.
// Create the VT page
var a_page: A_PAGE vt_page = new;
a_page.set_file("my_file.e");
a_page.show();

// Find the text "packet" (first occurrence, whole text, not case sensitive)
a_page.find("packet");

Example 2
The following example searches the current page of window “a_window”, for all occurrences of the text
“packet”, finding partial text and case sensitive.
// Find the text "packet" (all occurrences, partial text, case sensitive)
a_page.get_current_page().find_by("packet", FALSE, FALSE, TRUE);

2.8.35 go_to_anchor()

Purpose
Go to the anchor and search for text

Specman Beta Features 2-201

Using the Visualization Toolkit
go_to_anchor()

Category
Predefined method

Syntax
vt-page.go_to_anchor(anchor-name: string, mark: bool, text: string): string

Syntax example:
var an_anchor: string;
an_anchor = go_to_anchor("anch1", TRUE, "packets");

Parameters

anchor-na The anchor to go to.

me

mark Enter TRUE to mark the text string, if it is found.

text The text to mark, if mark is TRUE.

Description
This method goes to the specified anchor, and marks the specified text that follows the anchor if the
mark option is TRUE.

This method can only be called when the page is the current page in the window.

Example 1
The following example jumps to an anchor named “my_anchor” inside an HTML page named
“my_file.html” and marks no text following the anchor.
// Create the VT page
var a_page: A_PAGE vt_page = new;
a_page.set_file("my_file.html");
a_page.show();

// Jump to anchor "my_anchor” in the current page

a_page.go_to_anchor("my_anchor", FALSE, "");

2-202 Specman Beta Features

 Using the Visualization Toolkit
Methods to Set and Get Widget Contents

Example 2
The following example jumps to an anchor named “my_anchor_1” inside an HTML page named
“my_file.html”, and marks the text “packet” following the anchor.
// Jump to anchor "my_anchor_1" in the current page and mark text "packet"
a_page.go_to_anchor("my_anchor_1", TRUE, "packet");

Example 3
The following example jumps to an anchor named “my_anchor_2” inside an HTML page named
“my_file.html” and marks the first word following the anchor.
// Jump to anchor "my_anchor_2" in the current page and mark the first
// word following the anchor
a_page.go_to_anchor("my_anchor_2", TRUE, "");

2.8.36 Methods to Set and Get Widget Contents

This section contains the following reference pages:

• set_widget_value() on page 2-203

• get_widget_value() on page 2-205
• set_widget_items() on page 2-206
• get_widget_items() on page 2-207

2.8.37 set_widget_value()

Purpose
Set the value of a widget

Category
Predefined method

Syntax
vt-page.set_widget_value(name: string, value: string)

Specman Beta Features 2-203

Using the Visualization Toolkit
set_widget_value()

Syntax example:
set_widget_value("anch", "first");

Parameters

name The name of the HTML widget.

value The value to set the widget to.

Description
This method sets the value of an HTML widget.

This method can only be called when the page is the current page in the window.

Example
The following example changes the values of several HTML widgets inside the current page.
var a_page: A_PAGE vt_page = new

// Create the HTML widgets

var lst_html: list of string;
lst_html.add(vt.inp_textfield("text-1", "", 20))
lst_html.add(vt.inp_combobox("combo-1", {"green"; "red"; "blue"}, "red"));
lst_html.add(vt.inp_checkbox("check-1", FALSE);

// Open the page

a_page.set_html_body(lst_html);
a_page.show();

// Set the value of the text field named "text-1" to be "packet-@1"

a_page.set_widget_value("text-1", "packet-@1");

// Set the selected value of the combo box named "combo-1" to be "green”
a_page.set_widget_value("combo-1", "green");

// Set the value of the check box named "check-1" to be TRUE (selected)
a_page.set_widget_value("check-1", TRUE);

2-204 Specman Beta Features

 Using the Visualization Toolkit
get_widget_value()

2.8.38 get_widget_value()

Purpose
Display the value of a widget

Category
Predefined method

Syntax
vt-page.get_widget_value(name: string): string

Syntax example:
var s: string;
s = a_page.get_widget_value("a_button");

Parameters

name The name of the widget.

Description
This method returns the value of an HTML widget.

This method can only be called when the page is the current page in the window.

Example
Assume we have the following template file, named “my_template.html”, along SPECMAN_PATH:
<(vt.inp_textfield("text-1", "packet", 20))>
<(vt.inp_combobox("combo-1", {"green"; "red"; "blue"}, "red"))>
<(vt.inp_checkbox("check-1", TRUE))>

The following opens a VT page with the template file and prints the values of several HTML widgets
inside the page.
var a_page: A_PAGE vt_page = new;
a_page.set_file(vt.template_to_html(my_template.html));

Specman Beta Features 2-205

Using the Visualization Toolkit
set_widget_items()

a_page.show();

// Print the value of the text field named "text-1"

print a_page.get_widget_value("text-1");

// Print the selected value of a combo box named "combo-1"

print a_page.get_widget_value("combo-1");

// Print the value of the check box named "check-1"

print a_page.get_widget_value("check-1");

2.8.39 set_widget_items()

Purpose
Set the items of a widget.

Category
Predefined method

Syntax
vt_page.set_widget_items(name: string, items: list of string)

Syntax example:
a_page.set_widget_items("list1", {"red";"green";"blue"});

Parameters

name The name of the widget

items The items to be set in the widget

Description
Sets the items of an HTML widget. The widgets that support this method are list box and combo box.

This method can only be called when the page is the current page.

2-206 Specman Beta Features

 Using the Visualization Toolkit
get_widget_items()

Example
var a_page: A_PAGE vt_page = new;
var lst_html: list of string;
var list_code: string = vt.inp_listbox("list1", "print 5", {"A";"B";"C"},
"C", 8, 10, TRUE, "");
lst_html.add(list_code);
a_page.set_html_body(lst_html);
a_page.show();

//set new items in the list

a_page.set_widget_items("list1", {"RED";"GREEN";"BLUE"});

2.8.40 get_widget_items()

Purpose
Get the items of a widget.

Category
Predefined method

Syntax
vt_page.get_widget_items(name: string)

Syntax example:
var items: string = a_page.get_widget_items("combo1");

Parameters

name The name of the widget

Description
Gets the items of an HTML widget. The widgets that support this method are list box and combo box.

This method can only be called when the page is the current page.

Specman Beta Features 2-207

Using the Visualization Toolkit
Backward Compatibility with Previous Releases

Example
var a_page: A_PAGE vt_page = new;
var lst_html: list of string;
var list_code: string = vt.inp_combobox("combo1", {"A";"B";"C"}, "A");
lst_html.add(list_code);
a_page.set_html_body(lst_html);
a_page.show();

//get the items in the combo box

a_page.get_widget_items("combo1");

2.9 Backward Compatibility with Previous Releases

Code writting for early beta releases of Visualization Toolkit will continue to work in the new VT
release, but some modifications are helpful to take advantage of new VT features. Those modifications
are described in this section.

This section contains the following topics:

• “Changed VT Concepts and Terminology” on page 2-208

• “Modifications Needed in New VT Code” on page 2-208
• “Deprecated VT Methods” on page 2-210

2.9.1 Changed VT Concepts and Terminology

The term “VT object” is used more specifically in this release than in the first VT release, to mean an
instance of the built-in vt struct.The more general term “VT Manager” is used in this release except
when vt object is specifically intended.

In the first VT release, the window category affected window reuse decisions made by VT. In this
release, “window kind” is used instead of “window category”. The window kind affects not only
window reuse decisions, but also defines the characteristics of new windows (all of the characteristics
that can be specified using the configure() method, such as menus, toolbars, symbols, and so on).

2.9.2 Modifications Needed in New VT Code

Table 2-4 shows modifications that are needed in old VT code to get the benefit of the new VT release.

2-208 Specman Beta Features

 Using the Visualization Toolkit
Modifications Needed in New VT Code

Table 2-4 VT Code Modifications for Compatibility

Method Changes in User Code

vt.open_file() Change category to window-kind:

Old:
open_file(file-name, category, f_new)

New:
open_file(file-name, window-kind, f_new)

vt.show_file() Change category to window-kind:

Old:
show_file(file-name, category)

New:
show_file(file-name, window-kind)

vt.open_template() Change category to window-kind:

Old:
open_template(templ, category, f_new)

New:
open_template(templ, window-kind, f_new)

vt.show_template() Change category to window-kind:

Old:
show_template(templ, category)

New:
show_template(templ, window-kind)

Specman Beta Features 2-209

Using the Visualization Toolkit
Deprecated VT Methods

Table 2-4 VT Code Modifications for Compatibility (continued)

Method Changes in User Code

VT window Create a vt_window subtype instead of calling vt_window methods after

configuration opening a window.

Old:
if (not win.is_visible()) {
win.set_size(700, 400);
win.add_menu_item("Calc", ...)
};

New:
extend VMP_WINDOW vt_window {
configure() is also {
set_size(700, 400);
add_menu_item("Calc", ...);
set_title_prefix("VMP");
};
};

2.9.3 Deprecated VT Methods

This section contains reference pages for predefined methods that were included in the first VT beta
release, but are no longer available in this release. This information is provided for the purpose of
supporting backward compatibility with releases prior to Specman 4.2b3 (Beta 3). The methods
described here should not be used in newly written e code.

The methods in this section are:

• open_file() on page 2-211

• show_file() on page 2-212
• open_template() on page 2-213
• show_template() on page 2-215
• lnk_file() on page 2-215
• lnk_template() on page 2-216
• btn_file() on page 2-217
• btn_template() on page 2-218
• is_alive() on page 2-219

2-210 Specman Beta Features

 Using the Visualization Toolkit
open_file()

• set_visible() on page 2-220

2.9.4 open_file()

Purpose
Show window using a file

Category
Predefined method

Syntax
vt.open_file(file-name: string, window-kind: string, new-win: boolean): vt_window

Syntax example:
var handle: vt_window;
handle = vt.open_file("rank_appl/rank.html", "rank", FALSE);

Parameters

file-name The name of the file or directory to open. The file can be an HTML file, a
text file, or a directory name. This file is displayed inside the VT window
page area. If the file is not found, an error is issued.

Note The name of the file is package relative. In other words, it is

searched along SPECMAN_PATH. If a new window is created, the
window is active but not visible.

window-kind The kind of the VT window. If NULL, then the default “undefined”
window kind is used.

new-win Specifies whether to force creation of a new window.

Specman Beta Features 2-211

Using the Visualization Toolkit
show_file()

Description
Opens VT window (either a new window or a reused window) and displays the file specified by
file-name. If it is a new window, then it is initially hidden, or if there is no open window of that window
kind (first new window of that window kind), then it is opened hidden. The file name can be package
relative and is searched for along SPECMAN_PATH. The return value is a vt_window handle (an
instance of vt_window), that represents the graphical window.

If the file you specify points to a resource on the Web, an “Open Link in Browser” page appears,
containing a message that the requested URL can only be opened in an external browser. The original
URL is shown as a hyperlink in that page. You can click on the hyperlink to open the URL in an external
browser (your system’s designated Web browser).

Note You can also open a VT window with show_file() on page 2-212.

Example
var handle: vt_window =
vt.open_file("rank_appl/rank.html", "rank", FALSE);
if (not handle.is_visible()) {
handle.set_title("Ranking Window");
handle.set_visible(TRUE);
}
else{
// Return or issue an error
};

See Also
• open_template() on page 2-213
• show_file() on page 2-212

2.9.5 show_file()

Purpose
Open a VT window

Category
Predefined method

2-212 Specman Beta Features

 Using the Visualization Toolkit
open_template()

Syntax
vt.show_file(file-name: string, window-kind: string)

Syntax example:
vt.show_file("rank_appl/rank.html", "rank");

Parameters

file-name The name of a file or directory to open. The file can be an HTML file, a
text file, or a directory name. The file is displayed in the VT window page
area. If the file is not found, an error is issued.

Note The name of the file is package relative. In other words, it is

searched along SPECMAN_PATH. If a new window is created, the
window is active but not visible.

window-kind The kind of the VT window. If NULL, then the default “undefined” kind is
used.

Description
Opens VT window with a file, and displays it. No handle is returned.

If the file you specify points to a resource on the Web, an “Open Link in Browser” page appears,
containing a message that the requested URL can only be opened in an external browser. The original
URL is shown as a hyperlink in that page. You can click on the hyperlink to open the URL in an external
browser (your system’s designated Web browser).

The vt.show_file() method is a wrapper of vt.open_file(), using FALSE for new-win, and setting the
window to be visible immediately after it is opened (if it is a new window).

2.9.6 open_template()

Purpose
Open a VT window using a template file

Category
Predefined method

Specman Beta Features 2-213

Using the Visualization Toolkit
open_template()

Syntax
vt.open_template(file-name: string, window-kind: string, new-win: boolean): vt_window

Syntax example:
var handle: vt_window;
handle = vt.open_template("manager/manager_template.html", "manager",
FALSE);

Parameters

file-name The name of a template file.

window-kind The kind of the VT window. If window-kind is NULL, then the default
“undefined” kind is used.

new-win Specifies whether to force creation of a new window.

Description
Opens VT window using a template file, and returns a vt_window handle. If it is a new window, then it
is initially hidden.

This method is similar to vt.open_file(), but the page file is a temporary file, generated by VT out of the
given template file. This is done by Specman, which reads the template file, reparses it and generates the
final file for display in the VT window.

All parameters are the same as those of vt.open_file(), including the vt_window return value. Also, the
decision whether to create a new window or reuse one is made in the same manner.

A similar way to open VT window for a template file is by using vt.show_template().

See Also
• open_file() on page 2-211
• show_template() on page 2-215

2-214 Specman Beta Features

 Using the Visualization Toolkit
show_template()

2.9.7 show_template()

Purpose
Open a VT window

Category
Predefined method

Syntax
vt.show_template(file-name: string, window-kind: string)

Syntax example:
vt.show_template("manager/manager_template.html", "manager");

Parameters

file-name The name of a template file.

window-kind The kind of the VT window. If NULL, then the default “undefined” kind is
used.

Description
Opens a VT window using a template file, and displays it. No handle is returned.

This method is actually a wrapper of open_template() on page 2-213, using FALSE for new-win, and
setting the window to be visible immediately after it is created.

2.9.8 lnk_file()

Purpose
Make a hyperlink that shows a file

Specman Beta Features 2-215

Using the Visualization Toolkit
lnk_template()

Category
Predefined method

Syntax
vt.lnk_file(file: string, window-kind: string, text: string): string

Syntax example:
Here is the <(vt.lnk_file("work/my_config.e", "configuration e file",
"config"))>.

Parameters

file The file to show.

window-kind The window kind.

text The text for the hyperlink.

Description
Makes text a hyperlink that when clicked shows the specified file. Returns a string.

This method is implemented by nesting show_file() on page 2-212 in lnk_command() on page 2-72.

2.9.9 lnk_template()

Purpose
Make a hyperlink that generates a file from an HTML template

Category
Predefined method

Syntax
vt.lnk_template(template-file: string, window-kind: string, text: string): string

2-216 Specman Beta Features

 Using the Visualization Toolkit
btn_file()

Syntax example:
To see the SoC visualizer, click <(vt.lnk_template("atm_example/soc.html",
"sys", "here"))>.

Parameters

template-file The HTML template.

window-kind The window kind.

text The text for the hyperlink.

Description
Makes text a hyperlink that when clicked generates a file by expanding the specified template file.
Returns a string.

This method is implemented by nesting show_template() on page 2-215 in lnk_command() on page

2-72.

2.9.10 btn_file()

Purpose
Make a button that opens a file

Category
Predefined method

Syntax
vt.btn_file(file: string, window-kind: string, text: string): string

Syntax example:
Here is the <(vt.btn_file("work/my_config.e", "configuration e file",
"config"))>.

Specman Beta Features 2-217

Using the Visualization Toolkit
btn_template()

Parameters

file The file to show.

window-kind The window kind.

text The text for the button.

Description
Returns HTML code representing a button that shows a file in a VT window. Return type is string.

2.9.11 btn_template()

Purpose
Make a button to generate a file from and HTML template

Category
Predefined method

Syntax
vt.btn_template(template-file: string, window-kind: string, text: string): string

Syntax example:
To see the SoC visualizer, click <(vt.btn_template("atm_example/soc.html",
"sys", "here"))>.

Parameters

template-file The HTML template file.

window-kind The window kind.

text The text for the button.

2-218 Specman Beta Features

 Using the Visualization Toolkit
is_alive()

Description
Makes text a hyperlinked button that generates a file by expanding the specified template file. Returns a
string.

2.9.12 is_alive()

Purpose
Test whether a window is alive (has not been closed)

Category
Predefined method

Syntax
vt-window.is_alive(): bool

Syntax example:
var mybool: bool;
var a_window: vt_window;
mybool = a_window.is_alive();

Description
Once the end user opens a VT window, it is alive until it is closed. This method returns TRUE if the
window is alive or FALSE if the window has been closed.

Example
if (a_window.is_alive()) then {
a_window.set_file("myfile.html");
} else {
a_window = vt.open_file("myfile.html", "test_manager", FALSE);
};

Specman Beta Features 2-219

Using the Visualization Toolkit
set_visible()

2.9.13 set_visible()

Purpose
Show or hide a window

Category
Predefined method

Syntax
vt-window.set_visible(visible: bool)

Syntax example:
var a_window: vt_window;
a_window.set_visible(TRUE);

Parameters

visible Enter TRUE to display the window, or enter FALSE to hide the window.

Description
Makes the window visible if entered with TRUE, or hides the window if entered with FALSE.

2-220 Specman Beta Features

Index

Symbols C
<< VT text expansion constructs 2-49 check-boxes
creating 2-94
A creating groups of 2-95
clear() method syntax 2-102
add_box() method syntax 2-99 close() method syntax 2-165
add_divider() method syntax 2-100 colors
add_field_boxes() method syntax 2-101 for text 2-119
add_menu() method syntax 2-145 getting codes for 2-116
add_menu_item() method syntax 2-146 VT text 2-116
add_menu_item_to_secondary_toolbar() method combo-boxes, creating 2-92
syntax 2-155 commands
add_menu_separator() method syntax 2-148 output
add_secondary_toolbar() method syntax 2-154 showing in HTML 2-103
add_separator_to_secondary_toolbar() method configure() VT page method syntax 2-166
syntax 2-156 configure() VT window method syntax 2-125
add_toolbar_separator() method syntax 2-149
D
B
documentation
beta features, defined 1-1 conventions 1-2
btn_command() method syntax 2-82 syntax notation used in 1-3
btn_file() method syntax 2-217
btn_instance() method syntax 2-86
btn_page() method syntax 2-87
E
btn_page_with_title() method syntax 2-88 enable_action() method syntax 2-150
btn_search() method syntax 2-83 environment variables
btn_template() method syntax 2-218 SN_NEW_HELP_WIN 2-110
btn_url_in_browser() method syntax 2-85 SPECMAN_WEB_BROWSER 2-110
expand_file() method syntax 2-112

Specman Beta Features Index-1

Index

expand_file_to_file() method syntax 2-113 H

hidden controls, creating 2-97
F hide_navigation_buttons() method syntax 2-152
files HTML
opening in browsers 2-111 code, converting to HTML file 2-68
opening in VT windows 2-211 embedding files in 2-105
showing in VT windows 2-212 templates
writing contents to other files 2-113 converting to HTML code 2-67
writing contents to structs 2-112 converting to HTML files 2-66
find() method syntax 2-199 HTML files
find_by() method syntax 2-200 creating 2-51
creating buttons 2-45
G creating hyperlinks 2-44
creating input components 2-46
get_absolute_name() method syntax 2-115 creating stripe charts 2-46
get_actual_html_body() method syntax 2-198 expanding templates 2-52
get_all_pages() method syntax 2-123 text expansion constructs 2-49
get_all_windows() method syntax 2-123 html_anchor() method syntax 2-80
get_anchor() method syntax 2-197 html_body() method syntax 2-105
get_color_code() method syntax 2-116 html_command_output() method syntax 2-103
get_current_page() method syntax 2-137, 2-138 HTML_HORIZONTAL_LINE field syntax 2-71
get_file() method syntax 2-196 html_image() method syntax 2-109
get_id() method syntax 2-187 html_modules() method syntax 2-106
get_kind() method syntax 2-139, 2-186 HTML_NEWLINE field syntax 2-69
get_location() method syntax 2-141 html_report() method syntax 2-104
get_requested_anchor() method syntax 2-191 HTML_SPACE field syntax 2-70
get_requested_file() method syntax 2-189 html_stripe() method syntax 2-98
get_requested_html_body() method syntax 2-192 hyperlinks
get_requested_url() method syntax 2-188 anchors for other links 2-80, 2-93, 2-206,
get_size() method syntax 2-140 2-207
get_symbol_value() method syntax 2-161 for text searches 2-73
get_symbol_values() method syntax 2-162 generating files from HTML templates 2-216
get_title() method syntax 2-193 to buttons 2-82, 2-87, 2-88
get_title_prefix() method syntax 2-142 to buttons for data browsing 2-86
get_url() method syntax 2-195 to buttons for URLs 2-85
get_widget_items() method syntax 2-207 to buttons from files and templates 2-218
get_widget_value() method syntax 2-205 to Data Browser 2-76
get_window() method syntax 2-194 to files 2-215
get_window_kind() method syntax 2-185 to files from buttons 2-217
go_to_anchor() method syntax 2-201 to input files 2-107
to lists of e code files 2-106
to text search from buttons 2-83
to URLs 2-74
Index-2 Specman Beta Features
 Index

to VT page 2-77, 2-78 P

package-relative name to absolute name 2-115
I
images, displaying in HTML files 2-109 R
inp_checkbox() method syntax 2-94
inp_combobox() method syntax 2-92 reports
inp_file() method syntax 2-107 HTML tables for 2-104
inp_hidden() method syntax 2-97
inp_listbox() method syntax 2-93 S
inp_member() method syntax 2-95 searching in VT windows 2-65
inp_textarea() method syntax 2-91 set_anchor() method syntax 2-175
inp_textfield() method syntax 2-89 set_file() method syntax 2-172
instance_to_string() method syntax 2-116 set_html_body() method syntax 2-176
is_alive() method syntax 2-219 set_location() method syntax 2-127
is_closed() method syntax 2-134, 2-184 set_lockable() method syntax 2-152
is_current() method syntax 2-183 set_locked() method syntax 2-129
is_lockable() method syntax 2-136 set_pre_close_command() method syntax 2-163
is_locked() method syntax 2-135 set_size() method syntax 2-128
is_opened() method syntax 2-133, 2-182 set_symbol_value() method syntax 2-158
is_pre_opened() method syntax 2-181 set_symbol_values() method syntax 2-159
is_visible() method syntax 2-132 set_title() method syntax 2-131, 2-170
set_url method syntax 2-171
L set_visible() method syntax 2-220
list_to_html() method syntax 2-68 set_widget_items() method syntax 2-206
lnk_anchor() method syntax 2-80 set_widget_value() method syntax 2-203
lnk_command() method syntax 2-72 set_window_kind() method syntax 2-168
lnk_file() method syntax 2-215 show() method syntax 2-179
lnk_instance() method syntax 2-76 show_file() method syntax 2-212
lnk_page() method syntax 2-77 show_file_in_browser() method syntax 2-111
lnk_page_with_title() method syntax 2-78 show_in_new_window() method syntax 2-180
lnk_search() method syntax 2-73 show_page() method syntax 2-60
lnk_template() method syntax 2-216 show_page_with_title() method syntax 2-61
lnk_url_in_browser() method syntax 2-74 show_search() method syntax 2-65
show_styles() method syntax 2-122
show_template() method syntax 2-215
O show_url_in_browser() method syntax 2-110
open_file() method syntax 2-211 Specman Elite
open_page() method syntax 2-62 beta features, defined 1-1
open_page_with_title() method syntax 2-64 stripes
open_template() method syntax 2-213 adding boxes 2-99
adding dividers 2-100
adding rows of boxes 2-101

Specman Beta Features Index-3

Index

clearing 2-102 color codes 2-116

HTML code for showing 2-98 colors 2-35
structs compatibility issues 2-208
converting names to strings 2-116 HTML code creation methods 2-69
syntax notation for e constructs 1-3 HTML files creation methods 2-66
package-relative file names 2-1
T pages
configuring 2-17, 2-64, 2-166, 2-168,
template_to_html() method syntax 2-66 2-170, 2-171, 2-172, 2-175,
template_to_list() method syntax 2-67 2-176, 2-203, 2-205
templates creating new 2-20
opening in VT windows 2-213 defining 2-17
showing in VT windows 2-215 displaying 2-20
text querying 2-139, 2-179, 2-180, 2-181,
printing in colors 2-119 2-182, 2-183, 2-184, 2-185,
text boxes 2-186, 2-187, 2-188, 2-189,
creating multiple line 2-91 2-191, 2-192, 2-193, 2-194,
creating single line 2-89 2-195, 2-196, 2-197, 2-198,
text_style() method syntax 2-119 2-199, 2-200, 2-201
to_front() method syntax 2-143 See also visualization toolkit 2-1
tooltips for HTML components 2-44 styles 2-35
symbols 2-11
U toolkit 2-1
units tooltips 2-44
converting names to strings 2-116, 2-122 vt object 2-1
URLs vt_window object 2-1
hyperlinks from buttons to 2-85 window method error messages 2-16
hyperlinks to 2-74 window methods 2-111, 2-125, 2-165
opening in browsers 2-110 window opening methods 2-59
windows
actions
V customizing 2-9
Visualization Toolkit adding actions 2-146
compatibility issues 2-208 adding lock buttons 2-152
See also VT 2-1 adding menu commands 2-11
Visualization Toolkit (VT) adding menu items 2-146
conventions 2-1 adding menu separators 2-148
defined 2-1 adding menus 2-11, 2-145
VT adding navigation buttons 2-152
API methods 2-111, 2-125, 2-165 adding secondary toolbar menu items
backward compatibility 2-208 2-155
browser methods 2-109 adding secondary toolbar separators
case sensitivity 2-1 2-156

Index-4 Specman Beta Features

 Index

adding secondary toolbars 2-154 using 2-12

adding toolbar separators 2-149 title 2-7
adding toolbars 2-11 toolbar 2-7, 2-8
assigning titles 2-131 viewing history 2-137, 2-138
bringing to front 2-143 vt struct
checking if open 2-219 external browser methods 2-109
checking visibility 2-132 HTML code creation methods 2-69
closing 2-15, 2-165 HTML files creation methods 2-66
callback 2-163 window opening methods 2-59
color styles 2-36 vt_color predefined colors 2-35
components 2-7 vt_style predefined color styles 2-36
configuring 2-125 vt_window
contents page 2-7 API methods 2-111, 2-125, 2-165
creating 2-5 vt_window_kind 2-3
creating buttons 2-45
creating hyperlinks 2-44 W
creating stripe charts 2-46
customized menus 2-9 web browsers, opening 2-110
customized toolbar 2-9 win.add_menu_item()
enabling menu actions 2-150 description 2-9
enabling menu commands 2-11
getting symbols 2-161, 2-162
history 2-13
ID number 2-14
locking 2-129
menu bar 2-7, 2-8
menu commands, predefined 2-9
menus, predefined 2-9
methods, scope 2-16
page area 2-8
querying 2-133, 2-134, 2-135, 2-136,
2-140, 2-141, 2-142
reuse policy 2-6
secondary toolbars 2-11
setting location 2-127
setting size 2-128
setting symbol values 2-158, 2-159
setting visibility 2-220
states 2-6
status bar 2-9
symbols
customizing 2-13
predefined 2-12

Specman Beta Features Index-5