API reference - Class PCellDeclaration

Notation used in Ruby API documentation

Module: db

Description: A PCell declaration providing the parameters and code to produce the PCell

Class hierarchy: PCellDeclaration

A PCell declaration is basically the recipe of how to create a PCell layout from a parameter set. The declaration includes

All these declarations are implemented by deriving from the PCellDeclaration class and reimplementing the specific methods. Reimplementing the display_name method is optional. The default implementation creates a name from the PCell name plus the parameters.

By supplying the information about the layers it wants to create, KLayout is able to call the production callback with a defined set of the layer ID's which are already mapped to valid actual layout layers.

This class has been introduced in version 0.22.

Public constructors

new PCellDeclaration ptrnewCreates a new object of this class

Public methods

void_assign(const PCellDeclaration other)Assigns another object to self
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]new PCellDeclaration ptr_dupCreates a copy of self
[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 PCellDeclaration other)Assigns another object to self
[virtual,const]voidcallback(const Layout layout,
string name,
PCellParameterStates states)
Indicates a parameter change and allows implementing actions based on the parameter value
[virtual,const]boolcan_create_from_shape(const Layout layout,
const Shape shape,
unsigned int layer)
Returns true, if the PCell can be created from the given shape
[virtual,const]variant[]coerce_parameters(const Layout layout,
variant[] input)
Modifies the parameters to match the requirements
[virtual,const]stringdisplay_text(variant[] parameters)Returns the display text for this PCell given a certain parameter set
[const]new PCellDeclaration ptrdupCreates a copy of self
[virtual,const]LayerInfo[]get_layers(variant[] parameters)Returns a list of layer declarations
[virtual,const]PCellParameterDeclaration[]get_parametersReturns a list of parameter declarations
[const]unsigned intidGets the integer ID of the PCell declaration
[const]Layout ptrlayoutGets the Layout object the PCell is registered in or nil if it is not registered yet.
[const]stringnameGets the name of the PCell
[virtual,const]variant[]parameters_from_shape(const Layout layout,
const Shape shape,
unsigned int layer)
Gets the parameters for the PCell which can replace the given shape
[virtual,const]voidproduce(const Layout layout,
unsigned int[] layer_ids,
variant[] parameters,
Cell cell)
The production callback
[virtual,const]Transtransformation_from_shape(const Layout layout,
const Shape shape,
unsigned int layer)
Gets the instance transformation for the PCell which can replace the given shape
[virtual,const]boolwants_lazy_evaluationGets a value indicating whether the PCell wants lazy evaluation

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

_assign

Signature: void _assign (const PCellDeclaration other)

Description: Assigns another object to self

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

_dup

Signature: [const] new PCellDeclaration ptr _dup

Description: Creates a copy of self

_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 PCellDeclaration other)

Description: Assigns another object to self

callback

Signature: [virtual,const] void callback (const Layout layout, string name, PCellParameterStates states)

Description: Indicates a parameter change and allows implementing actions based on the parameter value

layout:The layout object in which the PCell will be produced
name:The name of the parameter which has changed or an empty string if all parameters need to be considered
states:A PCellParameterStates object which can be used to manipulate the parameter states

This method may be reimplemented to implement parameter-specific actions upon value change or button callbacks. Whenever the value of a parameter is changed in the PCell parameter form, this method is called with the name of the parameter in 'name'. The implementation can manipulate values or states (enabled, visible) or parameters using the PCellParameterStates object passed in 'states'.

Initially, this method will be called with an empty parameter name to indicate a global change. The implementation may then consolidate all states. The initial state is build from the 'readonly' (disabled) or 'hidden' (invisible) parameter declarations.

This method is also called when a button-type parameter is present and the button is pressed. In this case the parameter name is the name of the button.

This feature has been introduced in version 0.28.

can_create_from_shape

Signature: [virtual,const] bool can_create_from_shape (const Layout layout, const Shape shape, unsigned int layer)

Description: Returns true, if the PCell can be created from the given shape

layout:The layout the shape lives in
shape:The shape from which a PCell shall be created
layer:The layer index (in layout) of the shape

KLayout offers a way to convert a shape into a PCell. To test whether the PCell can be created from a shape, it will call this method. If this method returns true, KLayout will use parameters_from_shape and transformation_from_shape to derive the parameters and instance transformation for the new PCell instance that will replace the shape.

coerce_parameters

Signature: [virtual,const] variant[] coerce_parameters (const Layout layout, variant[] input)

Description: Modifies the parameters to match the requirements

layout:The layout object in which the PCell will be produced
input:The parameters before the modification
Returns:The modified parameters or an empty array, indicating that no modification was done

This method can be reimplemented to change the parameter set according to some constraints for example. The reimplementation may modify the parameters in a way that they are usable for the produce method.

The method receives a reference to the layout so it is able to verify the parameters against layout properties.

It can raise an exception to indicate that something is not correct.

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.

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.

display_text

Signature: [virtual,const] string display_text (variant[] parameters)

Description: Returns the display text for this PCell given a certain parameter set

Reimplement this method to create a distinct display text for a PCell variant with the given parameter set. If this method is not implemented, a default text is created.

dup

Signature: [const] new PCellDeclaration ptr dup

Description: Creates a copy of self

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

get_layers

Signature: [virtual,const] LayerInfo[] get_layers (variant[] parameters)

Description: Returns a list of layer declarations

Reimplement this method to return a list of layers this PCell wants to create. The layer declarations are returned as a list of LayerInfo objects which are used as match expressions to look up the layer in the actual layout.

This method receives the PCell parameters which allows it to deduce layers from the parameters.

get_parameters

Signature: [virtual,const] PCellParameterDeclaration[] get_parameters

Description: Returns a list of parameter declarations

Reimplement this method to return a list of parameters used in that PCell implementation. A parameter declaration is a PCellParameterDeclaration object and defines the parameter name, type, description text and possible choices for the parameter value.

id

Signature: [const] unsigned int id

Description: Gets the integer ID of the PCell declaration

This ID is used to identify the PCell in the context of a Layout object for example

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.

layout

Signature: [const] Layout ptr layout

Description: Gets the Layout object the PCell is registered in or nil if it is not registered yet.

This attribute has been added in version 0.27.5.

name

Signature: [const] string name

Description: Gets the name of the PCell

new

Signature: [static] new PCellDeclaration ptr new

Description: Creates a new object of this class

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

parameters_from_shape

Signature: [virtual,const] variant[] parameters_from_shape (const Layout layout, const Shape shape, unsigned int layer)

Description: Gets the parameters for the PCell which can replace the given shape

layout:The layout the shape lives in
shape:The shape from which a PCell shall be created
layer:The layer index (in layout) of the shape

KLayout offers a way to convert a shape into a PCell. If can_create_from_shape returns true, it will use this method to derive the parameters for the PCell instance that will replace the shape. See also transformation_from_shape and can_create_from_shape.

produce

Signature: [virtual,const] void produce (const Layout layout, unsigned int[] layer_ids, variant[] parameters, Cell cell)

Description: The production callback

layout:The layout object where the cell resides
layer_ids:A list of layer ID's which correspond to the layers declared with get_layers
parameters:A list of parameter values which correspond to the parameters declared with get_parameters
cell:The cell where the layout will be created

Reimplement this method to provide the code that implements the PCell. The code is supposed to create the layout in the target cell using the provided parameters and the layers passed in the layer_ids list.

transformation_from_shape

Signature: [virtual,const] Trans transformation_from_shape (const Layout layout, const Shape shape, unsigned int layer)

Description: Gets the instance transformation for the PCell which can replace the given shape

layout:The layout the shape lives in
shape:The shape from which a PCell shall be created
layer:The layer index (in layout) of the shape

KLayout offers a way to convert a shape into a PCell. If can_create_from_shape returns true, it will use this method to derive the transformation for the PCell instance that will replace the shape. See also parameters_from_shape and can_create_from_shape.

wants_lazy_evaluation

Signature: [virtual,const] bool wants_lazy_evaluation

Description: Gets a value indicating whether the PCell wants lazy evaluation

In lazy evaluation mode, the PCell UI will not immediately update the layout when a parameter is changed. Instead, the user has to commit the changes in order to have the parameters updated. This is useful for PCells that take a long time to compute.

The default implementation will return 'false' indicating immediate updates.

This method has been added in version 0.27.6.