KLayout Manual: Main Index » Class Index » API reference - Class Annotation

API reference - Class Annotation

Notation used in Ruby API documentation

Description: A layout annotation (i.e. ruler)

• Public constructors
• Public methods
• Public static methods and constants
• Deprecated methods (protected, public, static, non-static and constructors)
• Detailed description

Annotation objects provide a way to attach measurements or descriptive informations to a layout view. Annotation objects can appear as rulers for example. Annotation objects can be configured in different ways using the styles provided. By configuring an annotation object properly, it can appear as a rectangle or a plain line for example. See Ruler properties for more details about the appearance options.

Annotations are inserted into a layout view using LayoutView#insert_annotation. Here is some sample code in Ruby:

app = RBA::Application.instance
mw = app.main_window
view = mw.current_view

ant = RBA::Annotation::new
ant.p1 = RBA::DPoint::new(0, 0)
ant.p2 = RBA::DPoint::new(100, 0)
ant.style = RBA::Annotation::StyleRuler
view.insert_annotation(ant)

Annotations can be retrieved from a view with LayoutView#each_annotation and all annotations can be cleared with LayoutView#clear_annotations.

To change an existing annotation, employ the ID of the existing annotation and use LayoutView#replace_annotation to replace it with a new one. Changing the annotation's properties directly won't have an immediate effect. Please note that LayoutView#each_annotation returns a const object, so that we have to create a copy to modify them. Here is some sample code for changing the style of all annotations present in the view:

view = RBA::LayoutView::current

begin

  view.transaction("Restyle annotations")

  view.each_annotation do |a|
    adup = a.dup
    adup.style = RBA::Annotation::StyleArrowBoth
    view.replace_annotation(a.id, adup)
  end
  
ensure
  view.commit
end

Public constructors

Public methods

Public static methods and constants

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

Detailed description

[const] bool !=(const Annotation other)

Description: Inequality operator

[const] bool ==(const Annotation other)

Description: Equality operator

[static] int AngleAny

Description: Gets the any angle code for use with the angle_constraint method

If this value is specified for the angle constraint, all angles will be allowed.

[static] int AngleDiagonal

Description: Gets the diagonal angle code for use with the angle_constraint method

If this value is specified for the angle constraint, only multiples of 45 degree are allowed.

[static] int AngleGlobal

Description: Gets the global angle code for use with the angle_constraint method.

This code will tell the ruler or marker to use the angle constraint defined globally.

[static] int AngleHorizontal

Description: Gets the horizontal angle code for use with the angle_constraint method

If this value is specified for the angle constraint, only horizontal rulers are allowed.

[static] int AngleOrtho

Description: Gets the ortho angle code for use with the angle_constraint method

If this value is specified for the angle constraint, only multiples of 90 degree are allowed.

[static] int AngleVertical

Description: Gets the vertical angle code for use with the angle_constraint method

If this value is specified for the angle constraint, only vertical rulers are allowed.

[static] int OutlineBox

Description: Gets the box outline code for use with the outline method

When this outline style is specified, a box is drawn with the corners specified by the start and end point. All box edges are drawn in the style specified with the style attribute.

[static] int OutlineDiag

Description: Gets the diagonal output code for use with the outline method

When this outline style is specified, a line connecting start and end points in the given style (ruler, arrow or plain line) is drawn.

[static] int OutlineDiagXY

Description: outline_xy code used by the outline method

When this outline style is specified, three lines are drawn: one horizontal from left to right and attached to the end of that a line from the bottom to the top. Another line is drawn connecting the start and end points directly. The lines are drawn in the specified style (see style method).

[static] int OutlineDiagYX

Description: Gets the yx plus diagonal outline code for use with the outline method

When this outline style is specified, three lines are drawn: one vertical from bottom to top and attached to the end of that a line from the left to the right. Another line is drawn connecting the start and end points directly. The lines are drawn in the specified style (see style method).

Python specific notes:

This method is not available for Python

[static] int OutlineXY

Description: Gets the xy outline code for use with the outline method

When this outline style is specified, two lines are drawn: one horizontal from left to right and attached to the end of that a line from the bottom to the top. The lines are drawn in the specified style (see style method).

[static] int OutlineYX

Description: Gets the yx outline code for use with the outline method

When this outline style is specified, two lines are drawn: one vertical from bottom to top and attached to the end of that a line from the left to the right. The lines are drawn in the specified style (see style method).

