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

API reference - Class Shape

Notation used in Ruby API documentation

Description: An object represeting a shape in the layout database

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

The shape proxy is basically a pointer to a shape of different kinds. No copy of the shape is created: if the shape proxy is copied the copy still points to the original shape. If the original shape is modified or deleted, the shape proxy will also point to a modified or invalid shape. The proxy can be "null" which indicates an invalid reference.

Shape objects are used together with the Shapes container object which stores the actual shape objects and uses Shape references as pointers inside the actual data storage. Shape references are used in various places, i.e. when removing or transforming objects inside a Shapes container.

Public constructors

Public methods

Public static methods and constants

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

Detailed description

[const] bool !=(const Shape other)

Description: Inequality operator

[const] bool ==(const Shape other)

Description: Equality operator

Equality of shapes is not specified by the identity of the objects but by the identity of the pointers - both shapes must refer to the same object.

[static] int TBox

Description:

[static] int TBoxArray

Description:

[static] int TBoxArrayMember

Description:

[static] int TEdge

Description:

[static] int TNull

Description:

[static] int TPath

Description:

[static] int TPathPtrArray

Description:

[static] int TPathPtrArrayMember

Description:

[static] int TPathRef

Description:

[static] int TPolygon

Description:

[static] int TPolygonPtrArray

Description:

[static] int TPolygonPtrArrayMember

Description:

[static] int TPolygonRef

Description:

[static] int TShortBox

Description:

[static] int TShortBoxArray

Description:

[static] int TShortBoxArrayMember

Description:

[static] int TSimplePolygon

Description:

[static] int TSimplePolygonPtrArray

Description:

[static] int TSimplePolygonPtrArrayMember

Description:

[static] int TSimplePolygonRef

Description:

[static] int TText

Description:

[static] int TTextPtrArray

Description:

[static] int TTextPtrArrayMember

Description:

[static] int TTextRef

Description:

[static] int TUserObject

Description:

[const] long long area

Description: Returns the area of the shape

This method has been added in version 0.22.

[const] Trans array_trans

Description: Get the array instance member transformation

This attribute is valid only if is_array_member? is true. The transformation returned describes the relative transformation of the array member addressed.

[const] void assign(const Shape other)

Description: Assign the contents of another object to self

This method assigns the contents of another object to self. This is a deep copy that does not only copy the reference but the actual content.

[const] Box bbox

Description: Returns the bounding box of the shape

[const] variant box

Description: Gets the box object

Starting with version 0.23, this method returns nil, if the shape does not represent a box.

void box=(const Box box)

Description: Replaces the shape by the given box

This method replaces the shape by the given box. This method can only be called for editable layouts. It does not change the user properties of the shape. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

[const] Point box_center

Description: Returns the center of the box

Applies to boxes only. Returns the center of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

void box_center=(const Point c)

Description: Sets the center of the box

Applies to boxes only. Changes the center of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

[const] int box_height

Description: Returns the height of the box

Applies to boxes only. Returns the height of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

void box_height=(int h)

Description: Sets the height of the box

Applies to boxes only. Changes the height of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

[const] Point box_p1

Description: Returns the lower left point of the box

Applies to boxes only. Returns the lower left point of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

void box_p1=(const Point p)

Description: Sets the lower left point of the box

Applies to boxes only. Changes the lower left point of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

[const] Point box_p2

Description: Returns the upper right point of the box

Applies to boxes only. Returns the upper right point of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

void box_p2=(const Point p)

Description: Sets the upper right point of the box

Applies to boxes only. Changes the upper right point of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

[const] int box_width

Description: Returns the width of the box

Applies to boxes only. Returns the width of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

void box_width=(int w)

Description: Sets the width of the box

Applies to boxes only. Changes the width of the box and throws an exception if the shape is not a box.

This method has been introduced in version 0.23.

Cell ptr cell

Description: Gets a reference to the cell the shape belongs to

This reference can be nil, if the Shape object is not living inside a cell

This method has been introduced in version 0.22.

void cell=(Cell ptr cell)

Description: Moves the shape to a different cell

Both the current and the target cell must reside in the same layout.

This method has been introduced in version 0.23.

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 delete

Description: Deletes the shape

After the shape is deleted, the shape object is emptied and points to nothing.

This method has been introduced in version 0.23.

void delete_property(variant key)

Description: Deletes the user property with the given key

This method is a convenience method that deletes the property with the given key. It does nothing if no property with that key exists. Using that method is more convenient than creating a new property set with a new ID and assigning that properties ID. This method may change the properties ID. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

void destroy

