xlTBUtils - 2022.1 English

Vitis Model Composer User Guide (UG1483)

Document ID
UG1483
Release Date
2022-05-26
Version
2022.1 English

The xlTBUtils command provides access to several features that include access to the layout, rerouting functions and to functions that return selected blocks and lines.

Syntax

xlTBUtils(function, args) 
e.g. 
xlTBUtils('Layout',struct('verbose',1,'autoroute',0)) 
xlTBUtils('Layout',optionStruct) 
xlTBUtils('Redrawlines',struct('autoroute',0)) 
xlTBUtils('RedrawLines',optionStruct) 
[lines,blks]=xlTBUtils('GetSelected',handle,'all')

Description

xlTBUtils(function [,args])

The function argument specifies the name of the function to execute. Further arguments (if required) can be tagged on as supplementary arguments to the function call. Note that the function argument string is not case sensitive. Possible values are enumerated below and explained further in the relevant subtopics.

Table 1. Function Argument
Function Description
'Layout' Runs the layout algorithm on a model to place and reroute lines on the model. Layout can be customized using the option structure that is detailed below.
'RedrawLines' Runs the routing algorithm on a model to reroute lines on the model. RedrawLines can be customized using the option structure detailed below.
'GetSelected' Returns MATLAB Simulink handles to blocks and lines that are selected on the system in focus.

'xlTBUtils('Layout',optionStruct)

Automatically places and routes a Simulink model. optionStruct is a MATLAB struct data-type, that contains the parameters for Layout. The optionStruct argument is optional.

Layout expects circuits to be placed left to right. After placement, Layout uses Simulink to autoroute the wire connections. Simulink will route avoiding anything visible on screen, including block labels. Setting "ignore_labels" will 'allow' Simulink to route over labels – after which it is possible to manually move the labels to a more reasonable location. Note that field names are case sensitive.

Table 2. optionStruct Argument
Field Names Description [Default values]
x_pitch, y_pitch The gaps (pitch) between block (pixels). x_pitch specifies the amount of spacing to leave between blocks horizontally, and y_pitch specifies vertical spacing. [30].
x_start, y_start Left (x_start) and top(y_start) margin spacing (pixels). The amount of spacing to leave on the left and top of a model. [10].
autoroute Turns on Simulink auto-routing of lines. (1 | 0) [1]
ignore_labels When auto-routing lines, Simulink will attempt to auto-route around text labels. Setting ignore_labels to 1 will minimize text label size during the routing process.
sys Name of the system to layout. [gcs]
verbose

When set to 1, a wait bar is shown during the layout process.

xlTBUtils('RedrawLines',optionStruct)

The RedrawLines command will redraw all lines in a Simulink model. If there are lines selected, only selected lines are redrawn otherwise all lines are redrawn. If a branch is selected, the entire line is redrawn; main trunk and all other sub-branches.

Table 3. RedrawLines Command
Field Names Description [Default values]
autoroute Turns on Simulink auto-routing of lines. (1 | 0) [1]
sys Name of the system to layout. [gcs]

xlTBUtils('GetSelected',handle,arg)

The GetSelected command returns handles to selected blocks and lines of the system in focus. The argument handle returns the Simulink model, in which the blocks and lines are selected. You can also provide the model name in place of the argument handle. The argument arg should be one of the string values described in the following table.

Table 4. GetSelected Command
GetSelected Description [Default values]
'all' Gets both selected lines and blocks.
'lines' Gets only selected lines.
'blocks' Gets only selected blocks.

The GetSelected command will return an array with two items, an array of a structure containing line information (lines) and an array of block handles (blks). If the 'lines' argument is used, blks is an empty array; similarly when the 'blocks' argument is used, lines is an empty array.

Examples

Example 1a: Performing Layouts
a.verbose = 1; 
a.autoroute= 0; 
xlTBUtils('Layout',a);

This will invoke the layout tool with verbose on and autoroute off.

Example 1b: Performing Layouts
xlTBUtils('Layout',struct('verbose',1,'autoroute',0));

This will also invoke the layout tool with verbose on and autoroute off.

Example 2: Redrawing lines
xlTBUtils('Redrawlines',struct('autoroute',0));

This will redraw the lines of the current system, with auto-routing off.

Example 3: Getting selected lines and blocks
xlTBUtils('GetSelected',handle,'all') 
lines = 

1x3 struct array with fields: 
  Handle 
  Name 
  Parent 
  SrcBlock 
  SrcPort 
  DstBlock 
  DstPort 
  Points 
  Branch 

blks = 

1.0e+003 * 

3.0320 
3.0480

This will return all selected lines and blocks in the current system. In this case, 3 lines and 2 blocks were selected. The first line handle can be accessed using the command:

lines(1).Handle

ans = 

3.0740e+003

The handle to the first block can be accessed using the command:

blks(1) 
ans = 
3.0320e+003

Remarks

The actions performed by Layout and RedrawLines will not be in the undo stack. Save a copy of the model before performing the actions, in order to revert to the original model.

This product contains certain software code or other information ("AT&T Software") proprietary to AT&T Corp. ("AT&T"). The AT&T Software is provided to you "AS IS". YOU ASSUME TOTAL RESPONSIBILITY AND RISK FOR USE OF THE AT&T SOFTWARE. AT&T DOES NOT MAKE, AND EXPRESSLY DISCLAIMS, ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND WHATSOEVER, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, WARRANTIES OF TITLE OR NON-INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHTS, ANY WARRANTIES ARISING BY USAGE OF TRADE, COURSE OF DEALING OR COURSE OF PERFORMANCE, OR ANY WARRANTY THAT THE AT&T SOFTWARE IS "ERROR FREE" OR WILL MEET YOUR REQUIREMENTS.

Unless you accept a license to use the AT&T Software, you shall not reverse compile, disassemble or otherwise reverse engineer this product to ascertain the source code for any AT&T Software.

© AT&T Corp. All rights reserved. AT&T is a registered trademark of AT&T Corp.

See Also

xlAddTerms