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.
| new TextGenerator ptr | new | Creates a new object of this class |
| [const] | TextGenerator ptr | _const_cast | Returns a non-const reference to self. | |
| void | _create | Ensures the C++ object is created | ||
| void | _destroy | Explicitly 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 | _manage | Marks the object as managed by the script side. | ||
| void | _unmanage | Marks the object as no longer owned by the script side. | ||
| void | assign | (const TextGenerator other) | Assigns another object to self | |
| [const] | Box | background | Gets the background rectangle of each glyph in the generator's database units | |
| [const] | DBox | dbackground | Gets the background rectangle in micron units | |
| [const] | double | dbu | Gets the basic database unit the design of the glyphs was made | |
| [const] | double | ddesign_grid | Gets the design grid of the glyphs in micron units | |
| [const] | string | description | Gets the description text of the generator | |
| [const] | int | design_grid | Gets the design grid of the glyphs in the generator's database units | |
| [const] | double | dheight | Gets the design height of the glyphs in micron units | |
| [const] | double | dline_width | Gets the line width of the glyphs in micron units | |
| [const] | new TextGenerator ptr | dup | Creates a copy of self | |
| [const] | double | dwidth | Gets the design width of the glyphs in micron units | |
| [const] | Region | glyph | (char char) | Gets the glyph of the given character as a region |
| [const] | int | height | Gets the design height of the glyphs in the generator's database units | |
| [const] | int | line_width | Gets the line width of the glyphs in the generator's database units | |
| void | load_from_file | (string path) | Loads the given file into the generator | |
| void | load_from_resource | (string resource_path) | Loads the given resource data (as layout data) into the generator | |
| [const] | string | name | Gets the name of the generator | |
| [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) | Gets the rendered text as a region |
| [const] | int | width | Gets the design height of the glyphs in the generator's database units |
| const TextGenerator ptr | default_generator | Gets the default text generator (a standard font) | ||
| string[] | font_paths | Gets the paths where to look for font files | ||
| const TextGenerator ptr | generator_by_name | (string name) | Gets the text generator for a given name | |
| const TextGenerator ptr[] | generators | Gets the generators registered in the system | ||
| void | set_font_paths | (string[] paths) | Sets the paths where to look for font files |
| void | create | Use of this method is deprecated. Use _create instead | ||
| void | destroy | Use of this method is deprecated. Use _destroy instead | ||
| [const] | bool | destroyed? | Use of this method is deprecated. Use _destroyed? instead | |
| [const] | bool | is_const_object? | Use of this method is deprecated. Use _is_const_object? instead |
_const_cast | Signature: [const] TextGenerator ptr _const_cast Description: Returns a non-const reference to self. Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects. This method has been introduced in version 0.29.6. | ||||||||||||||
_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: | ||||||||||||||
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: | ||||||||||||||
set_font_paths | Signature: [static] void set_font_paths (string[] paths) 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
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. |