API reference - Class TextGenerator

Notation used in Ruby API documentation

Module: db

Description: A text generator class

A text generator is basically a way to produce human-readable text for labelling layouts. It's similar to the Basic.TEXT PCell, but more convenient to use in a scripting context.

Generators can be constructed from font files (or resources) or one of the registered generators can be used.

To create a generator from a font file proceed this way:

gen = RBA::TextGenerator::new
gen.load_from_file("myfont.gds")
region = gen.text("A TEXT", 0.001)

This code produces a RBA::Region with a database unit of 0.001 micron. This region can be fed into a Shapes container to place it into a cell for example.

By convention the font files must have two to three layers:

Currently, all glyphs must be bottom-left aligned at 0, 0. The border must be drawn in at least one glyph cell. The border is taken as the overall bbox of all borders.

The glyph cells must be named with a single character or "nnn" where "d" is the ASCII code of the character (i.e. "032" for space). Allowed ASCII codes are 32 through 127. If a lower-case "a" character is defined, lower-case letters are supported. Otherwise, lowercase letters are mapped to uppercase letters.

Undefined characters are left blank in the output.

A comment cell can be defined ("COMMENT") which must hold one text in layer 1 stating the comment, and additional descriptions such as line width:

Generators can be picked form a list of predefined generator. See generators, default_generator and generator_by_name for picking a generator from the list.

This class has been introduced in version 0.25.

Public constructors

new TextGenerator ptrnewCreates a new object of this class

Public methods

void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidassign(const TextGenerator other)Assigns another object to self
[const]BoxbackgroundGets the background rectangle of each glyph in the generator's database units
[const]DBoxdbackgroundGets the background rectangle in micron units
[const]doubledbuGets the basic database unit the design of the glyphs was made
[const]doubleddesign_gridGets the design grid of the glyphs in micron units
[const]stringdescriptionGets the description text of the generator
[const]intdesign_gridGets the design grid of the glyphs in the generator's database units
[const]doubledheightGets the design height of the glyphs in micron units
[const]doubledline_widthGets the line width of the glyphs in micron units
[const]new TextGenerator ptrdupCreates a copy of self
[const]doubledwidthGets the design width of the glyphs in micron units
[const]Regionglyph(char char)Gets the glyph of the given character as a region
[const]intheightGets the design height of the glyphs in the generator's database units
[const]intline_widthGets the line width of the glyphs in the generator's database units
voidload_from_file(string path)Loads the given file into the generator
voidload_from_resource(string resource_path)Loads the given resource data (as layout data) into the generator
[const]stringnameGets the name of the generator
[const]Regiontext(string text,
double target_dbu,
double mag = 1,
bool inv = false,
double bias = 0,
double char_spacing = 0,
double line_spacing = 0)
Gets the rendered text as a region
[const]intwidthGets the design height of the glyphs in the generator's database units

Public static methods and constants

const TextGenerator ptrdefault_generatorGets the default text generator (a standard font)
string[]font_pathsGets the paths where to look for font files
const TextGenerator ptrgenerator_by_name(string name)Gets the text generator for a given name
const TextGenerator ptr[]generatorsGets the generators registered in the system
voidset_font_paths(string[] arg1)Sets the paths where to look for font files

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

assign

Signature: void assign (const TextGenerator other)

Description: Assigns another object to self

background

Signature: [const] Box background

Description: Gets the background rectangle of each glyph in the generator's database units

The background rectangle is the one that is used as background for inverted rendering. A version that delivers this value in micrometer units is dbackground.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

dbackground

Signature: [const] DBox dbackground

Description: Gets the background rectangle in micron units

The background rectangle is the one that is used as background for inverted rendering.

dbu

Signature: [const] double dbu

Description: Gets the basic database unit the design of the glyphs was made

This database unit the basic resolution of the glyphs.

ddesign_grid

Signature: [const] double ddesign_grid

Description: Gets the design grid of the glyphs in micron units

The design grid is the basic grid used when designing the glyphs. In most cases this grid is bigger than the database unit.

default_generator

Signature: [static] const TextGenerator ptr default_generator