Description: Explicitly destroy the object

Explicitly destroy the object on C++ side if it was owned by the Ruby interpreter. Subsequent access to this object will throw an exception. If the object is not owned by Ruby, 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] Shape dup

Description: Creates a copy of self

[iter] Edge each_edge

Description: Iterate over the edges of the object

This method applies to polygons and simple polygons and delivers all edges that form the polygon's contours. It will throw an exception if the object is not an edge.

[const,iter] Point each_point

Description: Iterate over all points of the object

This method applies to paths and delivers all points of the path's center line. It will throw an exception for other objects.

[const,iter] Point each_point_hole(unsigned int hole_index)

Description: Iterate over the points of a hole contour

This method applies to polygons and delivers all points of the respective hole contour. It will throw an exception for other objects. Simple polygons deliver an empty sequence.

[const,iter] Point each_point_hull

Description: Iterate over the hull contour of the object

This method applies to polygons and delivers all points of the polygon hull contour. It will throw an exception for other objects.

[const] variant edge

Description: Returns the edge object

Starting with version 0.23, this method returns nil, if the shape does not represent an edge.

void edge=(const Edge box)

Description: Replaces the shape by the given edge

This method replaces the shape by the given edge. This method can only be called for editable layouts. It does not change the user properties of the shape. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

[const] bool has_prop_id?

Description: Returns true, if the shape has properties, i.e. has a properties ID

[const] unsigned int holes

Description: Return the number of holes

This method applies to polygons and will throw an exception for other objects.. Simple polygons deliver a value of zero.

[const] bool is_array_member?

Description: Returns true, if the shape is a member of a shape array

[const] bool is_box?

Description: Returns true if the shape is a box

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

[const] bool is_edge?

Description: Returns true, if the object is an edge

[const] bool is_null?

Description: Returns true, if the shape reference is a null reference (not referring to a shape)

[const] bool is_path?

Description: Returns true, if the shape is a path

[const] bool is_polygon?

Description: Returns true, if the shape is a polygon

This method returns true only if the object is a polygon or a simple polygon. Other objects can convert to polygons, for example paths, so it may be possible to use the polygon method also if is_polygon? does not return true.

[const] bool is_simple_polygon?

Description: Returns true, if the shape is a simple polygon

This method returns true only if the object is a simple polygon. The simple polygon identity is contained in the polygon identity, so usually it is sufficient to use is_polygon? and polygon instead of specifically handle simply polygons. This method is provided only for specific optimisation purposes.

[const] bool is_text?

Description: Returns true, if the object is a text

[const] bool is_user_object?

Description: Returns true if the shape is a user defined object

[const] bool is_valid?

Description: Returns true, if the shape is valid

After the shape is deleted, the shape object is no longer valid and this method returns false.

This method has been introduced in version 0.23.

[const] unsigned int layer

Description: Returns the layer index of the layer the shape is on

Throws an exception if the shape does not reside inside a cell.

This method has been added in version 0.23.

void layer=(unsigned int layer_index)

Description: Moves the shape to a layer given by the layer index object

This method has been added in version 0.23.

[const] LayerInfo layer_info

Description: Returns the LayerInfo object of the layer the shape is on

If the shape does not reside inside a cell, an empty layer is returned.

This method has been added in version 0.23.

void layer_info=(const LayerInfo layer_info)

Description: Moves the shape to a layer given by a LayerInfo object

If no layer with the given properties exists, an exception is thrown.

This method has been added in version 0.23.

Layout ptr layout

Description: Gets a reference to the Layout the shape belongs to

This reference can be nil, if the Shape object is not living inside a layout.

This method has been introduced in version 0.22.

[static] Shape new

Description: Creates a new object of this class

[const] variant path

Description: Returns the path object

Starting with version 0.23, this method returns nil, if the shape does not represent a path.

void path=(const Path box)

Description: Replaces the shape by the given path object

This method replaces the shape by the given path object. This method can only be called for editable layouts. It does not change the user properties of the shape. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

[const] int path_bgnext

Description: Obtain the path's starting vertex extension

Applies to paths only. Will throw an exception if the object is not a path.

void path_bgnext=(int e)

Description: Sets the path's starting vertex extension

Applies to paths only. Will throw an exception if the object is not a path.

This method has been introduced in version 0.23.

[const] int path_endext

Description: Obtain the path's end vertex extension

Applies to paths only. Will throw an exception if the object is not a path.

void path_endext=(int e)

Description: Sets the path's end vertex extension

Applies to paths only. Will throw an exception if the object is not a path.

This method has been introduced in version 0.23.

[const] int path_length