Python specific notes:

This method is not available for Python

[static] int StyleArrowBoth

Description: Gets the both arrow ends style code for use the style method

When this style is specified, a two-headed arrow is drawn.

[static] int StyleArrowEnd

Description: Gets the end arrow style code for use the style method

When this style is specified, an arrow is drawn pointing from the start to the end point.

[static] int StyleArrowStart

Description: Gets the start arrow style code for use the style method

When this style is specified, an arrow is drawn pointing from the end to the start point.

[static] int StyleLine

Description: Gets the line style code for use with the style method

When this style is specified, plain line is drawn.

[static] int StyleRuler

Description: Gets the ruler style code for use the style method

When this style is specified, the annotation will show a ruler with some ticks at distances indicating a decade of units and a suitable subdivision into minor ticks at intervals of 1, 2 or 5 units.

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.

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.

[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.

[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.

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.

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.

[static] int angle_any

Description: Gets the any angle code for use with the angle_constraint method

Use of this method is deprecated. Use AngleAny instead

[const] int angle_constraint

Description: Returns the angle constraint attribute

See angle_constraint= for a more detailed description.

Python specific notes:

The object exposes a readable attribute 'angle_constraint'. This is the getter.

void angle_constraint=(int flag)

Description: Sets the angle constraint attribute

This attribute controls if an angle constraint is applied when moving one of the ruler's points. The Angle... values can be used for this purpose.

Python specific notes:

The object exposes a writable attribute 'angle_constraint'. This is the setter.

[static] int angle_diagonal

Description: Gets the diagonal angle code for use with the angle_constraint method

Use of this method is deprecated. Use AngleDiagonal instead

[static] int angle_global

Description: Gets the global angle code for use with the angle_constraint method.

Use of this method is deprecated. Use AngleGlobal instead

[static] int angle_horizontal

Description: Gets the horizontal angle code for use with the angle_constraint method

Use of this method is deprecated. Use AngleHorizontal instead

[static] int angle_ortho

Description: Gets the ortho angle code for use with the angle_constraint method

Use of this method is deprecated. Use AngleOrtho instead

[static] int angle_vertical

Description: Gets the vertical angle code for use with the angle_constraint method

Use of this method is deprecated. Use AngleVertical instead

void assign(const Annotation other)

Description: Assigns another object to self

[const] DBox box

Description: Gets the bounding box of the object (not including text)

void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

[const] bool destroyed?

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

Use of this method is deprecated. Use _destroyed? instead

[const] new Annotation ptr dup

Description: Creates a copy of self

[const] string fmt

Description: Returns the format used for the label

Format strings can contain placeholders for values and formulas for computing derived values. See Ruler properties for more details.

Python specific notes:

The object exposes a readable attribute 'fmt'. This is the getter.

void fmt=(string format)

Description: Sets the format used for the label

Format strings can contain placeholders for values and formulas for computing derived values. See Ruler properties for more details.

Python specific notes:

The object exposes a writable attribute 'fmt'. This is the setter.

[const] string fmt_x

Description: Returns the format used for the x-axis label

Format strings can contain placeholders for values and formulas for computing derived values. See Ruler properties for more details.

Python specific notes:

The object exposes a readable attribute 'fmt_x'. This is the getter.

void fmt_x=(string format)

Description: Sets the format used for the x-axis label

X-axis labels are only used for styles that have a horizontal component. Format strings can contain placeholders for values and formulas for computing derived values. See Ruler properties for more details.

Python specific notes:

The object exposes a writable attribute 'fmt_x'. This is the setter.

[const] string fmt_y

Description: Returns the format used for the y-axis label

Format strings can contain placeholders for values and formulas for computing derived values. See Ruler properties for more details.

Python specific notes:

The object exposes a readable attribute 'fmt_y'. This is the getter.

void fmt_y=(string format)

Description: Sets the format used for the y-axis label

Y-axis labels are only used for styles that have a vertical component. Format strings can contain placeholders for values and formulas for computing derived values. See Ruler properties for more details.

Python specific notes:

The object exposes a writable attribute 'fmt_y'. This is the setter.

[const] int id

Description: Returns the annotation's ID

The annotation ID is an integer that uniquely identifies an annotation inside a view. The ID is used for replacing an annotation (see LayoutView#replace_annotation).

This method was introduced in version 0.24.

[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

[static] new Annotation ptr new

Description: Create a new ruler or marker with the default attributes

Python specific notes:

This method is the default initializer of the object

[const] int outline

Description: Returns the outline style of the annotation object

Python specific notes:

The object exposes a readable attribute 'outline'. This is the getter.

void outline=(int outline)

Description: Sets the outline style used for drawing the annotation object

The Outline... values can be used for defining the annotation object's outline. The outline style determines what components are drawn.

Python specific notes:

The object exposes a writable attribute 'outline'. This is the setter.

[static] int outline_box

Description: Gets the box outline code for use with the outline method

Use of this method is deprecated. Use OutlineBox instead

[static] int outline_diag

Description: Gets the diagonal output code for use with the outline method

Use of this method is deprecated. Use OutlineDiag instead

[static] int outline_diag_xy

Description: outline_xy code used by the outline method

Use of this method is deprecated. Use OutlineDiagXY instead

[static] int outline_diag_yx

Description: Gets the yx plus diagonal outline code for use with the outline method

Use of this method is deprecated. Use OutlineDiagYX instead

[static] int outline_xy

Description: Gets the xy outline code for use with the outline method

Use of this method is deprecated. Use OutlineXY instead

[static] int outline_yx

Description: Gets the yx outline code for use with the outline method

Use of this method is deprecated. Use OutlineYX instead

[const] DPoint p1

Description: Gets the first point of the ruler or marker

The points of the ruler or marker are always given in micron units in floating-point coordinates.

Python specific notes:

The object exposes a readable attribute 'p1'. This is the getter.

void p1=(const DPoint point)

Description: Sets the first point of the ruler or marker

The points of the ruler or marker are always given in micron units in floating-point coordinates.

Python specific notes:

The object exposes a writable attribute 'p1'. This is the setter.

[const] DPoint p2

Description: Gets the second point of the ruler or marker

The points of the ruler or marker are always given in micron units in floating-point coordinates.

Python specific notes:

The object exposes a readable attribute 'p2'. This is the getter.

void p2=(const DPoint point)

Description: Sets the second point of the ruler or marker

The points of the ruler or marker are always given in micron units in floating-point coordinates.

Python specific notes:

The object exposes a writable attribute 'p2'. This is the setter.

void snap=(bool flag)

Description: Sets the 'snap to objects' attribute

If this attribute is set to true, the ruler or marker snaps to other objects when moved.

Python specific notes:

The object exposes a writable attribute 'snap'. This is the setter.

[const] bool snap?

Description: Returns the 'snap to objects' attribute

Python specific notes:

The object exposes a readable attribute 'snap'. This is the getter.

[const] int style

Description: Returns the style of the annotation object

Python specific notes:

The object exposes a readable attribute 'style'. This is the getter.

void style=(int style)

Description: Sets the style used for drawing the annotation object

The Style... values can be used for defining the annotation object's style. The style determines if ticks or arrows are drawn.

Python specific notes:

The object exposes a writable attribute 'style'. This is the setter.

[static] int style_arrow_both

Description: Gets the both arrow ends style code for use the style method

Use of this method is deprecated. Use StyleArrowBoth instead

[static] int style_arrow_end

Description: Gets the end arrow style code for use the style method

Use of this method is deprecated. Use StyleArrowEnd instead

[static] int style_arrow_start

Description: Gets the start arrow style code for use the style method

Use of this method is deprecated. Use StyleArrowStart instead

[static] int style_line

Description: Gets the line style code for use with the style method

Use of this method is deprecated. Use StyleLine instead

[static] int style_ruler

Description: Gets the ruler style code for use the style method

Use of this method is deprecated. Use StyleRuler instead

[const] string text

Description: Returns the formatted text for the main label

[const] string text_x

Description: Returns the formatted text for the x-axis label

[const] string text_y

Description: Returns the formatted text for the y-axis label

[const] string to_s

Description: Returns the string representation of the ruler

This method was introduced in version 0.19.

Python specific notes:

This method is also available as 'str(object)'

[const] Annotation transformed(const DTrans t)

Description: Transforms the ruler or marker with the given simple transformation

[const] Annotation transformed_cplx(const DCplxTrans t)

Description: Transforms the ruler or marker with the given complex transformation

[const] Annotation transformed_cplx(const ICplxTrans t)

Description: Transforms the ruler or marker with the given complex transformation

This method has been introduced in version 0.18.