Description: Gets the default text generator (a standard font)

This method delivers the default generator or nil if no such generator is installed.

description

Signature: [const] string description

Description: Gets the description text of the generator

The generator's description text is a human-readable text that is used to identify the generator (aka 'font') in user interfaces.

design_grid

Signature: [const] int design_grid

Description: Gets the design grid of the glyphs in the generator's database units

The design grid is the basic grid used when designing the glyphs. In most cases this grid is bigger than the database unit. A version that delivers this value in micrometer units is ddesign_grid.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

dheight

Signature: [const] double dheight

Description: Gets the design height of the glyphs in micron units

The height is the height of the rectangle occupied by each character.

dline_width

Signature: [const] double dline_width

Description: Gets the line width of the glyphs in micron units

The line width is the intended (not necessarily precisely) line width of typical character lines (such as the bar of an 'I').

dup

Signature: [const] new TextGenerator ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

dwidth

Signature: [const] double dwidth

Description: Gets the design width of the glyphs in micron units

The width is the width of the rectangle occupied by each character.

font_paths

Signature: [static] string[] font_paths

Description: Gets the paths where to look for font files

See set_font_paths for a description of this function.

This method has been introduced in version 0.27.4.

generator_by_name

Signature: [static] const TextGenerator ptr generator_by_name (string name)

Description: Gets the text generator for a given name

This method delivers the generator with the given name or nil if no such generator is registered.

generators

Signature: [static] const TextGenerator ptr[] generators

Description: Gets the generators registered in the system

This method delivers a list of generator objects that can be used to create texts.

glyph

Signature: [const] Region glyph (char char)

Description: Gets the glyph of the given character as a region

The region represents the glyph's outline and is delivered in the generator's database units .A more elaborate way to getting the text's outline is text.

height

Signature: [const] int height

Description: Gets the design height of the glyphs in the generator's database units

The height is the height of the rectangle occupied by each character. A version that delivers this value in micrometer units is dheight.

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

line_width

Signature: [const] int line_width

Description: Gets the line width of the glyphs in the generator's database units

The line width is the intended (not necessarily precisely) line width of typical character lines (such as the bar of an 'I'). A version that delivers this value in micrometer units is dline_width.

load_from_file

Signature: void load_from_file (string path)

Description: Loads the given file into the generator

See the description of the class how the layout data is read.

load_from_resource

Signature: void load_from_resource (string resource_path)

Description: Loads the given resource data (as layout data) into the generator

The resource path has to start with a colon, i.e. ':/my/resource.gds'. See the description of the class how the layout data is read.

name

Signature: [const] string name

Description: Gets the name of the generator

The generator's name is the basic key by which the generator is identified.

new

Signature: [static] new TextGenerator ptr new

Description: Creates a new object of this class

Python specific notes:
This method is the default initializer of the object.

set_font_paths

Signature: [static] void set_font_paths (string[] arg1)

Description: Sets the paths where to look for font files

This function sets the paths where to look for font files. After setting such a path, each font found will render a specific generator. The generator can be found under the font file's name. As the text generator is also the basis for the Basic.TEXT PCell, using this function also allows configuring custom fonts for this library cell.

This method has been introduced in version 0.27.4.

text

Signature: [const] Region text (string text, double target_dbu, double mag = 1, bool inv = false, double bias = 0, double char_spacing = 0, double line_spacing = 0)

Description: Gets the rendered text as a region

text:The text string
target_dbu:The database unit for which to produce the text
mag:The magnification (1.0 for original size)
inv:inverted rendering: if true, the glyphs are rendered inverse with the background box as the outer bounding box
bias:An additional bias to be applied (happens before inversion, can be negative)
char_spacing:Additional space between characters (in micron units)
line_spacing:Additional space between lines (in micron units)

Various options can be specified to control the appearance of the text. See the description of the parameters. It's important to specify the target database unit in target_dbu to indicate what database unit shall be used to create the output for.

width

Signature: [const] int width

Description: Gets the design height of the glyphs in the generator's database units

The width is the width of the rectangle occupied by each character. A version that delivers this value in micrometer units is dwidth.