Previous: Text, Up: Core object functions

2.2.11 Components

Component objects represent instances of symbols. They contain other objects copied from the original symbol when it is instantiated into a schematic.

A component's basename is a string used to identify which symbol it originated from. When instantiating a symbol on initial placement in a schematic, or when recreating a component while loading a schematic, the basename is used to find the underlying symbol file in the component library.

See Component objects.

Note: In the gEDA C source code, these are normally called “complex” objects. However, as Guile Scheme supports complex numbers, and the procedures related to working with complex numbers use the word ‘complex’ to describe them, this API uses ‘component’ to avoid ambiguity.

The position, angle and mirror flag of a component indicates the transformation that was applied to the contents of the original symbol. The transformation is applied in the following order:

  1. If mirror is true, the symbol is reflected in the line x = 0.
  2. The symbol is rotated anti-clockwise by angle degrees about the point (0,0) (angle may only be an integer multiple of 90 degrees).
  3. Finally, the symbol is translated by position.

The component's contents (as returned by component-contents) have the transformation already applied to them. Updating the translation information using e.g. set-component! will not alter them – that must be done separately (e.g. by reloading the symbol).

— Function: component? object

Returns ‘#t’ if and only if object is a component object.

— Function: make-component basename position angle mirror locked

Creates and returns a new, empty component object with the given basename. position, angle and mirror specify the symbol transformation. If locked is true, the component will be protected against accidental selection by the user (this is used in gschem e.g. for titleblocks).

No attempt is made to load a symbol matching basename from component libraries, and the returned component is flagged as embedded.

— Function: make-component/library basename position angle mirror locked

Searches the component libraries for a symbol matching basename, and if found, instantiates the symbol and returns the resulting component (which is not flagged as embedded). Arguments are as for make-component.

If no match for basename is found, ‘#f’ is returned.

— Function: set-component! component position angle mirror locked

Sets the parameters of component. Arguments are the same as to make-component. Returns component.

Note: Remember that modifying the transformation parameters of a component does not update the component's contents.

— Function: component-info component

Returns the parameters of component as a list of the form: 

          (basename (x . y) angle mirror locked)
— Function: component-basename component

Returns the basename of component.

— Function: component-position component

Returns the position to which the original symbol was translated when creating component.

— Function: component-angle component

Returns the angle by which the original symbol was rotated when creating component, as an integer number of degrees.

— Function: component-mirror? component

Returns true if the original symbol was mirrored when creating component.

— Function: component-locked? component

Returns true if component is non-selectable.

— Function: component-contents component

Returns the contents of components as a list of objects.

— Function: component-append! component objects...

Appends objects (which must not be component objects) to the contents of component. Any objects which are already included in component are ignored. If any objects are already part of a page or of another component object, an ‘object-state’ error is raised. Returns component.

— Function: component-remove! component objects...

Removes objects from the contents of component. Any objects which are not part of a component or of a page are ignored. Returns component.

An ‘object-state’ error will be raised if any objects satisfy any of the following conditions: