Notation used in Ruby API documentation
Module: lay
Description: This class has been introduced in version 0.30.11.
Class hierarchy: PCellParametersPage » PCellParametersPage_Native [internal] » PCellParametersPageBase [internal]
A custom PCell parameter page is creating by overloading the PCellDeclaration#create_parameters_page factory method. It returns a subclass of PCellParametersPage to implement a custom PCell parameters page.
In order to implement a custom page, as a minimum it needs to implement these features:
To be useful, the implementation should also:
Here is a Python example which implements a simple box PCell with a custom parameters page. The parameters page has a width, a height and a layer control and uses a custom layout:
import klayout.db as kdb
import klayout.lay as klay
from klayout.QtWidgets import QLineEdit, QLabel, QGridLayout
class CustomPage(klay.PCellParametersPage):
def __init__(self):
super().__init__()
def make_label(self, title, name):
if self.show_parameter_names():
return title + "[" + name + "]"
else:
return title
def build_widgets(self, container):
self.layer_sel = klay.LayerSelectionComboBox(container)
# attach the layer selection widget to the current view/cell view
self.layer_sel.set_view(self.view(), self.cv_index())
self.layer_sel.current_layer_changed += lambda: self.parameter_changed("l")
self.w_edit = QLineEdit(container)
self.w_edit.editingFinished += lambda: self.parameter_changed("w")
self.h_edit = QLineEdit(container)
self.h_edit.editingFinished += lambda: self.parameter_changed("h")
ly = QGridLayout(container)
self.ly = ly
if self.dense():
ly.setContentsMargins(0, 0, 0, 0)
ly.setSpacing(2)
else:
ly.setContentsMargins(4, 4, 4, 4)
ly.setSpacing(6)
lbl = QLabel(self.make_label("Layer", "l"), container)
ly.addWidget(lbl, 0, 0)
ly.addWidget(self.layer_sel, 0, 1, 1, 3)
lbl = QLabel(self.make_label("Width", "w"), container)
ly.addWidget(lbl, 1, 0)
ly.addWidget(self.w_edit, 1, 1)
lbl = QLabel(self.make_label("Height", "h"), container)
ly.addWidget(lbl, 1, 2)
ly.addWidget(self.h_edit, 1, 3)
ly.setColumnStretch(4, 1)
ly.setRowStretch(2, 1)
def apply_values(self, states):
l = states.parameter("l").value
self.layer_sel.current_layer = l
w = states.parameter("w").value
h = states.parameter("h").value
self.w_edit.setText("%.12g" % w)
self.h_edit.setText("%.12g" % h)
def commit_values(self, states):
states.parameter("l").value = self.layer_sel.current_layer_info()
states.parameter("w").value = float(self.w_edit.text)
states.parameter("h").value = float(self.h_edit.text)
class CustomPagePCell(kdb.PCellDeclarationHelper):
def __init__(self):
super().__init__()
self.param("l", self.TypeLayer, "Layer", default = kdb.LayerInfo(1, 0))
self.param("w", self.TypeDouble, "Width", default = 1)
self.param("h", self.TypeDouble, "Height", default = 1)
def display_text_impl(self):
return f"CustomPagePCell(w={self.w},h={self.h})"
def produce_impl(self):
self.cell.shapes(self.l_layer).insert(kdb.DBox(0, 0, self.w, self.h))
def create_parameters_page(self):
return CustomPage()
class CustomPagePCellLib(kdb.Library):
def __init__(self):
self.description = "A PCell with a custom page"
self.layout().dbu = 0.0001
self.layout().register_pcell("CustomPagePCell", CustomPagePCell())
self.register("CustomPagePCellLib")
CustomPagePCellLib()
Note, that this implementation makes use of the custom LayerSelectionComboBox widget which is borrowed from KLayout and allows selecting a layer.
| new PCellParametersPageBase ptr | new | Creates a new object of this class |
| [const] | PCellParametersPage 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. | ||
| [virtual] | void | apply_states | (const PCellParameterStates states) | Write the parameter attributes from the parameter states to the edit widgets. |
| [virtual] | void | apply_values | (const PCellParameterStates states) | Write the parameter values from the parameter states to the edit widgets. |
| void | assign | (const PCellParametersPageBase other) | Assigns another object to self | |
| [virtual] | void | build_widgets | (QFrame ptr container) | Populates the page widget. |
| void | check_range | (variant value, string name) | A utility function to check the a given values against the range given by the PCell parameter declaration. | |
| [virtual] | void | commit_values | (PCellParameterStates states) | Reads the parameter values into the parameter states |
| [const] | QFrame ptr | container_widget | Gets the container widget that holds the parameter page. | |
| [const] | int | cv_index | Gets the cell view index of the Layout object the parameter page is attached to. | |
| [const] | bool | dense | Gets a value indicating whether a dense layout is requested. | |
| [const] | new PCellParametersPageBase ptr | dup | Creates a copy of self | |
| [virtual] | variant | get_user_state | Provides some user data to be stored along with the page state. | |
| void | parameter_changed | (string name) | Signals a change in a parameter | |
| [const] | const PCellDeclaration ptr | pcell_decl | Gets the PCellDeclaration object for the PCell that is addressed in this page. | |
| [virtual] | void | set_user_state | (variant user_data) | Restores the PCell parameter page state from some user data. |
| [const] | bool | show_parameter_names | Gets a value indicating whether parameter names are to be shown. | |
| [const] | LayoutView ptr | view | Gets the view object the parameter page is attached to. |
| QPixmap | error_pixmap | Gets the standard 'error' icon pixmap used in the standard implementation for the parameter state icon. | ||
| QPixmap | info_pixmap | Gets the standard 'info' icon pixmap used in the standard implementation for the parameter state icon. | ||
| QPixmap | warning_pixmap | Gets the standard 'warning' icon pixmap used in the standard implementation for the parameter state icon. |
| 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] PCellParametersPage 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. |
apply_states | Signature: [virtual] void apply_states (const PCellParameterStates states) Description: Write the parameter attributes from the parameter states to the edit widgets. This method is supposed to change the edit widgets states like visibility or enabled state according to the attributes stored in state PCellParameterStates object. The system will update the actual values by calling the apply_values method separately. |
apply_values | Signature: [virtual] void apply_values (const PCellParameterStates states) Description: Write the parameter values from the parameter states to the edit widgets. This method is supposed to change the edit widgets to reflect the parameter values. A corresponding method to write the parameter attributes like visibility to the edit widgets is apply_states. As these steps are called under different conditions, there are two methods for updating values and states respectively. The method for updating the attributes is apply_states. The bidirectional counterpart is commit_values. |
assign | Signature: void assign (const PCellParametersPageBase other) Description: Assigns another object to self |
build_widgets | Signature: [virtual] void build_widgets (QFrame ptr container) Description: Populates the page widget. This method is supposed to populate the given container widget (a QFrame) with widgets to implement the parameter page user interface. The container widget cannot be substituted and 'build_widgets' is always called with an empty container widget. Use the dense method to get a value indicating that a dense layout shall be used for pages suitable for embedding. Use the show_parameter_names method to get a value indicating whether to include parameter names in suitable places in the user interface. Use pcell_decl to get the PCellDeclaration object for the PCell that requested this page. You can use this object to obtain the parameter declarations for the individual PCell parameters. The standard implementation uses these parameters to build a generic widget grid for the PCell parameter editors. The widgets used in the user interface should have event handlers that translate edits into calls of the parameter_changed method. This method will implement the necessary actions to trigger callbacks and to update the PCell layout dynamically or to request an update in 'lazy evaluation' mode. The 'build_widgets' method does not need to configure the widgets with values or other dynamic attributes like visibility. The system will call apply_values and apply_states to refresh values or attributes respectively. |
check_range | Signature: void check_range (variant value, string name) Description: A utility function to check the a given values against the range given by the PCell parameter declaration. On mismatch, an exception is thrown by this method. |
commit_values | Signature: [virtual] void commit_values (PCellParameterStates states) Description: Reads the parameter values into the parameter states This method is supposed to fill the parameter values in the PCellParameterStates object with the current values of the parameter editors. This method must to change the parameter states or any other attribute in the 'states' object, except the value. The bidirectional counterpart is apply_values. |
container_widget | Signature: [const] QFrame ptr container_widget Description: Gets the container widget that holds the parameter page. The container widget is a QFrame widget that needs to be populated during the execution of the 'build_widgets' method. This widgets is created freshly before 'build_widgets' is called and acts as a container custom PCell parameters page. It is not possible to substitute this widget, but it is possible to create any kind of widget subhierarchy below this page. |
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. |
cv_index | Signature: [const] int cv_index Description: Gets the cell view index of the Layout object the parameter page is attached to. |
dense | Signature: [const] bool dense Description: Gets a value indicating whether a dense layout is requested. A dense alyout is requested when the page is needed for an embedded PCell parameter page, for example in the editor options page. This flag shall be used in the implementation of the 'build_widgets' method and if set, this method should create a layout with more tightly packed widgets or smaller widget variants. |
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. |
dup | Signature: [const] new PCellParametersPageBase ptr dup Description: Creates a copy of self Python specific notes: |
error_pixmap | Signature: [static] QPixmap error_pixmap Description: Gets the standard 'error' icon pixmap used in the standard implementation for the parameter state icon. |
get_user_state | Signature: [virtual] variant get_user_state Description: Provides some user data to be stored along with the page state. The PCell parameters page sometimes persists its state to restore it later, for example, after the page has been recreated on a configuration change. The state may include things like positions of scroll bars or splitter pane sizes. This method is called to obtain state values from custom PCell parameter pages. The value is restored with set_user_state. |
info_pixmap | Signature: [static] QPixmap info_pixmap Description: Gets the standard 'info' icon pixmap used in the standard implementation for the parameter state icon. |
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. |
new | Signature: [static] new PCellParametersPageBase ptr new Description: Creates a new object of this class Python specific notes: |
parameter_changed | Signature: void parameter_changed (string name) Description: Signals a change in a parameter The PCell parameter page implementation shall call this method when a parameter has changed or was edited. Calling this method will trigger the callback function and update the PCell's layout unless lazy evaluation is selected. In that case, the 'Update' button will be shown and the user can choose to update the layout manually. Typically this method is called in a slot attached to the value-representative widget, such as a check box or line edit. Provide the name of the changed parameter through the 'name' argument or use an empty string to signal an unspecific change. |
pcell_decl | Signature: [const] const PCellDeclaration ptr pcell_decl Description: Gets the PCellDeclaration object for the PCell that is addressed in this page. |
set_user_state | Signature: [virtual] void set_user_state (variant user_data) Description: Restores the PCell parameter page state from some user data. This method is the restore counterpart for get_user_state. See documentation there for details. |
show_parameter_names | Signature: [const] bool show_parameter_names Description: Gets a value indicating whether parameter names are to be shown. This flag correlates with the respective display option. When this option changes, the widget stack is rebuilt. This flag shall be used in the implementation of the 'build_widgets' method and if set, this method should produce labels including the parameter names for visualization. |
view | Signature: [const] LayoutView ptr view Description: Gets the view object the parameter page is attached to. |
warning_pixmap | Signature: [static] QPixmap warning_pixmap Description: Gets the standard 'warning' icon pixmap used in the standard implementation for the parameter state icon. |