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.
| new EditorHooks ptr | new | Creates a new object of this class |
| [const] | EditorHooks 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 | add_technology | (string tech) | Additionally associates the hooks with the given technology. | |
| [virtual] | void | begin_create_instances | (CellView cellview) | Instance creation protocol - begin session |
| [virtual] | void | begin_create_shapes | (CellView cellview, const LayerProperties layer) | Shape creation protocol - begin session |
| [virtual] | void | begin_edit | (CellView cellview) | Editing protocol - begin session |
| [virtual] | void | begin_edits | Editing protocol - begin edits | |
| [virtual] | void | begin_new_instances | Instance creation protocol - begin new instances | |
| [virtual] | void | begin_new_shapes | Shape creation protocol - begin new shapes | |
| void | clear_technologies | Clears the list of technologies the hooks are associated with. | ||
| [virtual] | void | commit_edit | Editing protocol - commit new objects | |
| [virtual] | void | commit_instances | Instance creation protocol - commit new objects | |
| [virtual] | void | commit_shapes | Shape creation protocol - commit new objects | |
| [virtual] | void | create_instance | (const Instance instance, const CplxTrans view_trans) | Instance creation protocol - indicate a new object |
| [virtual] | void | create_shape | (const Shape shape, const CplxTrans view_trans) | Shape creation protocol - indicate a new object |
| [virtual] | void | end_create_instances | Instance creation protocol - finish session | |
| [virtual] | void | end_create_shapes | Shape creation protocol - finish session | |
| [virtual] | void | end_edit | Editing protocol - finish session | |
| [virtual] | void | end_edits | Editing protocol - finish list of edits | |
| [virtual] | void | end_new_instances | Instance creation protocol - finish list of new instances | |
| [virtual] | void | end_new_shapes | Shape creation protocol - finish list of new shapes | |
| [const] | bool | for_technologies | Returns a value indicating whether the hooks are associated with any technology. | |
| [const] | bool | is_for_technology | (string tech) | Returns a value indicating whether the hooks are associated with the given technology. |
| [virtual] | void | modified | (const ObjectInstPath object, const Shape shape, const CplxTrans view_trans) | Modification protocol - indicate a modified object |
| [const] | string | name | Gets the name of the hooks object. | |
| void | register | (string name) | Registers the hooks in the system. | |
| [const] | string[] | technologies | Gets the list of technologies these hooks are associated with. | |
| void | technology= | (string technology) | sets the name of the technology the hooks are associated with | |
| [virtual] | void | transformed | (const ObjectInstPath object, const ICplxTrans applied_trans, const CplxTrans view_trans) | Editing protocol - indicate an object transformation |
| 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] 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
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: | ||||||
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: | ||||||
transformed | Signature: [virtual] void transformed (const ObjectInstPath object, const ICplxTrans applied_trans, const CplxTrans view_trans) Description: Editing protocol - indicate an object transformation
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. |