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.

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:

If mirror is true, the symbol is reflected in the line x = 0.

The symbol is rotated anti-clockwise by angle degrees about the
point (0,0) (angle may only be an integer multiple of 90
degrees).

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-componentbasename 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/librarybasename 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-infocomponent

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

(basename (x . y) angle mirror locked)

Function: component-basenamecomponent

Returns the basename of component.

Function: component-positioncomponent

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

Function: component-anglecomponent

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-contentscomponent

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: