diff --git a/src/pymod/distutils_src/klayout/dbcore.pyi b/src/pymod/distutils_src/klayout/dbcore.pyi index 2d185116b..ad12773a1 100644 --- a/src/pymod/distutils_src/klayout/dbcore.pyi +++ b/src/pymod/distutils_src/klayout/dbcore.pyi @@ -1474,6 +1474,26 @@ class Cell: This method has been introduced in version 0.22. """ ... + @overload + def change_ref(self, lib_id: int, lib_cell_index: int) -> None: + r""" + @brief Changes the reference to a different library cell + This method requires a cell that is a library reference (i.e. \is_library_cell? is true). It will change that reference to a new cell, potentially from a different library. + The library is given by library ID, the cell by cell inside inside that library. + + This method has been introduced in version 0.30.5. + """ + ... + @overload + def change_ref(self, lib_name: str, cell_name: str) -> None: + r""" + @brief Changes the reference to a different library cell + This method requires a cell that is a library reference (i.e. \is_library_cell? is true). It will change that reference to a new cell, potentially from a different library. + This version takes a library name and cell name (from that library). + + This method has been introduced in version 0.30.5. + """ + ... def child_cells(self) -> int: r""" @brief Gets the number of child cells @@ -2291,12 +2311,12 @@ class Cell: this method has been introduced in version 0.22. """ ... - def library(self) -> Library: + def library(self) -> LibraryBase: r""" @brief Returns a reference to the library from which the cell is imported if the cell is not imported from a library, this reference is nil. - this method has been introduced in version 0.22. + This method has been introduced in version 0.22. """ ... def library_cell_index(self) -> int: @@ -2506,7 +2526,7 @@ class Cell: This method has been introduced in version 0.22. """ ... - def pcell_library(self) -> Library: + def pcell_library(self) -> LibraryBase: r""" @brief Returns the library where the PCell is declared if this cell is a PCell and it is not defined locally. A PCell often is not declared within the current layout but in some library. @@ -15707,8 +15727,7 @@ class DText: Setter: @brief Sets the vertical alignment - This property specifies how the text is aligned relative to the anchor point. - This property has been introduced in version 0.22 and extended to enums in 0.28. + This is the version accepting integer values. It's provided for backward compatibility. """ x: float r""" @@ -35808,11 +35827,11 @@ class Instance: Starting with version 0.25 the displacement is of vector type. Setter: - @brief Sets the displacement vector for the 'a' axis + @brief Sets the displacement vector for the 'a' axis in micrometer units - If the instance was not an array instance before it is made one. + Like \a= with an integer displacement, this method will set the displacement vector but it accepts a vector in micrometer units that is of \DVector type. The vector will be translated to database units internally. - This method has been introduced in version 0.23. Starting with version 0.25 the displacement is of vector type. + This method has been introduced in version 0.25. """ b: Vector r""" @@ -35821,11 +35840,11 @@ class Instance: Starting with version 0.25 the displacement is of vector type. Setter: - @brief Sets the displacement vector for the 'b' axis in micrometer units + @brief Sets the displacement vector for the 'b' axis - Like \b= with an integer displacement, this method will set the displacement vector but it accepts a vector in micrometer units that is of \DVector type. The vector will be translated to database units internally. + If the instance was not an array instance before it is made one. - This method has been introduced in version 0.25. + This method has been introduced in version 0.23. Starting with version 0.25 the displacement is of vector type. """ cell: Cell r""" @@ -35868,10 +35887,9 @@ class Instance: @brief Gets the complex transformation of the instance or the first instance in the array This method is always valid compared to \trans, since simple transformations can be expressed as complex transformations as well. Setter: - @brief Sets the complex transformation of the instance or the first instance in the array (in micrometer units) - This method sets the transformation the same way as \cplx_trans=, but the displacement of this transformation is given in micrometer units. It is internally translated into database units. + @brief Sets the complex transformation of the instance or the first instance in the array - This method has been introduced in version 0.25. + This method has been introduced in version 0.23. """ da: DVector r""" @@ -36000,9 +36018,10 @@ class Instance: @brief Gets the transformation of the instance or the first instance in the array The transformation returned is only valid if the array does not represent a complex transformation array Setter: - @brief Sets the transformation of the instance or the first instance in the array + @brief Sets the transformation of the instance or the first instance in the array (in micrometer units) + This method sets the transformation the same way as \cplx_trans=, but the displacement of this transformation is given in micrometer units. It is internally translated into database units. - This method has been introduced in version 0.23. + This method has been introduced in version 0.25. """ @classmethod def new(cls) -> Instance: @@ -36365,7 +36384,7 @@ class Instance: r""" @brief Gets the layout this instance is contained in - This const version of the method has been introduced in version 0.25. + This method has been introduced in version 0.22. """ ... @overload @@ -36373,7 +36392,7 @@ class Instance: r""" @brief Gets the layout this instance is contained in - This method has been introduced in version 0.22. + This const version of the method has been introduced in version 0.25. """ ... def pcell_declaration(self) -> PCellDeclaration_Native: @@ -38997,7 +39016,7 @@ class Layout: From version 0.23 on this method is deprecated because another method exists which is more convenient because is returns a \Cell object (\create_cell). """ ... - def add_lib_cell(self, library: Library, lib_cell_index: int) -> int: + def add_lib_cell(self, library: LibraryBase, lib_cell_index: int) -> int: r""" @brief Imports a cell from the library @param library The reference to the library from which to import the cell @@ -39019,7 +39038,7 @@ class Layout: """ ... @overload - def add_pcell_variant(self, library: Library, pcell_id: int, parameters: Dict[str, Any]) -> int: + def add_pcell_variant(self, library: LibraryBase, pcell_id: int, parameters: Dict[str, Any]) -> int: r""" @brief Creates a PCell variant for a PCell located in an external library with the parameters given as a name/value dictionary @return The cell index of the new proxy cell in this layout @@ -39040,7 +39059,7 @@ class Layout: """ ... @overload - def add_pcell_variant(self, library: Library, pcell_id: int, parameters: Sequence[Any]) -> int: + def add_pcell_variant(self, library: LibraryBase, pcell_id: int, parameters: Sequence[Any]) -> int: r""" @brief Creates a PCell variant for a PCell located in an external library @return The cell index of the new proxy cell in this layout @@ -40205,7 +40224,7 @@ class Layout: The number of layers reports the maximum (plus 1) layer index used so far. Not all of the layers with an index in the range of 0 to layers-1 needs to be a valid layer. These layers can be either valid, special or unused. Use \is_valid_layer? and \is_special_layer? to test for the first two states. """ ... - def library(self) -> Library: + def library(self) -> LibraryBase: r""" @brief Gets the library this layout lives in or nil if the layout is not part of a library This attribute has been introduced in version 0.27.5. @@ -43842,7 +43861,7 @@ class LayoutVsSchematic(LayoutToNetlist): ... ... -class Library: +class Library(LibraryBase): r""" @brief A Library @@ -43856,6 +43875,89 @@ class Library: This class has been introduced in version 0.22. """ + @classmethod + def new(cls) -> Library: + r""" + @brief Creates a new, empty library + """ + ... + def __init__(self) -> None: + r""" + @brief Creates a new, empty library + """ + ... + def _assign(self, other: LibraryBase) -> None: + r""" + @brief Assigns another object to self + """ + ... + def _const_cast(self) -> Library: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _dup(self) -> Library: + r""" + @brief Creates a copy of self + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> Library: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + ... + +class LibraryBase: + r""" + @hide + """ description: str r""" Getter: @@ -43877,7 +43979,7 @@ class Library: See \technology for details. This attribute has been introduced in version 0.25. In version 0.27, a library can be associated with multiple technologies and this method will revert the selection to a single one. Passing an empty string is equivalent to \clear_technologies. """ @classmethod - def library_by_id(cls, id: int) -> Library: + def library_by_id(cls, id: int) -> LibraryBase: r""" @brief Gets the library object for the given ID If the ID is not valid, nil is returned. @@ -43886,11 +43988,10 @@ class Library: """ ... @classmethod - def library_by_name(cls, name: str, for_technology: Optional[str] = ...) -> Library: + def library_by_name(cls, name: str, for_technology: Optional[str] = ...) -> LibraryBase: r""" @brief Gets a library by name - Returns the library object for the given name. If the name is not a valid - library name, nil is returned. + Returns the library object for the given name. If the name is not a valid library name, nil is returned. Different libraries can be registered under the same names for different technologies. When a technology name is given in 'for_technologies', the first library matching this technology is returned. If no technology is given, the first library is returned. @@ -43914,27 +44015,35 @@ class Library: """ ... @classmethod - def new(cls) -> Library: + def new(cls) -> LibraryBase: r""" - @brief Creates a new, empty library + @brief Creates a new object of this class """ ... - def __copy__(self) -> Library: + @classmethod + def refresh_all(cls) -> None: + r""" + @brief Calls \refresh on all libraries. + + This convenience method has been introduced in version 0.30.4. + """ + ... + def __copy__(self) -> LibraryBase: r""" @brief Creates a copy of self """ ... - def __deepcopy__(self) -> Library: + def __deepcopy__(self) -> LibraryBase: r""" @brief Creates a copy of self """ ... def __init__(self) -> None: r""" - @brief Creates a new, empty library + @brief Creates a new object of this class """ ... - def _const_cast(self) -> Library: + def _const_cast(self) -> LibraryBase: r""" @brief 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. @@ -43977,7 +44086,7 @@ class Library: Usually it's not required to call this method. It has been introduced in version 0.24. """ ... - def _to_const_object(self) -> Library: + def _to_const_object(self) -> LibraryBase: r""" @hide """ @@ -43998,7 +44107,7 @@ class Library: This method has been introduced in version 0.27 """ ... - def assign(self, other: Library) -> None: + def assign(self, other: LibraryBase) -> None: r""" @brief Assigns another object to self """ @@ -44040,7 +44149,7 @@ class Library: The latter may happen, if the object is owned by a C++ object which got destroyed itself. """ ... - def dup(self) -> Library: + def dup(self) -> LibraryBase: r""" @brief Creates a copy of self """ @@ -44085,14 +44194,15 @@ class Library: def name(self) -> str: r""" @brief Returns the libraries' name - The name is set when the library is registered and cannot be changed + The name is set when the library is registered. To change it use \rename. """ ... def refresh(self) -> None: r""" @brief Updates all layouts using this library. This method will retire cells or update layouts in the attached clients. - It will also recompute the PCells inside the library. + It will also recompute the PCells inside the library. Starting with version 0.30.5, this method will also call 'reload' on all libraries to refresh cells located in external files. + This method has been introduced in version 0.27.8. """ ... @@ -44109,12 +44219,30 @@ class Library: The technology specific behaviour has been introduced in version 0.27. """ ... + def rename(self, name: str) -> None: + r""" + @brief Renames the library + + Re-registers the library under a new name. Note that this method will also change the references to the library. + + This method has been introduced in version 0.30.5. + """ + ... def technologies(self) -> List[str]: r""" @brief Gets the list of technologies this library is associated with. This method has been introduced in version 0.27 """ ... + def unregister(self) -> None: + r""" + @brief Unregisters the library + + Unregisters the library from the system. This will break all references of cells using this library and make them 'defunct'. + + This method has been introduced in version 0.30.5. + """ + ... ... class LoadLayoutOptions: @@ -44644,6 +44772,13 @@ class LoadLayoutOptions: This method has been added in version 0.25. """ + lstream_bbox_meta_info_key: str + r""" + Getter: + @brief If not an empty string, this attribute specifies the key under which the cell bounding box information is stored + Setter: + @brief If not an empty string, this attribute specifies the key under which the cell bounding box information is stored + """ mag_create_other_layers: bool r""" Getter: @@ -47473,15 +47608,15 @@ class NetPinRef: @overload def net(self) -> Net: r""" - @brief Gets the net this pin reference is attached to. + @brief Gets the net this pin reference is attached to (non-const version). + + This constness variant has been introduced in version 0.26.8 """ ... @overload def net(self) -> Net: r""" - @brief Gets the net this pin reference is attached to (non-const version). - - This constness variant has been introduced in version 0.26.8 + @brief Gets the net this pin reference is attached to. """ ... def pin(self) -> Pin: @@ -47804,15 +47939,15 @@ class NetTerminalRef: @overload def net(self) -> Net: r""" - @brief Gets the net this terminal reference is attached to. + @brief Gets the net this terminal reference is attached to (non-const version). + + This constness variant has been introduced in version 0.26.8 """ ... @overload def net(self) -> Net: r""" - @brief Gets the net this terminal reference is attached to (non-const version). - - This constness variant has been introduced in version 0.26.8 + @brief Gets the net this terminal reference is attached to. """ ... def terminal_def(self) -> DeviceTerminalDefinition: @@ -51440,6 +51575,11 @@ class PCellDeclaration(PCellDeclaration_Native): @hide """ ... + def cell_name(self, arg0: Sequence[Any]) -> str: + r""" + @hide + """ + ... def description(self) -> str: r""" @hide @@ -51577,6 +51717,10 @@ class PCellDeclaration_Native: r""" """ ... + def cell_name(self, parameters: Sequence[Any]) -> str: + r""" + """ + ... def coerce_parameters(self, layout: Layout, parameters: Sequence[Any]) -> List[Any]: r""" """ @@ -63549,12 +63693,12 @@ class SaveLayoutOptions: dbu: float r""" Getter: - @brief Get the explicit database unit if one is set + @brief Gets the explicit database unit if one is set See \dbu= for a description of that attribute. Setter: - @brief Set the database unit to be used in the stream file + @brief Sets the database unit to be used in the stream file By default, the database unit of the layout is used. This method allows one to explicitly use a different database unit. A scale factor is introduced automatically which scales all layout objects accordingly so their physical dimensions remain the same. When scaling to a larger database unit or one that is not an integer fraction of the original one, rounding errors may occur and the layout may become slightly distorted. @@ -63608,17 +63752,19 @@ class SaveLayoutOptions: gds2_libname: str r""" Getter: - @brief Get the library name - See \gds2_libname= method for a description of the library name. - This property has been added in version 0.18. + @brief Gets the library name + See \libname= for details. + The 'libname' alias has been introduced in version 0.30.5. The original name \gds2_libname is still available. Setter: - @brief Set the library name + @brief Sets the library name - The library name is the string written into the LIBNAME records of the GDS file. - The library name should not be an empty string and is subject to certain limitations in the character choice. + The library name is an attribute and specifies a formal name for a library, if the layout files is to be used as one. + Currently, this attribute is only supported by the GDS2 format. Hence the alias. - This property has been added in version 0.18. + By default or if the libname is an empty string, the current library name of the layout or 'LIB' is used. + + The 'libname' alias has been introduced in version 0.30.5. The original name \gds2_libname= is still available. """ gds2_max_cellname_length: int r""" @@ -63776,6 +63922,50 @@ class SaveLayoutOptions: This method was introduced in version 0.23. """ + libname: str + r""" + Getter: + @brief Gets the library name + + See \libname= for details. + The 'libname' alias has been introduced in version 0.30.5. The original name \gds2_libname is still available. + Setter: + @brief Sets the library name + + The library name is an attribute and specifies a formal name for a library, if the layout files is to be used as one. + Currently, this attribute is only supported by the GDS2 format. Hence the alias. + + By default or if the libname is an empty string, the current library name of the layout or 'LIB' is used. + + The 'libname' alias has been introduced in version 0.30.5. The original name \gds2_libname= is still available. + """ + lstream_compression_level: int + r""" + Getter: + @brief Get the LStream compression level + See \oasis_compression_level= method for a description of the LStream compression level. + Setter: + @brief Set the LStream compression level + The LStream compression level is an integer number between 0 and 10. 0 basically is no compression, 1 produces shape arrays in a simple fashion. 2 and higher compression levels will use a more elaborate algorithm to find shape arrays which uses 2nd and further neighbor distances. The higher the level, the higher the memory requirements and run times. + """ + lstream_permissive: bool + r""" + Getter: + @brief Gets the LStream permissive mode + See \oasis_permissive= method for a description of this predicate. + Setter: + @brief Sets LStream permissive mode + If this flag is true, certain shapes which cannot be written to LStream are reported as warnings, not as errors. For example, paths with odd width (are rounded). + """ + lstream_recompress: bool + r""" + Getter: + @brief Gets the LStream recompression mode + See \oasis_recompress= method for a description of this predicate. + Setter: + @brief Sets LStream recompression mode + If this flag is true, shape arrays already existing will be resolved and compression is applied to the individual shapes again. If this flag is false (the default), shape arrays already existing will be written as such. + """ mag_lambda: float r""" Getter: @@ -63939,7 +64129,7 @@ class SaveLayoutOptions: @brief Gets the scaling factor currently set Setter: - @brief Set the scaling factor for the saving + @brief Sets the scaling factor for the saving Using a scaling factor will scale all objects accordingly. This scale factor adds to a potential scaling implied by using an explicit database unit. @@ -65055,11 +65245,10 @@ class Shape: Starting with version 0.23, this method returns nil, if the shape does not represent a text. Setter: - @brief 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. + @brief Replaces the shape by the given text (in micrometer units) + This method replaces the shape by the given text, like \text= with a \Text argument does. This version translates the text from micrometer units to database units internally. - This method has been introduced in version 0.22. + This method has been introduced in version 0.25. """ text_dpos: DVector r""" @@ -69275,16 +69464,16 @@ class SubCircuit(NetlistObject): @overload def circuit_ref(self) -> Circuit: r""" - @brief Gets the circuit referenced by the subcircuit (non-const version). - - - This constness variant has been introduced in version 0.26.8 + @brief Gets the circuit referenced by the subcircuit. """ ... @overload def circuit_ref(self) -> Circuit: r""" - @brief Gets the circuit referenced by the subcircuit. + @brief Gets the circuit referenced by the subcircuit (non-const version). + + + This constness variant has been introduced in version 0.26.8 """ ... @overload @@ -69330,17 +69519,17 @@ class SubCircuit(NetlistObject): @overload def net_for_pin(self, pin_id: int) -> Net: r""" - @brief Gets the net connected to the specified pin of the subcircuit. + @brief Gets the net connected to the specified pin of the subcircuit (non-const version). If the pin is not connected, nil is returned for the net. + + This constness variant has been introduced in version 0.26.8 """ ... @overload def net_for_pin(self, pin_id: int) -> Net: r""" - @brief Gets the net connected to the specified pin of the subcircuit (non-const version). + @brief Gets the net connected to the specified pin of the subcircuit. If the pin is not connected, nil is returned for the net. - - This constness variant has been introduced in version 0.26.8 """ ... ... @@ -69991,8 +70180,7 @@ class Text: Setter: @brief Sets the vertical alignment - This property specifies how the text is aligned relative to the anchor point. - This property has been introduced in version 0.22 and extended to enums in 0.28. + This is the version accepting integer values. It's provided for backward compatibility. """ x: int r""" diff --git a/src/pymod/distutils_src/klayout/laycore.pyi b/src/pymod/distutils_src/klayout/laycore.pyi index cddb19ee2..8d821c6d1 100644 --- a/src/pymod/distutils_src/klayout/laycore.pyi +++ b/src/pymod/distutils_src/klayout/laycore.pyi @@ -726,6 +726,243 @@ class ActionBase: ... ... +class AngleConstraintType: + r""" + @brief Specifies angle constraints during snapping. + + This enum has been introduced in version 0.30.4. + """ + AC_Any: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use any angle and not snap to a specific direction. + """ + AC_Diagonal: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use multiples of 45 degree. + """ + AC_Global: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use the global angle constraint. + """ + AC_Horizontal: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use horizontal direction only. + """ + AC_Ortho: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use multiples of 90 degree. + """ + AC_Vertical: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use vertical direction only. + """ + @overload + @classmethod + def new(cls, i: int) -> AngleConstraintType: + r""" + @brief Creates an enum from an integer value + """ + ... + @overload + @classmethod + def new(cls, s: str) -> AngleConstraintType: + r""" + @brief Creates an enum from a string value + """ + ... + def __copy__(self) -> AngleConstraintType: + r""" + @brief Creates a copy of self + """ + ... + def __deepcopy__(self) -> AngleConstraintType: + r""" + @brief Creates a copy of self + """ + ... + @overload + def __eq__(self, other: int) -> bool: + r""" + @brief Compares an enum with an integer value + """ + ... + @overload + def __eq__(self, other: object) -> bool: + r""" + @brief Compares two enums + """ + ... + def __hash__(self) -> int: + r""" + @brief Gets the hash value from the enum + """ + ... + @overload + def __init__(self, i: int) -> None: + r""" + @brief Creates an enum from an integer value + """ + ... + @overload + def __init__(self, s: str) -> None: + r""" + @brief Creates an enum from a string value + """ + ... + def __int__(self) -> int: + r""" + @brief Gets the integer value from the enum + """ + ... + @overload + def __lt__(self, other: AngleConstraintType) -> bool: + r""" + @brief Returns true if the first enum is less (in the enum symbol order) than the second + """ + ... + @overload + def __lt__(self, other: int) -> bool: + r""" + @brief Returns true if the enum is less (in the enum symbol order) than the integer value + """ + ... + @overload + def __ne__(self, other: int) -> bool: + r""" + @brief Compares an enum with an integer for inequality + """ + ... + @overload + def __ne__(self, other: object) -> bool: + r""" + @brief Compares two enums for inequality + """ + ... + def __repr__(self) -> str: + r""" + @brief Converts an enum to a visual string + """ + ... + def __str__(self) -> str: + r""" + @brief Gets the symbolic string from an enum + """ + ... + def _const_cast(self) -> AngleConstraintType: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> AngleConstraintType: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + def assign(self, other: AngleConstraintType) -> None: + r""" + @brief Assigns another object to self + """ + ... + def create(self) -> None: + r""" + @brief 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. + """ + ... + def destroy(self) -> None: + r""" + @brief 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. + """ + ... + def destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def dup(self) -> AngleConstraintType: + r""" + @brief Creates a copy of self + """ + ... + def hash(self) -> int: + r""" + @brief Gets the hash value from the enum + """ + ... + def inspect(self) -> str: + r""" + @brief Converts an enum to a visual string + """ + ... + def is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def to_i(self) -> int: + r""" + @brief Gets the integer value from the enum + """ + ... + def to_s(self) -> str: + r""" + @brief Gets the symbolic string from an enum + """ + ... + ... + class Annotation(BasicAnnotation): r""" @brief A layout annotation (i.e. ruler) @@ -1954,6 +2191,158 @@ class BitmapBuffer: ... ... +class ButtonState: + r""" + @brief The namespace for the button state flags in the mouse events of the Plugin class. + This class defines the constants for the button state. In the event handler, the button state is indicated by a bitwise combination of these constants. See \Plugin for further details. + This class has been introduced in version 0.22. + """ + AltKey: ClassVar[int] + r""" + @brief Indicates that the Alt key is pressed + This constant is combined with other constants within \ButtonState + """ + ControlKey: ClassVar[int] + r""" + @brief Indicates that the Control key is pressed + This constant is combined with other constants within \ButtonState + """ + LeftButton: ClassVar[int] + r""" + @brief Indicates that the left mouse button is pressed + This constant is combined with other constants within \ButtonState + """ + MidButton: ClassVar[int] + r""" + @brief Indicates that the middle mouse button is pressed + This constant is combined with other constants within \ButtonState + """ + RightButton: ClassVar[int] + r""" + @brief Indicates that the right mouse button is pressed + This constant is combined with other constants within \ButtonState + """ + ShiftKey: ClassVar[int] + r""" + @brief Indicates that the Shift key is pressed + This constant is combined with other constants within \ButtonState + """ + @classmethod + def new(cls) -> ButtonState: + r""" + @brief Creates a new object of this class + """ + ... + def __copy__(self) -> ButtonState: + r""" + @brief Creates a copy of self + """ + ... + def __deepcopy__(self) -> ButtonState: + r""" + @brief Creates a copy of self + """ + ... + def __init__(self) -> None: + r""" + @brief Creates a new object of this class + """ + ... + def _const_cast(self) -> ButtonState: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> ButtonState: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + def assign(self, other: ButtonState) -> None: + r""" + @brief Assigns another object to self + """ + ... + def create(self) -> None: + r""" + @brief 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. + """ + ... + def destroy(self) -> None: + r""" + @brief 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. + """ + ... + def destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def dup(self) -> ButtonState: + r""" + @brief Creates a copy of self + """ + ... + def is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + ... + class CellView: r""" @brief A class describing what is shown inside a layout view @@ -2385,6 +2774,208 @@ class CellView: ... ... +class Cursor: + r""" + @brief The namespace for the cursor constants + This class defines the constants for the cursor setting (for example for method \Plugin#set_cursor). + This class has been introduced in version 0.22. + """ + Arrow: ClassVar[int] + r""" + @brief 'Arrow cursor' constant + """ + Blank: ClassVar[int] + r""" + @brief 'Blank cursor' constant + """ + Busy: ClassVar[int] + r""" + @brief 'Busy state cursor' constant + """ + ClosedHand: ClassVar[int] + r""" + @brief 'Closed hand cursor' constant + """ + Cross: ClassVar[int] + r""" + @brief 'Cross cursor' constant + """ + Forbidden: ClassVar[int] + r""" + @brief 'Forbidden area cursor' constant + """ + IBeam: ClassVar[int] + r""" + @brief 'I beam (text insert) cursor' constant + """ + None_: ClassVar[int] + r""" + @brief 'No cursor (default)' constant for \Plugin#set_cursor (resets cursor to default) + """ + OpenHand: ClassVar[int] + r""" + @brief 'Open hand cursor' constant + """ + PointingHand: ClassVar[int] + r""" + @brief 'Pointing hand cursor' constant + """ + SizeAll: ClassVar[int] + r""" + @brief 'Size all directions cursor' constant + """ + SizeBDiag: ClassVar[int] + r""" + @brief 'Backward diagonal resize cursor' constant + """ + SizeFDiag: ClassVar[int] + r""" + @brief 'Forward diagonal resize cursor' constant + """ + SizeHor: ClassVar[int] + r""" + @brief 'Horizontal resize cursor' constant + """ + SizeVer: ClassVar[int] + r""" + @brief 'Vertical resize cursor' constant + """ + SplitH: ClassVar[int] + r""" + @brief 'split_horizontal cursor' constant + """ + SplitV: ClassVar[int] + r""" + @brief 'Split vertical cursor' constant + """ + UpArrow: ClassVar[int] + r""" + @brief 'Upward arrow cursor' constant + """ + Wait: ClassVar[int] + r""" + @brief 'Waiting cursor' constant + """ + WhatsThis: ClassVar[int] + r""" + @brief 'Question mark cursor' constant + """ + @classmethod + def new(cls) -> Cursor: + r""" + @brief Creates a new object of this class + """ + ... + def __copy__(self) -> Cursor: + r""" + @brief Creates a copy of self + """ + ... + def __deepcopy__(self) -> Cursor: + r""" + @brief Creates a copy of self + """ + ... + def __init__(self) -> None: + r""" + @brief Creates a new object of this class + """ + ... + def _const_cast(self) -> Cursor: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> Cursor: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + def assign(self, other: Cursor) -> None: + r""" + @brief Assigns another object to self + """ + ... + def create(self) -> None: + r""" + @brief 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. + """ + ... + def destroy(self) -> None: + r""" + @brief 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. + """ + ... + def destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def dup(self) -> Cursor: + r""" + @brief Creates a copy of self + """ + ... + def is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + ... + class Dispatcher: r""" @brief Root of the configuration space in the plugin context and menu dispatcher @@ -3903,6 +4494,194 @@ class ImageDataMapping: ... ... +class KeyCode: + r""" + @brief The namespace for the some key codes. + This namespace defines some key codes understood by built-in \LayoutView components. When compiling with Qt, these codes are compatible with Qt's key codes. + The key codes are intended to be used when directly interfacing with \LayoutView in non-Qt-based environments. + + This class has been introduced in version 0.28. + """ + Backspace: ClassVar[int] + r""" + @brief Indicates the Backspace key + """ + Backtab: ClassVar[int] + r""" + @brief Indicates the Backtab key + """ + Delete: ClassVar[int] + r""" + @brief Indicates the Delete key + """ + Down: ClassVar[int] + r""" + @brief Indicates the Down key + """ + End: ClassVar[int] + r""" + @brief Indicates the End key + """ + Enter: ClassVar[int] + r""" + @brief Indicates the Enter key + """ + Escape: ClassVar[int] + r""" + @brief Indicates the Escape key + """ + Home: ClassVar[int] + r""" + @brief Indicates the Home key + """ + Insert: ClassVar[int] + r""" + @brief Indicates the Insert key + """ + Left: ClassVar[int] + r""" + @brief Indicates the Left key + """ + PageDown: ClassVar[int] + r""" + @brief Indicates the PageDown key + """ + PageUp: ClassVar[int] + r""" + @brief Indicates the PageUp key + """ + Return: ClassVar[int] + r""" + @brief Indicates the Return key + """ + Right: ClassVar[int] + r""" + @brief Indicates the Right key + """ + Tab: ClassVar[int] + r""" + @brief Indicates the Tab key + """ + Up: ClassVar[int] + r""" + @brief Indicates the Up key + """ + @classmethod + def new(cls) -> KeyCode: + r""" + @brief Creates a new object of this class + """ + ... + def __copy__(self) -> KeyCode: + r""" + @brief Creates a copy of self + """ + ... + def __deepcopy__(self) -> KeyCode: + r""" + @brief Creates a copy of self + """ + ... + def __init__(self) -> None: + r""" + @brief Creates a new object of this class + """ + ... + def _const_cast(self) -> KeyCode: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> KeyCode: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + def assign(self, other: KeyCode) -> None: + r""" + @brief Assigns another object to self + """ + ... + def create(self) -> None: + r""" + @brief 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. + """ + ... + def destroy(self) -> None: + r""" + @brief 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. + """ + ... + def destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def dup(self) -> KeyCode: + r""" + @brief Creates a copy of self + """ + ... + def is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + ... + class LayerProperties: r""" @brief The layer properties structure @@ -5721,6 +6500,7 @@ class LayoutViewBase(Dispatcher): Setter: @brief Makes the cellview with the given index the active one (shown in hierarchy browser) See \active_cellview_index. + Note, that this changing the active cell view index has side effects such as terminating an editing operation. This method has been renamed from set_active_cellview_index to active_cellview_index= in version 0.25. The original name is still available, but is deprecated. """ @@ -5754,6 +6534,7 @@ class LayoutViewBase(Dispatcher): WARNING: This variable can only be set, not retrieved. @brief Makes the cellview with the given index the active one (shown in hierarchy browser) See \active_cellview_index. + Note, that this changing the active cell view index has side effects such as terminating an editing operation. This method has been renamed from set_active_cellview_index to active_cellview_index= in version 0.25. The original name is still available, but is deprecated. """ @@ -5923,6 +6704,24 @@ class LayoutViewBase(Dispatcher): When this event is triggered, the cellviews have already been changed. Before version 0.25 this event was based on the observer pattern obsolete now. The corresponding methods (add_cellview_list_observer/remove_cellview_list_observer) have been removed in 0.25. """ + on_current_layer_changed: None + r""" + Getter: + @brief An event indicating the current layer has changed + @param new_layer The layer iterator of the new current layer + + This event is triggered after the current layer was changed - i.e. a new layer is selected in the layer list. + + This event was introduced in version 0.30.5. + + Setter: + @brief An event indicating the current layer has changed + @param new_layer The layer iterator of the new current layer + + This event is triggered after the current layer was changed - i.e. a new layer is selected in the layer list. + + This event was introduced in version 0.30.5. + """ on_current_layer_list_changed: None r""" Getter: @@ -6079,6 +6878,22 @@ class LayoutViewBase(Dispatcher): This event was translated from the Observer pattern to an event in version 0.25. """ + on_selected_layers_changed: None + r""" + Getter: + @brief An event indicating the layer selection has changed + + This event is triggered after the layer selection was changed - i.e. layers got selected or unselected. + + This event was introduced in version 0.30.5. + + Setter: + @brief An event indicating the layer selection has changed + + This event is triggered after the layer selection was changed - i.e. layers got selected or unselected. + + This event was introduced in version 0.30.5. + """ on_selection_changed: None r""" Getter: @@ -7626,6 +8441,7 @@ class LayoutViewBase(Dispatcher): r""" @brief Makes the cellview with the given index the active one (shown in hierarchy browser) See \active_cellview_index. + Note, that this changing the active cell view index has side effects such as terminating an editing operation. This method has been renamed from set_active_cellview_index to active_cellview_index= in version 0.25. The original name is still available, but is deprecated. """ @@ -10058,3 +10874,1015 @@ class PixelBuffer: ... ... +class Plugin(PluginBase): + r""" + @brief The plugin object + + This class provides the actual plugin implementation. Each view gets its own instance of the plugin class. The plugin factory \PluginFactory class must be specialized to provide a factory for new objects of the Plugin class. See the documentation there for details about the plugin mechanism and the basic concepts. + + This class has been introduced in version 0.22. + """ + AC_Any: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use any angle and not snap to a specific direction. + """ + AC_Diagonal: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use multiples of 45 degree. + """ + AC_Global: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use the global angle constraint. + """ + AC_Horizontal: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use horizontal direction only. + """ + AC_Ortho: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use multiples of 90 degree. + """ + AC_Vertical: ClassVar[AngleConstraintType] + r""" + @brief Specifies to use vertical direction only. + """ + @classmethod + def ac_from_buttons(cls, buttons: int) -> AngleConstraintType: + r""" + @brief Creates an angle constraint from a button combination + This method provides the angle constraints implied by a specific modifier combination, i.e. 'Shift' will render ortho snapping. Use this function to generate angle constraints following the established conventions. + + This method has been added in version 0.30.4. + """ + ... + def _const_cast(self) -> Plugin: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> Plugin: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + @overload + def add_edge_marker(self, e: db.DEdge, emphasize: Optional[bool] = ...) -> None: + r""" + @brief Creates a cursor to indicate an edge + This function will create a marker that indicates an edge - for example the edge that a point is snapping to. + If 'emphasize' is true, the cursor is displayed in a 'stronger' style. + + Before you use this method, clear existing edge markers and cursors with \clear_mouse_cursors. + + This method has been added in version 0.30.4. + """ + ... + @overload + def add_edge_marker(self, e: db.Edge, cv_index: int, layer: db.LayerInfo, emphasize: Optional[bool] = ...) -> None: + r""" + @brief Creates a cursor to indicate an edge + This version of this method creates an edge marker based on the integer-unit edge and + a source cellview index plus a layer info. + The cellview index and layer info is used to derive the transformation rules to apply to the edge and to compute the final position. + + This method has been added in version 0.30.4. + """ + ... + @overload + def add_mouse_cursor(self, p: db.DPoint, emphasize: Optional[bool] = ...) -> None: + r""" + @brief Creates a cursor to indicate the mouse position + This function will create a marker that indicates the (for example snapped) mouse position. + In addition to this, it will establish the position for the tracking cursor, if mouse + tracking is enabled in the application. You can override the tracking position by reimplementing + \tracking_position and \has_tracking_position. + + To enable tracking, make sure a reimplementation of \mouse_moved_event does not consume the + event and returns 'false'. + + Multiple cursors can be created. In that case, the tracking position is given by the last cursor. + + If 'emphasize' is true, the cursor is displayed in a 'stronger' style - i.e. with a double circle instead of a single one. + + Before you use this method, clear existing cursors with \clear_mouse_cursors. + + This method has been added in version 0.30.4. + """ + ... + @overload + def add_mouse_cursor(self, p: db.Point, cv_index: int, layer: db.LayerInfo, emphasize: Optional[bool] = ...) -> None: + r""" + @brief Creates a cursor to indicate the mouse position + This version of this method creates a mouse cursor based on the integer-unit point and + a source cellview index plus a layer info. + The cellview index and layer info is used to derive the transformation rules to apply to the point and to compute the final position. + + This method has been added in version 0.30.4. + """ + ... + def clear_mouse_cursors(self) -> None: + r""" + @brief Clears all existing mouse cursors + Use this function to remove exisiting mouse cursors (see \add_mouse_cursor and \add_edge_marker). + This method is automatically called when the plugin becomes deactivated. + + This method has been added in version 0.30.4. + """ + ... + def configure_test(self, name: str, value: str) -> None: + r""" + @hide + """ + ... + def dispatcher(self) -> Dispatcher: + r""" + @brief Gets the dispatcher object the plugin is associated with + This method returns the dispatcher object that the plugin is associated with. + The dispatcher object manages the configuration parameters. 'set_config', 'get_config' and 'commit_config' can be used on this object to get or set configuration parameters. Configuration parameters are a way to persist information and the preferred way of communicating with editor option pages and configuration pages. + + This convenience method has been added in version 0.30.4. + """ + ... + def grab_mouse(self) -> None: + r""" + @brief Redirects mouse events to this plugin, even if the plugin is not active. + """ + ... + def has_tracking_position_test(self) -> bool: + r""" + @hide + """ + ... + def set_cursor(self, cursor_type: int) -> None: + r""" + @brief Sets the cursor in the view area to the given type + Setting the cursor has an effect only inside event handlers, i.e. \mouse_button_pressed_event. The cursor is not set permanently. Is is reset in the mouse move handler unless a button is pressed or the cursor is explicitly set again in \mouse_moved_event. + + The cursor type is one of the cursor constants in the \Cursor class, i.e. 'CursorArrow' for the normal cursor. + """ + ... + @overload + def snap(self, p: db.DPoint) -> db.DPoint: + r""" + @brief Snaps a point to the edit grid + + @param p The point to snap + + If the edit grid is given, the point's x and y components + are snapped to the edit grid. Otherwise the global grid is used. + Edit and global grid are set by configuration options. + + This method has been added in version 0.30.4. + """ + ... + @overload + def snap(self, p: db.DPoint, plast: db.DPoint, connect: Optional[bool] = ..., ac: Optional[AngleConstraintType] = ...) -> db.DPoint: + r""" + @brief Snaps a point to the edit grid with an angle constraint + + @param p The point to snap + @param plast The last point of the connection/move vector + @param connect true, if the point is an connection vertex, false if it is a move target point + @param ac Overrides the connect or move angle constraint unless it is \Plugin#AC_Global + + This method snaps point "p" relative to the initial point "plast". This method + tries to snap "p" to the edit or global grid (edit grid with higher priority), while + trying to observe the angle constraint that imposes a constraint on the way "p" + can move relative to "plast". + + The "connect" parameter will decide which angle constraint to use, unless "ac" specifies + an angle constraint already. If "connect" is true, the line between "p" and "plast" is regarded a connection + between points (e.g. a polygon edge) and the connection angle constraint applies. Otherwise + the move constraint applies. + + The angle constraint determines how "p" can move in relation to "plast" - for example, + if the angle constraint is \Plugin#AC_Ortho, "p" can only move away from "plast" in horizontal or vertical direction. + + This method has been added in version 0.30.4. + """ + ... + @overload + def snap(self, v: db.DVector) -> db.DVector: + r""" + @brief Snaps a vector to the edit grid + + @param v The vector to snap + + If the edit grid is given, the vector's x and y components + are snapped to the edit grid. Otherwise the global grid is used. + Edit and global grid are set by configuration options. + + This method has been added in version 0.30.4. + """ + ... + @overload + def snap(self, v: db.DVector, connect: Optional[bool] = ..., ac: Optional[AngleConstraintType] = ...) -> db.DVector: + r""" + @brief Snaps a move vector to the edit grid with and implies an angle constraint + + @param v The vector to snap + @param connect true, if the vector is an connection vector, false if it is a move vector + @param ac Overrides the connect or move angle constraint unless it is AC_Global + + The "connect" parameter will decide which angle constraint to use, unless "ac" specifies + an angle constraint already. If "connect" is true, the vector is regarded a connection line + between points (e.g. a polygon edge) and the connection angle constraint applies. Otherwise + the move constraint applies. + + The angle constraint determines how "p" can move in relation to "plast" - for example, + if the angle constraint is \Plugin#AC_Ortho, "p" can only move away from "plast" in horizontal or vertical direction. + + This method has been added in version 0.30.4. + """ + ... + @overload + def snap2(self, p: db.DPoint, plast: db.DPoint, connect: Optional[bool] = ..., ac: Optional[AngleConstraintType] = ..., visualize: Optional[bool] = ...) -> db.DPoint: + r""" + @brief Snaps a point to the edit grid with an angle constraint with advanced snapping (including object snapping) + + @param p The point to snap + @param plast The last point of the connection or move start point + @param connect true, if the point is an connection, false if it is a move target point + @param ac Overrides the connect or move angle constraint unless it is AC_Global + @param visualize If true, a cursor shape is added to the scene indicating the snap details + + This method will snap the point p, given an initial point "plast". This includes an angle constraint. + If "connect" is true, the line between "plast" and "p" is regarded a connection (e.g. a polygon edge). + If not, the line is regarded a move vector. If "ac" is \Plugin#AC_Global, the angle constraint is + taken from the connect or move angle constraint, depending on the value of "connect". The angle constraint + determines how "p" can move in relation to "plast" - for example, if the angle constraint is \Plugin#AC_Ortho, + "p" can only move away from "plast" in horizontal or vertical direction. + + This method considers options like global or editing grid or whether the target point + will snap to another object. The behavior is given by the respective configuration. + + If "visualize" is true, the function will generate calls to \add_mouse_cursor or \add_edge_marker to provide a visualization of the edges or vertexes that the point is snapping to. \clear_mouse_cursors will be called before. + + This method has been added in version 0.30.4. + """ + ... + @overload + def snap2(self, p: db.DPoint, visualize: Optional[bool] = ...) -> db.DPoint: + r""" + @brief Snaps a point to the edit grid with advanced snapping (including object snapping) + + @param p The point to snap + @param visualize If true, a cursor shape is added to the scene indicating the snap details + + This method behaves like the other "snap2" variant, but does not allow to specify an + angle constraint. Only grid constraints and snapping to objects is supported. + + If "visualize" is true, the function will generate calls to \add_mouse_cursor or \add_edge_marker to provide a visualization of the edges or vertexes that the point is snapping to. \clear_mouse_cursors will be called before. + + This method has been added in version 0.30.4. + """ + ... + def tracking_position_test(self) -> db.DPoint: + r""" + @hide + """ + ... + def ungrab_mouse(self) -> None: + r""" + @brief Removes a mouse grab registered with \grab_mouse. + """ + ... + def view(self) -> LayoutViewBase: + r""" + @brief Gets the view object the plugin is associated with + This method returns the view object that the plugin is associated with. + + This convenience method has been added in version 0.30.4. + """ + ... + ... + +class PluginBase: + r""" + @brief The plugin base class + + This class is provided as an interface to the base class implementation for various functions. + You can use these methods in order to pass down events to the original implementation. + + This class has been introduced in version 0.30.4. + """ + @classmethod + def new(cls) -> PluginBase: + r""" + @brief Creates a new object of this class + """ + ... + def __init__(self) -> None: + r""" + @brief Creates a new object of this class + """ + ... + def _const_cast(self) -> PluginBase: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> PluginBase: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + def activated(self) -> None: + r""" + @brief Gets called when the plugin is activated (base class implementation) + """ + ... + def config_finalize(self) -> None: + r""" + @brief Sends the post-configuration request to the plugin (base class implementation) + """ + ... + def configure(self, name: str, value: str) -> bool: + r""" + @brief Sends configuration requests to the plugin (base class implementation) + """ + ... + def create(self) -> None: + r""" + @brief 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. + """ + ... + def deactivated(self) -> None: + r""" + @brief Gets called when the plugin is deactivated and another plugin is activated (base class implementation) + """ + ... + def destroy(self) -> None: + r""" + @brief 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. + """ + ... + def destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def drag_cancel(self) -> None: + r""" + @brief This method is called when some mouse dragging operation should be cancelled (base class implementation) + """ + ... + def enter_event(self, prio: bool) -> bool: + r""" + @brief Handles the enter event (base class implementation) + """ + ... + def has_tracking_position(self) -> bool: + r""" + @brief Gets a value indicating whether the plugin provides a tracking position (base class implementation) + """ + ... + def is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def key_event(self, key: int, buttons: int) -> bool: + r""" + @brief Handles the key pressed event (base class implementation) + """ + ... + def leave_event(self, prio: bool) -> bool: + r""" + @brief Handles the leave event (base class implementation) + """ + ... + def menu_activated(self, symbol: str) -> None: + r""" + @brief Gets called when a custom menu item is selected (base class implementation) + """ + ... + def mouse_button_pressed_event(self, p: db.DPoint, buttons: int, prio: bool) -> bool: + r""" + @brief Handles the mouse button pressed event (base class implementation) + """ + ... + def mouse_button_released_event(self, p: db.DPoint, buttons: int, prio: bool) -> bool: + r""" + @brief Handles the mouse button release event (base class implementation) + """ + ... + def mouse_click_event(self, p: db.DPoint, buttons: int, prio: bool) -> bool: + r""" + @brief Handles the mouse button click event after the button has been released (base class implementation) + """ + ... + def mouse_double_click_event(self, p: db.DPoint, buttons: int, prio: bool) -> bool: + r""" + @brief Handles the mouse button double-click event (base class implementation) + """ + ... + def mouse_moved_event(self, p: db.DPoint, buttons: int, prio: bool) -> bool: + r""" + @brief Handles the mouse move event (base class implementation) + """ + ... + def tracking_position(self) -> db.DPoint: + r""" + @brief Gets the tracking position (base class implementation) + """ + ... + def update(self) -> None: + r""" + @brief Gets called when the view has changed (base class implementation) + """ + ... + def wheel_event(self, delta: int, horizontal: bool, p: db.DPoint, buttons: int, prio: bool) -> bool: + r""" + @brief Handles the mouse wheel event (base class implementation) + """ + ... + ... + +class PluginFactory: + r""" + @brief The plugin framework's plugin factory object + + Plugins are components that extend KLayout's functionality in various aspects. Scripting support exists currently for providing mouse mode handlers and general on-demand functionality connected with a menu entry. + + Plugins are objects that implement the \Plugin interface. Each layout view is associated with one instance of such an object. The PluginFactory is a singleton which is responsible for creating \Plugin objects and providing certain configuration information such as where to put the menu items connected to this plugin and what configuration keys are used. + + An implementation of PluginFactory must at least provide an implementation of \create_plugin. This method must instantiate a new object of the specific plugin. + + After the factory has been created, it must be registered in the system using one of the \register methods. It is therefore recommended to put the call to \register at the end of the "initialize" method. For the registration to work properly, the menu items must be defined before \register is called. + + The following features can also be implemented: + + @ + + This is a simple example for a plugin in Ruby. It switches the mouse cursor to a 'cross' cursor when it is active: + + @code + class PluginTestFactory < RBA::PluginFactory + + # Constructor + def initialize + # registers the new plugin class at position 100000 (at the end), with name + # "my_plugin_test" and title "My plugin test" + register(100000, "my_plugin_test", "My plugin test") + end + + # Create a new plugin instance of the custom type + def create_plugin(manager, dispatcher, view) + return PluginTest.new + end + + end + + # The plugin class + class PluginTest < RBA::Plugin + def mouse_moved_event(p, buttons, prio) + if prio + # Set the cursor to cross if our plugin is active. + set_cursor(RBA::Cursor::Cross) + end + # Returning false indicates that we don't want to consume the event. + # This way for example the cursor position tracker still works. + false + end + def mouse_click_event(p, buttons, prio) + if prio + puts "mouse button clicked." + # This indicates we want to consume the event and others don't receive the mouse click + # with prio = false. + return true + end + # don't consume the event if we are not active. + false + end + end + + # Instantiate the new plugin factory. + PluginTestFactory.new + @/code + + This class has been introduced in version 0.22. + """ + @property + def has_tool_entry(self) -> None: + r""" + WARNING: This variable can only be set, not retrieved. + @brief Enables or disables the tool bar entry + Initially this property is set to true. This means that the plugin will have a visible entry in the toolbar. This property can be set to false to disable this feature. In that case, the title and icon given on registration will be ignored. + """ + ... + @classmethod + def new(cls) -> PluginFactory: + r""" + @brief Creates a new object of this class + """ + ... + def __copy__(self) -> PluginFactory: + r""" + @brief Creates a copy of self + """ + ... + def __deepcopy__(self) -> PluginFactory: + r""" + @brief Creates a copy of self + """ + ... + def __init__(self) -> None: + r""" + @brief Creates a new object of this class + """ + ... + def _const_cast(self) -> PluginFactory: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> PluginFactory: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + def add_config_menu_item(self, menu_name: str, insert_pos: str, title: str, cname: str, cvalue: str) -> None: + r""" + @brief Adds a configuration menu item + + Menu items created this way will send a configuration request with 'cname' as the configuration parameter name and 'cvalue' as the configuration parameter value. + If 'cvalue' is a string with a single question mark ("?"), the item is a check box that reflects the boolean value of the configuration item. + + This method has been introduced in version 0.27. + """ + ... + @overload + def add_menu_entry(self, menu_name: str, insert_pos: str) -> None: + r""" + @brief Specifies a separator + Call this method in the factory constructor to build the menu items that this plugin shall create. + This specific call inserts a separator at the given position (insert_pos). The position uses abstract menu item paths and "menu_name" names the component that will be created. See \AbstractMenu for a description of the path. + """ + ... + @overload + def add_menu_entry(self, symbol: str, menu_name: str, insert_pos: str, title: str) -> None: + r""" + @brief Specifies a menu item + Call this method in the factory constructor to build the menu items that this plugin shall create. + This specific call inserts a menu item at the specified position (insert_pos). The position uses abstract menu item paths and "menu_name" names the component that will be created. See \AbstractMenu for a description of the path. + When the menu item is selected "symbol" is the string that is sent to the \menu_activated callback (either the global one for the factory ot the one of the per-view plugin instance). + + @param symbol The string to send to the plugin if the menu is triggered + @param menu_name The name of entry to create at the given position + @param insert_pos The position where to create the entry + @param title The title string for the item. The title can contain a keyboard shortcut in round braces after the title text, i.e. "My Menu Item(F12)" + """ + ... + @overload + def add_menu_entry(self, symbol: str, menu_name: str, insert_pos: str, title: str, sub_menu: bool) -> None: + r""" + @brief Specifies a menu item or sub-menu + Similar to the previous form of "add_menu_entry", but this version allows also to create sub-menus by setting the last parameter to "true". + + With version 0.27 it's more convenient to use \add_submenu. + """ + ... + def add_menu_item_clone(self, symbol: str, menu_name: str, insert_pos: str, copy_from: str) -> None: + r""" + @brief Specifies a menu item as a clone of another one + Using this method, a menu item can be made a clone of another entry (given as path by 'copy_from'). + The new item will share the \Action object with the original one, so manipulating the action will change both the original entry and the new entry. + + This method has been introduced in version 0.27. + """ + ... + def add_option(self, name: str, default_value: str) -> None: + r""" + @brief Specifies configuration variables. + Call this method in the factory constructor to add configuration key/value pairs to the configuration repository. Without specifying configuration variables, the status of a plugin cannot be persisted. + + Once the configuration variables are known, they can be retrieved on demand using "get_config" from \MainWindow or listening to \configure callbacks (either in the factory or the plugin instance). Configuration variables can be set using "set_config" from \MainWindow. This scheme also works without registering the configuration options, but doing so has the advantage that it is guaranteed that a variable with this keys exists and has the given default value initially. + """ + ... + def add_submenu(self, menu_name: str, insert_pos: str, title: str) -> None: + r""" + @brief Specifies a menu item or sub-menu + + This method has been introduced in version 0.27. + """ + ... + def assign(self, other: PluginFactory) -> None: + r""" + @brief Assigns another object to self + """ + ... + def create(self) -> None: + r""" + @brief 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. + """ + ... + def destroy(self) -> None: + r""" + @brief 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. + """ + ... + def destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def dup(self) -> PluginFactory: + r""" + @brief Creates a copy of self + """ + ... + def is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + @overload + def register(self, position: int, name: str, title: str) -> None: + r""" + @brief Registers the plugin factory + @param position An integer that determines the order in which the plugins are created. The internal plugins use the values from 1000 to 50000. + @param name The plugin name. This is an arbitrary string which should be unique. Hence it is recommended to use a unique prefix, i.e. "myplugin::ThePluginClass". + @param title The title string which is supposed to appear in the tool bar and menu related to this plugin. + + Registration of the plugin factory makes the object known to the system. Registration requires that the menu items have been set already. Hence it is recommended to put the registration at the end of the initialization method of the factory class. + """ + ... + @overload + def register(self, position: int, name: str, title: str, icon: str) -> None: + r""" + @brief Registers the plugin factory + @param position An integer that determines the order in which the plugins are created. The internal plugins use the values from 1000 to 50000. + @param name The plugin name. This is an arbitrary string which should be unique. Hence it is recommended to use a unique prefix, i.e. "myplugin::ThePluginClass". + @param title The title string which is supposed to appear in the tool bar and menu related to this plugin. + @param icon The path to the icon that appears in the tool bar and menu related to this plugin. + + This version also allows registering an icon for the tool bar. + + Registration of the plugin factory makes the object known to the system. Registration requires that the menu items have been set already. Hence it is recommended to put the registration at the end of the initialization method of the factory class. + """ + ... + ... + +class TextInfo: + r""" + @brief A utility class for generating text bounding boxes including the glyph polygons + + The geometry database regards text objects as point-like, hence the natural bounding box of a text object is a single point. To obtain the visual bounding box, you can use the \TextInfo object. It is created from a layout view and allows computing bounding boxes from \Text, \DText or \Shape objects which include the visual representation of the text. + + That bounding box is given in the equivalent space of the original text object - i.e. when it is placed into the same cell and on the same layer than the original text. + + This computation is not trivial, because there are fonts that do not scale with zoom level. Hence, the equivalent bounding bounding box depends on the zoom factor and other transformations that control the rendering of the text. Also, a number of settings from the layout view - specifically default font or default text height influence the appearance of the characters and need to be considered. The TextInfo object takes care of these things. + + It does not take care however of transformations applied inside the hierarchy. Specifically, when a text object is not in the current top cell, different instantiation paths may exist that render different bounding boxes. Hence there not a single equivalent bounding box for a text object not inside the top cell. It is recommended to first transform the texts into the top cell before computing the bounding boxes. + + Here is some sample code that places boxes over each selected text object. These boxes are identical to the selection markers of the texts, but this identity quickly vanishes if you zoom in or out: + + @code + begin + + view = RBA::LayoutView.current + # Provide undo support, so it is more convenient to try out + view.transaction("Generate true label bounding boxes") + + textinfo = RBA::TextInfo::new(view) + + view.each_object_selected do |sel| + + # Ignore selected objects which are not texts + sel.shape.is_text? || next + + # Transform the text to top level + tl_text = sel.trans * sel.shape.text + + # Compute the bounding box + bbox = textinfo.bbox(tl_text, sel.cv_index, sel.layer) + + # Place boxes over the original texts + # Note that 'ctx_cell' is the true origin of the selection path, hence the one that 'sel.trans' applies to + view.cellview(sel.cv_index).ctx_cell.shapes(sel.layer).insert(bbox) + + end + + ensure + view.commit + + end + @/code + + This class has been introduced in version 0.30.5. + """ + border: float + r""" + Getter: + @brief Gets the border in pixels + See \border= for details about this attribute. + Setter: + @brief Sets the border in pixels + This attribute adds a border between the bounding box edges and the character polygons for better readability of the text when a box is drawn around them. The value is given in screen pixels. The default value is the one used for the markers in the application. + """ + @classmethod + def new(cls, view: LayoutViewBase) -> TextInfo: + r""" + @brief Creates a TextInfo object for a given layout view + """ + ... + def __copy__(self) -> TextInfo: + r""" + @brief Creates a copy of self + """ + ... + def __deepcopy__(self) -> TextInfo: + r""" + @brief Creates a copy of self + """ + ... + def __init__(self, view: LayoutViewBase) -> None: + r""" + @brief Creates a TextInfo object for a given layout view + """ + ... + def _const_cast(self) -> TextInfo: + r""" + @brief 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. + """ + ... + def _create(self) -> None: + r""" + @brief 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. + """ + ... + def _destroy(self) -> None: + r""" + @brief 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. + """ + ... + def _destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def _is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + def _manage(self) -> None: + r""" + @brief 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. + """ + ... + def _to_const_object(self) -> TextInfo: + r""" + @hide + """ + ... + def _unmanage(self) -> None: + r""" + @brief 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. + """ + ... + def assign(self, other: TextInfo) -> None: + r""" + @brief Assigns another object to self + """ + ... + @overload + def bbox(self, dtext: db.DText, cv_index: Optional[int] = ..., layer_index: Optional[int] = ...) -> db.DBox: + r""" + @brief Obtains the bounding box for the given micrometer-unit text object + + This method returns a \DBox object, representing the bounding box of the micrometer-unit \DText object. + The cellview and layer index is optional. Without a layer and cellview index, the bounding box computation will not take into account potential additional transformations implied by transformations present the layer view specification. + + The bounding box is given as an equivalent micrometer-unit \DBox object, when placed in the same cell and on the same layer as the original text object. + """ + ... + @overload + def bbox(self, shape: db.Shape) -> db.Box: + r""" + @brief Obtains the bounding box for the given text-type shape + + If the shape is not a text object or it is not part of a layout shown in the layout view, this method will return an empty box. Otherwise, it will return a \Box object, representing the bounding box of the text object, including the label's character representation. + + The bounding box is given as an equivalent integer-unit \Box object, when placed in the same cell and on the same layer as the original text object. + """ + ... + @overload + def bbox(self, text: db.Text, cv_index: int, layer_index: Optional[int] = ...) -> db.Box: + r""" + @brief Obtains the bounding box for the given text object + + This method returns a \Box object, representing the bounding box of the integer-unit \Text object. + The cellview index needs to be specified, while the layer index is optional. The layer index is the layer where the text object lives in the layout, given by the cellview index. Without a layer, the bounding box computation will not take into account potential additional transformations implied by transformations present the layer view specification. + + The bounding box is given as an equivalent integer-unit \Box object, when placed in the same cell and on the same layer as the original text object. + """ + ... + def create(self) -> None: + r""" + @brief 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. + """ + ... + def destroy(self) -> None: + r""" + @brief 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. + """ + ... + def destroyed(self) -> bool: + r""" + @brief 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. + """ + ... + def dup(self) -> TextInfo: + r""" + @brief Creates a copy of self + """ + ... + def is_const_object(self) -> bool: + r""" + @brief 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. + """ + ... + ... +