Description: Returns the length of the path

Applies to paths only. Will throw an exception if the object is not a path. This method returns the length of the spine plus extensions if present.

This method has been added in version 0.23.

[const] int path_width

Description: Obtain the path width

Applies to paths only. Will throw an exception if the object is not a path.

void path_width=(int w)

Description: Sets the path width

Applies to paths only. Will throw an exception if the object is not a path.

This method has been introduced in version 0.23.

[const] unsigned int perimeter

Description: Returns the perimeter of the shape

This method will return an approximation of the perimeter for paths.

This method has been added in version 0.23.

[const] variant polygon

Description: Returns the polygon object

Returns the polygon object that this shape refers to or converts the object to a polygon. Paths, boxes and simple polygons are converted to polygons. For paths this operation renders the path's hull contour.

Starting with version 0.23, this method returns nil, if the shape does not represent a geometrical primitive that can be converted to a polygon.

void polygon=(const Polygon box)

Description: Replaces the shape by the given polygon object

This method replaces the shape by the given polygon object. This method can only be called for editable layouts. It does not change the user properties of the shape. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

[const] unsigned int prop_id

Description: Get the properties ID associated with the shape

The Layout object can be used to retrieve the actual properties associated with the ID.

void prop_id=(unsigned int arg1)

Description: Sets the properties ID of this shape

The Layout object can be used to retrieve an ID for a given set of properties. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

variant property(variant key)

Description: Gets the user property with the given key

This method is a convenience method that gets the property with the given key. If no property with that key does not exist, it will return nil. Using that method is more convenient than using the layout object and the properties ID to retrieve the property value. This method has been introduced in version 0.22.

void round_path=(bool r)

Description: The path will be a round-ended path if this property is set to true

Applies to paths only. Will throw an exception if the object is not a path. Please note that the extensions will apply as well. To get a path with circular ends, set the begin and end extensions to half the path's width.

This method has been introduced in version 0.23.

[const] bool round_path?

Description: Returns true, if the path has round ends

Applies to paths only. Will throw an exception if the object is not a path.

void set_property(variant key,variant value)

Description: Set the user property with the given key to the given value

This method is a convenience method that sets the property with the given key to the given value. If no property with that key exists, it will create one. Using that method is more convenient than creating a new property set with a new ID and assigning that properties ID. This method may change the properties ID. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

Shapes ptr shapes

Description: Gets a reference to the Shapes container the shape lives in

This reference can be nil, if the Shape object is not referring to an actual shape.

This method has been introduced in version 0.22.

[const] variant simple_polygon

Description: Returns the simple polygon object

Returns the simple polygon object that this shape refers to or converts the object to a simple polygon. Paths, boxes and polygons are converted to simple polygons. Polygons with holes will have their holes removed but introducing cut lines that connect the hole contours with the outer contour. Starting with version 0.23, this method returns nil, if the shape does not represent a geometrical primitive that can be converted to a simple polygon.

void simple_polygon=(const SimplePolygon box)

Description: Replaces the shape by the given simple polygon object

This method replaces the shape by the given simple polygon object. This method can only be called for editable layouts. It does not change the user properties of the shape. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

[static] int t_box

Description:

This method is deprecated. Use method 'TBox' instead

[static] int t_box_array

Description:

This method is deprecated. Use method 'TBoxArray' instead

[static] int t_box_array_member

Description:

This method is deprecated. Use method 'TBoxArrayMember' instead

[static] int t_edge

Description:

This method is deprecated. Use method 'TEdge' instead

[static] int t_null

Description:

This method is deprecated. Use method 'TNull' instead

[static] int t_path

Description:

This method is deprecated. Use method 'TPath' instead

[static] int t_path_ptr_array

Description:

This method is deprecated. Use method 'TPathPtrArray' instead

[static] int t_path_ptr_array_member

Description:

This method is deprecated. Use method 'TPathPtrArrayMember' instead

[static] int t_path_ref

Description:

This method is deprecated. Use method 'TPathRef' instead

[static] int t_polygon

Description:

This method is deprecated. Use method 'TPolygon' instead

[static] int t_polygon_ptr_array

Description:

This method is deprecated. Use method 'TPolygonPtrArray' instead

[static] int t_polygon_ptr_array_member

Description:

This method is deprecated. Use method 'TPolygonPtrArrayMember' instead

[static] int t_polygon_ref

Description:

This method is deprecated. Use method 'TPolygonRef' instead

[static] int t_short_box

Description:

This method is deprecated. Use method 'TShortBox' instead

[static] int t_short_box_array

Description:

This method is deprecated. Use method 'TShortBoxArray' instead

[static] int t_short_box_array_member

Description:

This method is deprecated. Use method 'TShortBoxArrayMember' instead

[static] int t_simple_polygon

Description:

This method is deprecated. Use method 'TSimplePolygon' instead

[static] int t_simple_polygon_ptr_array

Description:

This method is deprecated. Use method 'TSimplePolygonPtrArray' instead

[static] int t_simple_polygon_ptr_array_member

Description:

This method is deprecated. Use method 'TSimplePolygonPtrArrayMember' instead

[static] int t_simple_polygon_ref

Description:

This method is deprecated. Use method 'TSimplePolygonRef' instead

[static] int t_text

Description:

This method is deprecated. Use method 'TText' instead

[static] int t_text_ptr_array

Description:

This method is deprecated. Use method 'TTextPtrArray' instead

[static] int t_text_ptr_array_member

Description:

This method is deprecated. Use method 'TTextPtrArrayMember' instead

[static] int t_text_ref

Description:

This method is deprecated. Use method 'TTextRef' instead

[static] int t_user_object

Description:

This method is deprecated. Use method 'TUserObject' instead

[const] variant text

Description: Returns the text object

Starting with version 0.23, this method returns nil, if the shape does not represent a text.

void text=(const Text box)

Description: Replaces the shape by the given text object

This method replaces the shape by the given text object. This method can only be called for editable layouts. It does not change the user properties of the shape. Calling this method will invalidate any iterators. It should not be called inside a loop iterating over shapes.

This method has been introduced in version 0.22.

[const] int text_font

Description: Gets the text's font

Applies to texts only. Will throw an exception if the object is not a text.

void text_font=(int font)

Description: Sets the text's font

Applies to texts only. Will throw an exception if the object is not a text.

This method has been introduced in version 0.23.

[const] int text_halign

Description: Gets the text's horizontal alignment

Applies to texts only. Will throw an exception if the object is not a text. The return value is 0 for left alignment, 1 for center alignment and 2 to right alignment.

This method has been introduced in version 0.22.

void text_halign=(int a)

Description: Sets the text's horizontal alignment

Applies to texts only. Will throw an exception if the object is not a text. See text_halign for a description of that property.

This method has been introduced in version 0.23.

[const] Point text_pos

Description: Gets the text's position

Applies to texts only. Will throw an exception if the object is not a text.

void text_pos=(const Point p)

Description: Sets the text's position

Applies to texts only. Will throw an exception if the object is not a text.

[const] int text_rot

Description: Gets the text's orientation code (see Trans)

Applies to texts only. Will throw an exception if the object is not a text.

void text_rot=(int o)

Description: Sets the text's orientation code (see Trans)

Applies to texts only. Will throw an exception if the object is not a text.

[const] int text_size

Description: Gets the text size

Applies to texts only. Will throw an exception if the object is not a text.

void text_size=(int size)

Description: Sets the text size

Applies to texts only. Will throw an exception if the object is not a text.

This method has been introduced in version 0.23.

[const] string text_string

Description: Obtain the text string

Applies to texts only. Will throw an exception if the object is not a text.

void text_string=(string string)

Description: Sets the text string

Applies to texts only. Will throw an exception if the object is not a text.

This method has been introduced in version 0.23.

[const] Trans text_trans

Description: Gets the text transformation

Applies to texts only. Will throw an exception if the object is not a text.

void text_trans=(const Trans trans)

Description: Sets the text transformation

Applies to texts only. Will throw an exception if the object is not a text.

This method has been introduced in version 0.23.

[const] int text_valign

Description: Gets the text's vertical alignment

Applies to texts only. Will throw an exception if the object is not a text. The return value is 0 for top alignment, 1 for center alignment and 2 to bottom alignment.

This method has been introduced in version 0.22.

void text_valign=(int a)

Description: Sets the text's vertical alignment

Applies to texts only. Will throw an exception if the object is not a text. See text_valign for a description of that property.

This method has been introduced in version 0.23.

[const] string to_s

Description: Create a string showing the contents of the reference

This method has been introduced with version 0.16.

void transform(const Trans trans)

Description: Transforms the shape with the given transformation

This method has been introduced in version 0.23.

void transform(const CplxTrans trans)

Description: Transforms the shape with the given complex transformation

This method has been introduced in version 0.23.

void transform(const ICplxTrans trans)

Description: Transforms the shape with the given complex transformation

This method has been introduced in version 0.23.

[const] int type

Description: Return the type of the shape

The returned values are the t_... constants available through the corresponding class members.