KLayout 0.29.8 (2024-10-28 63dd591e5) [master]

API reference - Class EditorHooks

Notation used in Ruby API documentation

Module: lay

Description: An implementation base class for editor hooks

Editor hooks allow implementing technology-specific callbacks into the editor for example to implement visual feedback about DRC rules.

This class provides the basic interface. To implement callbacks, use the EditorHooks class. You should not need to instantiate this class.

The following is an excample for editor hooks that add DRC space indicators for polygon-alike shapes, It implements the shape creation protocol to capture new shapes and the modification protocol to capture shape manipulations. It displays a halo following hard-coded DRC rules to indicate the forbidden zones around the shapes:

class MyEditorHooks < RBA::EditorHooks

  def initialize()
  
    register("editor_hooks_demo")

    cleanup    

    # some demo values    
    @spaces = {
      RBA::LayerInfo::new(1, 0) => [ 0.2, RBA::Region::Euclidian ],
      RBA::LayerInfo::new(2, 0) => [ 0.5, RBA::Region::Projection ]
    }
    
  end

  # Utilities
  
  # pick the space value from layer or set to nil
  def set_space_from_layer(layer_index)
    lp = @layout.get_info(layer_index)
    if @spaces[lp]
      (s, m) = @spaces[lp]
      @space = s / @layout.dbu
      @metrics = m
    else
      @space = nil
    end
  end
      
  def add_marker_from_shape(shape, trans)
  
    if !@space
      return   # no space value set
    end
    
    p = shape.polygon
    if !p
      return   # not a polygon-like object
    end
    
    r = RBA::Region::new
    # maintain 2-point polygons for the first edge drawn
    r.merged_semantics = (p.num_points != 2)
    r.insert(p)
    
    # compute DRC hull and prepare markers
    r.drc_hull(@metrics, @space).each do |pp|
      m = RBA::Marker::new(@view)
      m.line_style = 2
      m.vertex_size = 0
      m.set_polygon(trans * pp)
      @markers.append(m)
    end
    
  end
  
  # setup session
  def start(cv)
    cleanup
    @view = cv.view
    @layout = cv.layout
  end
  
  # end session
  def cleanup
    @space = nil
    @view = nil
    @layout = nil
    clear_markers
  end
  
  def clear_markers
    @markers && @markers.each do |m|
      # this is how a marker gets removed in Ruby:
      m._destroy
    end
    @markers = []
  end
        
  # Shape creation protocol
  
  def begin_create_shapes(cv, layer)
    start(cv)
    set_space_from_layer(layer.layer_index)
  end

  def begin_new_shapes
    clear_markers
  end

  def create_shape(shape, trans)
    add_marker_from_shape(shape, trans)
  end
      
  def end_create_shapes
    cleanup
  end
    
  # Modification protocol
  
  def begin_edit(cv)
    start(cv)
  end

  def begin_edits
    # create new markers
    clear_markers
  end

  # transformation of a shape or instance
  def transformed(path, applied, trans)
    if path.shape
      set_space_from_layer(path.layer)
      add_marker_from_shape(path.shape, trans * applied)
    end
  end

  # modification of a shape
  def modified(path, shape, trans)
    set_space_from_layer(path.layer)
    add_marker_from_shape(shape, trans)
  end

  def end_edit
    cleanup
  end
  
end

# instantiation of the hooks object
MyEditorHooks::new

The EditorHooks class has been introduced in version 0.29.1.

Public constructors

new EditorHooks ptrnewCreates a new object of this class

Public methods

[const]EditorHooks ptr_const_castReturns a non-const reference 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]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.
voidadd_technology(string tech)Additionally associates the hooks with the given technology.
[virtual]voidbegin_create_instances(CellView cellview)Instance creation protocol - begin session
[virtual]voidbegin_create_shapes(CellView cellview,
const LayerProperties layer)
Shape creation protocol - begin session
[virtual]voidbegin_edit(CellView cellview)Editing protocol - begin session
[virtual]voidbegin_editsEditing protocol - begin edits
[virtual]voidbegin_new_instancesInstance creation protocol - begin new instances
[virtual]voidbegin_new_shapesShape creation protocol - begin new shapes
voidclear_technologiesClears the list of technologies the hooks are associated with.
[virtual]voidcommit_editEditing protocol - commit new objects
[virtual]voidcommit_instancesInstance creation protocol - commit new objects
[virtual]voidcommit_shapesShape creation protocol - commit new objects
[virtual]voidcreate_instance(const Instance instance,
const CplxTrans view_trans)
Instance creation protocol - indicate a new object
[virtual]voidcreate_shape(const Shape shape,
const CplxTrans view_trans)
Shape creation protocol - indicate a new object
[virtual]voidend_create_instancesInstance creation protocol - finish session
[virtual]voidend_create_shapesShape creation protocol - finish session
[virtual]voidend_editEditing protocol - finish session
[virtual]voidend_editsEditing protocol - finish list of edits
[virtual]voidend_new_instancesInstance creation protocol - finish list of new instances
[virtual]voidend_new_shapesShape creation protocol - finish list of new shapes
[const]boolfor_technologiesReturns a value indicating whether the hooks are associated with any technology.
[const]boolis_for_technology(string tech)Returns a value indicating whether the hooks are associated with the given technology.
[virtual]voidmodified(const ObjectInstPath object,
const Shape shape,
const CplxTrans view_trans)
Modification protocol - indicate a modified object
[const]stringnameGets the name of the hooks object.
voidregister(string name)Registers the hooks in the system.
[const]string[]technologiesGets the list of technologies these hooks are associated with.
voidtechnology=(string technology)sets the name of the technology the hooks are associated with
[virtual]voidtransformed(const ObjectInstPath object,
const ICplxTrans applied_trans,
const CplxTrans view_trans)
Editing protocol - indicate an object transformation

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

_const_cast

Signature: [const] EditorHooks 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.

add_technology

Signature: void add_technology (string tech)

Description: Additionally associates the hooks with the given technology.

See also clear_technologies.

begin_create_instances

Signature: [virtual] void begin_create_instances (CellView cellview)

Description: Instance creation protocol - begin session

This method is called to initiate an instance creation session. The session is ended with end_create_instances. Between these calls, new objects are announced with begin_new_instances, create_instance and end_new_instances calls. These calls are repeated to indicate changes in the objects created.

commit_instances is called once before end_create_instances to indicate that the last set of objects is committed to the database.

begin_create_shapes

Signature: [virtual] void begin_create_shapes (CellView cellview, const LayerProperties layer)

Description: Shape creation protocol - begin session

This method is called to initiate a shape creation session. The session is ended with end_create_shapes. Between these calls, new objects are announced with begin_new_shapes, create_shape and end_new_shapes calls. These calls are repeated to indicate changes in the objects created.

commit_shapes is called once before end_create_shapes to indicate that the last set of objects is committed to the database.

begin_edit

Signature: [virtual] void begin_edit (CellView cellview)

Description: Editing protocol - begin session

This method is called to initiate an object editing session. The session is ended with end_edit. Between these calls, edits are announced with begin_edits, transformed or modified and end_edits calls. These calls are repeated to indicate changes in the objects modified while moving the mouse for example.

commit_edit is called once before end_edit to indicate that the last set of objects are committed to the database.

begin_edits

Signature: [virtual] void begin_edits

Description: Editing protocol - begin edits

See begin_edit for a description of the protocol.

begin_new_instances

Signature: [virtual] void begin_new_instances

Description: Instance creation protocol - begin new instances

See begin_create_instances for a description of the protocol.

begin_new_shapes

Signature: [virtual] void begin_new_shapes

Description: Shape creation protocol - begin new shapes

See begin_create_shapes for a description of the protocol.

clear_technologies

Signature: void clear_technologies

Description: Clears the list of technologies the hooks are associated with.

See also add_technology.

commit_edit

Signature: [virtual] void commit_edit

Description: Editing protocol - commit new objects

See begin_edit for a description of the protocol.

commit_instances

Signature: [virtual] void commit_instances

Description: Instance creation protocol - commit new objects

See begin_create_instances for a description of the protocol.

commit_shapes

Signature: [virtual] void commit_shapes

Description: Shape creation protocol - commit new objects

See begin_create_shapes for a description of the protocol.

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.

create_instance

Signature: [virtual] void create_instance (const Instance instance, const CplxTrans view_trans)

Description: Instance creation protocol - indicate a new object

See begin_create_instances for a description of the protocol.

create_shape

Signature: [virtual] void create_shape (const Shape shape, const CplxTrans view_trans)

Description: Shape creation protocol - indicate a new object

See begin_create_shapes for a description of the protocol.

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.

end_create_instances

Signature: [virtual] void end_create_instances

Description: Instance creation protocol - finish session

See begin_create for a description of the protocol.

end_create_shapes

Signature: [virtual] void end_create_shapes

Description: Shape creation protocol - finish session

See begin_create for a description of the protocol.

end_edit

Signature: [virtual] void end_edit

Description: Editing protocol - finish session

See begin_edit for a description of the protocol.

end_edits

Signature: [virtual] void end_edits

Description: Editing protocol - finish list of edits

See begin_edit for a description of the protocol.

end_new_instances

Signature: [virtual] void end_new_instances

Description: Instance creation protocol - finish list of new instances

See begin_create_instances for a description of the protocol.

end_new_shapes

Signature: [virtual] void end_new_shapes

Description: Shape creation protocol - finish list of new shapes

See begin_create_shapes for a description of the protocol.

for_technologies

Signature: [const] bool for_technologies

Description: Returns a value indicating whether the hooks are associated with any technology.

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.

is_for_technology

Signature: [const] bool is_for_technology (string tech)

Description: Returns a value indicating whether the hooks are associated with the given technology.

The method is equivalent to checking whether the technologies list is empty.

modified

Signature: [virtual] void modified (const ObjectInstPath object, const Shape shape, const CplxTrans view_trans)

Description: Modification protocol - indicate a modified object

object:A path to the modified object
shape:The new, modified shape
view_trans:The combined transformation of DBU space to view space

See begin_edit for a description of the protocol.

Note that 'object' is the original, unmodified objects while 'shape' is the modified shape. This shape object is a synthetic reference and does not exist in the database yet.

name

Signature: [const] string name

Description: Gets the name of the hooks object.

This is the name, the object was registered under in the system.

new

Signature: [static] new EditorHooks ptr new

Description: Creates a new object of this class

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

register

Signature: void register (string name)

Description: Registers the hooks in the system.

The hooks will not be active before they are registered in the system. Registration will also transfer object ownership to the system.

The name is arbitary, but should be unique. Upon registration, this hooks object will replace others with the same name already registered in the system. This will simplify debugging as you can re-run the same code, without accumulating hooks.

technologies

Signature: [const] string[] technologies

Description: Gets the list of technologies these hooks are associated with.

technology=

Signature: void technology= (string technology)

Description: sets the name of the technology the hooks are associated with

This will clear all technology associations and associate the hooks with that technology only.

Python specific notes:
The object exposes a writable attribute 'technology'. This is the setter.

transformed

Signature: [virtual] void transformed (const ObjectInstPath object, const ICplxTrans applied_trans, const CplxTrans view_trans)

Description: Editing protocol - indicate an object transformation

object:A path to the modified object
applied_trans:The DBU-space of the transformation applied to the object
view_trans:The combined transformation of DBU space to view space

See begin_edit for a description of the protocol.

Note that 'object' is the original, unmodified objects to which 'applied_trans' will be applied upon commit.