diff --git a/src/lay/doc/programming/application_api.xml b/src/lay/doc/programming/application_api.xml index 05a172c13..6d3dfab73 100644 --- a/src/lay/doc/programming/application_api.xml +++ b/src/lay/doc/programming/application_api.xml @@ -9,7 +9,7 @@

This section covers the basic application API. The application API consists of the main application class - and a couple of classes that represent the user interface. This sections presents a selection of classes + and several classes that represent the user interface. This sections presents a selection of classes that make up the application API. These classes provide the main entry points into the application API. Further classes are documented in RBA Class Index.

@@ -30,13 +30,13 @@ 
Application::instance
-

The application object is the main entry point into the API. It offers a couple of methods. In particular:

+

The application object is the main entry point into the API. It offers several methods and attributes. In particular:

The MainWindow class

@@ -103,7 +103,8 @@
  • : returns a LayoutView object (see below) which represents the current tab.
  • : returns the index of the current tab. Some methods like "select_view" operate with view indexes. The view index is the number of the tab (0 is the leftmost one). The "view" method - allows obtaining the LayoutView object from a view index.
    • + allows obtaining the LayoutView object from a view index. The same way + selects the view with the index given in this call.
  • : gets the global grid in micrometer units.
  • and : gets or sets the name of the technology to use to new layouts or for layouts loaded without an explicit technology specification.
    • @@ -120,13 +121,13 @@
  • and : save or restore a session. Sessions contain a window settings and informations about the layouts loaded. Sessions allows storing and restoring of the state of the main window.
    • -
  • : switch to the given tab.
    • -
  • : gets the LayoutView object for a given tab index.
    • +
  • : switches to the given tab. This equivalent to using .
    • +
  • : gets the object for a given tab index.
  • : gets the number of tabs.

    • - The MainWindow supplies two events. + The MainWindow supplies three events. See for details about events. These are the events:

    @@ -147,7 +148,7 @@

    - The MainWindow class features a couple of parameterless methods starting with "cm_...". These methods are identical with + In addition, the MainWindow class features many parameterless methods starting with "cm_...". These methods are identical with the methods called when the respective menu functions are triggered. They are of use when menu events need to be emulated in code, for example to implement special key bindings.

    @@ -157,14 +158,14 @@

    The LayoutView class is documented in detail in . It represents one layout tab in the - main window. A layout view can show multiple layouts. The specification about which layout and which cell of that - layout is shown is combined in the CellView objects (). Each LayoutView has a list - of CellView objects corresponding to the layouts shown in the same panel. + main window. A single layout view can show multiple layouts. The objects represent one + layout loaded into a view. They specific the layout loaded plus the cell selected for drawing. + Each LayoutView has a list of CellView objects corresponding to the layouts shown in the same panel.

    - A LayoutView object can be obtained from the main window either by obtaining the current view or by obtaining - the view object for a tab given by the tab index: + A LayoutView object can be obtained from the main window either by reading the current view or by getting + the view object for a tab by the tab index: 

    # Current view:
@@ -181,13 +182,13 @@ Application::instance.main_window.current_view_index
 Application::instance.main_window.views

    - The index is 0 for the first tab. Note that the value returned by current_view can be "nil" if no layout - is shown. + The index is 0 for the first tab. Note that the value returned by + or can be "nil" if no layout is shown.

    - A layout view is the container for a couple of resources. These resources are mainly display objects like - annotations, markers and images. In addition, the report database system in anchored in the LayoutView object. + A layout view is the container for a variety of "visual" objects. These resources are mainly display objects like + annotations, markers and images. In addition, the report database system is anchored in the LayoutView object. The following resources are managed in the layout view:

    @@ -205,17 +206,19 @@ Application::instance.main_window.views to a large degree, so different colors can be used for example. Markers are objects of class Marker (). -
  • Local configuration: be default, the layout view draws it's configuration from the global +
  • Local configuration: be default, the layout view pulls it's configuration from the global configuration database. It is possible however to override certain configuration parameters for a - particular view. This allows for example to set the background color for a particular view. + particular view. This allows for example to set the background color for a particular view without + affecting the other views.
  • Layer properties: the layer properties tree is also managed by the layout view. Since there can be multiple layer properties trees in different tabs in the layer properties panel, there are method to access either the current or a specific one of the layer properties trees.
    • -
  • Custom stipples: custom stipples can be defined in the layout view and used in the - layer properties. Custom stipples are bitmaps that define the fill pattern used for the inside - area of a polygon. +
  • Custom stipples and line pattern: custom stipplesu and line styles can be set in the + layout view and used in the layer properties. Custom stipples are bitmaps that define the fill + pattern used for the inside area of a polygon. Line styles are bit pattern that make lines being + resolved into dots.
  • Selection: the layout view also manages the selection. This is a set of objects and their instantiation path in the layout database. It represents the set of selected objects. Each @@ -225,8 +228,8 @@ Application::instance.main_window.views
  • Transient selection: this is the object that is highlighted briefly when the mouse hovers over it.
    • -
  • Cell views: the list of layouts and cells shown in the layout view as overlays. The - cell view list cannot be manipulated directly. Instead, it is expanded when a layout is loaded. +
  • Cell views: the list of layouts and cells shown in the layout view as overlays. Cell views + are created when layouts are loaded and deleted when layouts are closed. One of the cell views is the "active" one. That is the one which is selected in the drop-down box in the cell tree and for which the cell tree is shown.
  • Cell visibility: the information about what cell is visible and what cell is not. Each @@ -248,7 +251,8 @@ Application::instance.main_window.views

    - The layout view offers a couple of methods. Here's a brief explanation of some of these methods: + Being the central class, the layout view naturally offers many methods and attributes. + Here's a brief explanation of some of these methods:

      @@ -264,6 +268,12 @@ Application::instance.main_window.views
    • , and : manage custom stipples.
      • +
    • , and : + manage custom line styles. +
      • +
    • and : moves the context cell up or down in the + hierarchy. +
    • and : gets an start or end iterator object that allows traversing of the layer properties tree in a recursive or non-recursive fashion. @@ -275,6 +285,9 @@ Application::instance.main_window.views
    • : gets the display area in micron units (the viewport).
      • +
    • : + returns the view into idle state (nothing selected, no editing in progress, "Select" mode is active). +
    • : gets the CellView object for a given index.
      • @@ -287,7 +300,7 @@ Application::instance.main_window.views
    • , , and : manage images.
      • -
    • , and : +
    • , , and : allow manipulation of the configuration for that layout view only. For example it is possible to set a different background color for that specific layout view.
      • @@ -303,13 +316,13 @@ Application::instance.main_window.views starts or ends a transaction. All operations between the start and end of a transaction can be undone in one step. +
    • : + clears the selection of geometrical objects (shapes or cell instances). +
    • and : creates a new layout or loads a layout. In both cases, you can either replace the current layouts or add the new one to the layouts present.
      • -
    • , and : - manage report databases. -
    • : returns an iterator pointing to the current layer (the one that has the focus frame in the layer tree. @@ -329,48 +342,55 @@ Application::instance.main_window.views
    • : close a cell view, i.e. remove that specific layout from the list of loaded layouts.
      • +
    • : Enables or disables editing. This method will enable or disable all editing + features. This is intended for temporarily disallowing edits. This is not the same than edit and viewer mode. +
    • , and : - dump the screen content into a QImage with or without a specific resolution.
      • + dumps the screen content into a QImage with or without a specific resolution.
    • : provides an initialization of a "LayerProperties" object for a new layer according to the current settings of the view.
    • , , and : - manage cell visibility. + manages cell visibility.
      • -
    • and : - load or save layer properties files. +
    • and : + loads or saves layer properties files.
    • , and : - manage hierarchy levels shown. + manages hierarchy levels shown.
    • , , and : return or manipulate the selection of geometrical objects (shapes, instances). The key descriptor object for that purpose is , which refers to a geometrical object throug an instantiation path.
    • (and other pan... methods), (and other zoom... methods): - change the viewport. + changes the viewport.
    • : - reload a given layout. + reloads a given layout. +
      • +
    • , , + and : Create, delete and get report databases stored inside the LayoutView object.
    • : changes the name of a cellview.
    • , and : - set or reset the layout view's title. + sets or resets the layout view's title.
      • +
    • : Saves a layout to a file (with options).
    • : - show or hide an image. + shows or hides an image.
    • , and : - get the viewport parameters. + gets the viewport parameters.

    Implementing Undo/Redo

    Undo/Redo functionality is implemented by using "transactions". Transactions are - groups of operations which comprise one user operation. Transactions are built internally + groups of operations which implement one user operation. Transactions are built internally and automatically once a transaction is initiated. Most operations performed in the framework of the LayoutView and Layout objects are tracked within these transactions. When a transacting is finished, it needs to be committed. After that, a new operation will be available for @@ -403,18 +423,19 @@ end

    - Generating such instantiation path object is somewhat tedious, but usually the requirement is not - to generate such paths, but to take an existing selecting, manipulate it somehow and then reset it back. + Generating such instantiation path objects is somewhat tedious, but usually the requirement is not + to generate such paths, but to take an existing selecting, manipulate it somehow and then to set the selection + to the new one. This is fairly easy by taking a copy of the selection, manipulation of the shapes and setting the manipulated selection as the new one.

    The following is a sample which replaces all shapes by their hull polygons. Note that is provides - undo/redo support through "transaction": + undo/redo support through a "transaction":

    - 
      view = mw.current_view
+  
    view = mw.current_view
 
 begin
 
@@ -440,7 +461,7 @@ end
   
    Events
    
 
   
    
-  The LayoutView can supply several events.  
+  The LayoutView object supplies several events.  
   See  for details about events. 
   These are the events:
   
    
@@ -450,22 +471,57 @@ end
     This event is triggered when the active cellview changes. The active cellview is the one indicated
     by the drop-down-box atop of the cell list if multiple layouts are loaded into one view.
    • +
  • on_annotation_changed: + This event is triggered if an annotation is changed. The ID of the annotation is sent along + with the event. +
    • +
  • on_annotation_selection_changed: + This event is triggered if the selection of annotations is changed. +
    • +
  • on_annotations_changed: + This event is triggered if an annotation is added or deleted. +
  • on_cell_visibility_changed: This event is triggered when the visibility of a cell changes. The visibility of a cell is changed by using "Hide Cell" or "Show Cell" from the cell tree's context menu.
    • -
  • on_cellview_list_changed: +
  • on_cellviews_changed: This event is triggered when a new cellview is added or a cellview is removed.
  • on_cellview_changed: - This event is triggered when a cellview changed (i.e. the current cell has been changed. The integer - slot ("signal_int") is called with the index of the cellview that has changed. + This event is triggered when a cellview changed (i.e. the current cell has been changed. The index of + the changed cell view is sent along with the event. +
    • +
  • on_close: + This event is triggered when a cell view is closed.
  • on_file_open: This event is triggered when a file is loaded.
    • +
  • on_hide: + This event is triggered when a cell view is going to become invisible (i.e the tab changed). +
    • +
  • on_current_layer_list_changed: + This event is triggered when the current layer list was changed (i.e. the tab in the layer list + has been changed). +
    • +
  • on_image_changed: + This event is triggered when an image was edited. The ID of the image is sent along with the event. +
    • +
  • on_image_selection_changed: + This event is triggered when an image was selected or unselected. +
    • +
  • on_images_changed: + This event is triggered when an image was added or deleted. +
  • on_layer_list_changed: - This event is triggered when the layer properties list was changed. + This event is triggered if a layer was changed, added or deleted. +
    • +
  • on_layer_list_deleted: + This event is triggered if a layer list was deleted (i.e. a tab was removed). +
    • +
  • on_layer_list_inserted: + This event is triggered if a layer list was inserted (i.e. a tab was added).
  • on_rdb_list_changed: This event is triggered when a report database is opened or removed. @@ -473,6 +529,9 @@ end
  • on_selection_changed: This event is triggered when the selection has changed.
    • +
  • on_show: + This event is triggered when a cell view is going to become visible (i.e the tab changed). +
  • on_transient_selection_changed: This event is triggered when the transient selection has changed.
    • @@ -498,13 +557,15 @@ end
  • Obtain the selected entries from the layer properties tree: and
  • Initialize layer properties with the default settings:
  • Expand layer properties which contain wildcard entries ("stylesheet" layer properties files):
    • +
  • Manipulate layer properties by setting the properties of the object returned by + or .

    • - Many of these functions use LayerPropertiesIterator objects () + Many of these functions use objects to identify entries in the layer tree. Such an object is basically a pointer into the tree. The term "iterator" - refers to the fact, that such a pointer can be moved to neighboring entries in the layer tree. + refers means that such a pointer can be moved to neighboring entries in the layer tree. By default, the LayerPropertiesIterator performs a preorder, depth-first traversal of the layer properties tree (the virtual root object is omitted). This is how to work with LayerPropertiesIterator objects: @@ -570,7 +631,7 @@ props = lp.current

    - The actual properties of the layer are accessible through methods of the LayerProperties object. + The actual properties of the layer are accessible through methods of the object. Since the parent node may override or contribute properties, a LayerProperties object has a twofold identity: the way it appears finally ("real") and the way it is configured ("local"). The property accessors have a "real" parameter and deliver the real value if this parameter is set to true and @@ -626,8 +687,8 @@ layout_view.insert_layer(lp, props)

    - The LayerProperties object () represents one entry in the layer properties tree - and has a couple of basic properties. For each of these properties, + The object represents one entry in the layer properties tree + and has several basic properties. For each of these properties, a getter for the real and local value exists as well as a setter that installs a local value. For example, for the width property, the following methods are defined:

    @@ -659,6 +720,7 @@ layout_view.insert_layer(lp, props)
    • (strong): specifies animation (blinking, scrolling)
    • (strong): specifies the fill pattern
      • +
    • (strong): specifies the line style
    • (additive): specifies the fill color's brightness
    • (strong): specifies the fill color
    • (additive): specifies the frame color's brightness
      • @@ -666,6 +728,7 @@ layout_view.insert_layer(lp, props)
    • (weak): the lower hierarchy level shown. This property has various flavors related to the definition of "lower level".
    • (weak): the upper hierarchy level shown. This property has various flavors related to the definition of "upper level".
    • (strong): specifies whether the layout is rendered with small crosses at each vertex
      • +
    • (strong): Specifies whether a cross is drawn in rectangles
    • (strong): specifies whether the layer is semi-transparent (color bitmap combination)
    • (strong): specifies whether the layer is visible
    • (strong): specifies whether the layer is valid
      • @@ -721,6 +784,7 @@ lv.cellview(0) # first one
      • : a reference to the cell shown (a Cell object: ).
        • +
      • : a reference to the cell shown (by cell index).
      • : the unique name of the layout.
      • : sets the unspecific path (see below)
      • : sets the specific path (see below)
        • @@ -729,10 +793,10 @@ lv.cellview(0) # first one
      • : closes this cell view (removes it from the layout view)
      -

      Unspecific and specific path, context cell

      +

      Unspecific and specific path and context cell

      - In addition to the cell the cell view specifies how the cell is embedded in the hierarchy. + In addition to the cell itself, the cell view specifies how the cell is embedded in the hierarchy. Embedding can happen in two ways: an unspecific and a specific way. Both ways contribute to a path which leads from a top cell to the cell drawn.

      @@ -747,7 +811,7 @@ lv.cellview(0) # first one

      The unspecific path ends at the "context cell" which usually is identical to the cell addressed by the cell view. - However, KLayout allows addressing of a specific instance of a direct or indirect child cell as the actual cell. In that + KLayout allows addressing of a specific instance of a direct or indirect child cell as the actual cell. In that case, the specific path comes into play. Bascially that means, that a cell is drawn within a context of embedding layout. The specific path leads from the context cell to the cell view's target cell and consists of specific instances (hence the name "specific path"). The "descend" and "ascend" feature @@ -817,12 +881,12 @@ lv.insert_image(image)

      - Annotations () are basically rulers but can be used for other purposes as well, i.e. - to simply add a text object. + Annotations () are basically rulers and other "overlay objects" but can be used for other purposes as well, + for example to simply add a text object. Annotations, like images, are objects stored in the LayoutView and can be selected, deleted, transformed etc.

      -

      Programmatically, annotations are created that way:

      +

      Programmatically, annotations are created this way:

      lv = RBA::Application::instance.main_window.current_view
 ant = RBA::Annotation::new
@@ -830,15 +894,16 @@ ant.p1 = RBA::DPoint.new(0.0, 0.0)
 ant.p2 = RBA::DPoint.new(100.0, 0.0)
 lv.insert_annotation(ant)
      -

      The annotation carries a couple of properties, which copy the properties that can be set using the - ruler properties dialog for example. The most important properties are the two positions (start and end - position) accessible through the and properties, the style ( property) +

      The annotation carries several attributes. Those are the same attributes that can be configured in the + annotation properties dialog. + The most important properties are the two positions (start and end + position) accessible through the and properties, + the style ( property) and the outline ( property).

      -

      Annotations cannot be manipulated directly. But annotations can be replaced by new annotations. For replacement, - the annotation ID is the key. The following - example demonstrates how rulers are manipulated. In this example, the style of all rulers +

      If properties are changed using the attribute setters, their appearance will change as well. + The following example demonstrates how rulers are manipulated. In this example, the style of all rulers is set to "arrow on both sides". Note, how in this example transactions are used to implement undo/redo:

      @@ -850,9 +915,7 @@ begin view.transaction("Restyle annotations") view.each_annotation do |a| - adup = a.dup adup.style = RBA::Annotation::StyleArrowBoth - view.replace_annotation(a.id, adup) end ensure diff --git a/src/lay/doc/programming/python.xml b/src/lay/doc/programming/python.xml index 981b4c69f..ad2094e66 100644 --- a/src/lay/doc/programming/python.xml +++ b/src/lay/doc/programming/python.xml @@ -195,6 +195,8 @@ box.right = box.right + 100 Protected methods are not supported - methods are public always. +
    • "nil" value: The Python equivalent to Ruby's "nil" is "None".
      • +
    • Iterators: Iterator binding: