5.5. slots — Slot classes

5.5.1. Dependent class

class cgkit.slots.Dependent

Dependent.onValueChanged()

Normal/array

Dependent.onResize(newsize)

This method is called by a controlling array slot whenever the size of the slot has changed.

Dependent.queryResizeVeto(size)

Check if a dependent vetoes a resize operation. This method is called by an array slot on all its dependents whenever the slot size should be changed to size. If the method returns True the resize operation is rejected. The default implementation returns False. Only slots with size constraints should return True.

5.5.2. Slot classes

There are the following standard slots:

• DoubleSlot
• IntSlot
• BoolSlot
• StrSlot
• PySlot
• Vec3Slot
• Vec4Slot
• Mat3Slot
• Mat4Slot
• QuatSlot

class cgkit.slots.Slot([value, flags])

Create a slot that initially carries the specified value.

Todo: Describe the flags argument.

Slot.isSlotCompatible(slot)

Return True if slot is compatible with this slot. Two slots are compatible if they hold the same type of value. Only compatible slots can be connected to each other. But note that even when this method returns true, it can happen that the slots can not be connected. This is the case whenever the target just doesn’t accept input connections (for example, because it’s computing its output value procedurally).

Slot.typeName()

Return a string containing the name of the stored type. This name can be used to display the type of the slot to the user. The name should be chosen so that if two slots cannot be connected to each other then they should also return different names (however, if two slots have different names it is still possible that they can be connected to each other).

Slot.getController()

Return the associated controlling slot or None.

Slot.setController(slot)

Set or remove a controller for this slot. The current controller is replaced with slot which may also be None to remove the current controller only. If the controller is not compatible with this slot an EIncompatibleSlotTypes exception is thrown.

Slot.getValue()

Return the current slot value.

Slot.setValue(val)

Set a new value. If the slot has a controller the new value is propagated up to the controller. It is then up to the controller how this new value influences the actual output value. So it is not guaranteed that the output of the slot is really the new value. When the value really changes this method triggers the onValueChanged() method on all dependent objects.

Slot.connect(slot)

Connect the output of this slot with the input of slot. Calling this method is equivalent to calling slot.setController(self). The method has no effect if slot is None.

Slot.disconnect(slot)

Breaks an existing connection between this slot and slot. Calling this method is equivalent to calling slot.setController(None). The method checks if the connection actually exists before breaking it. If it does not exist, a ValueError exception is raised. The method has no effect if slot is None.

Slot.addDependent(d)

Establish a dependency between this slot and another object d. The argument d is added to the list of dependent objects. This means that d somehow depends on the value of this slot and that d has to be notified whenever the value of this slot changes. The actual notification is done by calling notifyDependents() which in turn calls onValueChanged() on all dependent objects.

Todo: C++ warning!

Slot.removeDependent(d)

Remove the dependency between this slot and another object d.

Slot.notifyDependents()

Notify all dependent slots about a value change. This method calls the onValueChanged() method of all slots whose value depends on the value of this slot.

Slot.computeValue()

This method is used to compute a new value whenever getValue() is called and the cache is invalid. It should only be implemented on procedural slots.

5.5.3. ArraySlot classes

class cgkit.slots.ArraySlot(multiplicity=1, constraint=None)

Create an array slot.

multiplicity is the “array length” of one individual item.

constraint is a SizeConstraint object that constrains the size of the array slot (see section SizeConstraint objects).

ArraySlot.size()

Return the number of elements in this array slot.

ArraySlot.isResizable(size, ignorelocalconstraint=False)

Check if this slot can currently be resized to a particular size. This method can be used to check if calling resize() with size as argument would succeed or not.

The method returns False if either the slot itself is size constrained or it is connected to a size constrained slot. In the latter case, the function will return True again if the connection is removed. The method will also return True if size matches the constraint size.

If ignorelocalconstraint is True the method will compute its result as if there would no constraint be present in this slot (so only dependent objects could reject the resize operation).

ArraySlot.resize(size)

Resize the array slot so that it can carry size elements. The values in the array are not modified by this operation.

ArraySlot.multiplicity()

Return the multiplicity of the array slot.

ArraySlot.copyValues(begin, end, target, index)

Copies the slice [begin : end] into position index of the slot target. If you want to copy one single value you have to pass [n, n+1]. It is also possible to pass negative values. For the copy operation to succeed, target has to be of the same type than this slot.

If any index is out of range, an exception is thrown.

Note: If this method is used to copy values within the same slot then the target range shouldn’t currently overlap with the source slice.

ArraySlot.isSlotCompatible(slot)

Return True if slot is compatible with this slot. Two slots are compatible if they hold the same type of value. Only compatible slots can be connected to each other. But note that even when this method returns true, it can happen that the slots can not be connected. This is the case whenever the target just doesn’t accept input connections (for example, because it’s computing its output value procedurally).

ArraySlot.typeName()

Return a string containing the name of the stored type. This name can be used to display the type of the slot to the user. The name should be chosen so that if two slots cannot be connected to each other then they should also return different names (however, if two slots have different names it is still possible that they can be connected to each other).

ArraySlot.getController()

Return the associated controlling slot or None.

ArraySlot.setController(slot)

Set or remove a controller for this slot. The current controller is replaced with slot which may also be None to remove the current controller only. If the controller is not compatible with this slot an EIncompatibleSlotTypes exception is thrown.

ArraySlot.getValue(index)

Return one item of the array slot. If the multiplicity of the slot is 1 then return value is just an individual value, otherwise it’s a tuple containing the values.

ArraySlot.setValue(index, value)

Set one item to a new value. If the multiplicity of the slot is 1 value has to be one single value, otherwise it must be a sequence containing multiplicity elements.

ArraySlot.connect(slot)

Connect the output of this slot with the input of slot. Calling this method is equivalent to calling slot.setController(self).

ArraySlot.addDependent(d)

Establish a dependency between this slot and another object d. The argument d is added to the list of dependent objects. This means that d somehow depends on the value of this slot and that d has to be notified whenever the value of this slot changes. The actual notification is done by calling notifyDependents() which in turn calls onValueChanged() on all dependent objects.

Todo: C++ warning!

ArraySlot.removeDependent(d)

Remove the dependency between this slot and another object d.

5.5.4. SizeConstraint objects

SizeConstraint objects can be passed into the constructor of an array slot to constrain its size. There are two variants, the LinearSizeConstraint and the UserSizeConstraint. The former constrains an array slot to a size that linearly depends on the size of another array slot, whereas the latter receives its size from the user.

class cgkit.slots.LinearSizeConstraint(ctrlslot, a=1, b=0)

This class depends its size linearly on the size of another slot.

ctrlslot is an array slot whose size determines the size of the constraint.

a and b are two coefficients that are used to calculate the constraint size which is where s is the size of ctrlslot.

LinearSizeConstraint.getCoeffs()

Returns a tuple (a, b) with the current coefficients.

LinearSizeConstraint.setCoeffs(a, b)

Set new coefficients for the constraint. The operation might raise an exception if the new coefficients are not compatible with another constraint. In this case, the old coefficients remain active.

class cgkit.slots.UserSizeConstraint(size=0)

This class stores a size that can be manually set by the user.

size is the initial size of the constraint.

UserSizeConstraint.setSize(size)

Set a new constraint size. All slots that are constrained by this object will be resized. Note that the operation might fail and an exception is thrown when the resize operation is not allowed (usually because there are other slots involved that are also size constrained).

5.5.5. Procedural slots

There are the following standard procedural slots:

• ProceduralDoubleSlot
• ProceduralIntSlot
• ProceduralVec3Slot
• ProceduralVec4Slot
• ProceduralMat3Slot
• ProceduralMat4Slot
• ProceduralQuatSlot

5.5.6. NotificationForwarder class

A NotificationForwarder object can be used to forward slot events from one particular slot to an arbitrary method instead of the onValueChanged() or onResize() method. To accomplish this the NotificationForwarder object is added as a dependent object of the slot. This means, whenever the value of the slot changes, the onValueChanged() method of the NotificationForwarder object is called which in turn calls an arbitrary other function or method.

class cgkit.slots.NotificationForwarder(onvalchanged, onresize=None)

onvalchanged is an arbitrary callable object that is invoked whenever a value changed event has occured. If the forwarder is used with a normal slot, the callable does not take any arguments. If it is used with an array slot, it takes two arguments start and end that specify what range has been modified.

onresize is a callable that gets called whenever the size of an array slot has changed. It takes one argument which is the new size of the slot.

Example:

>>> from cgkit import *
>>> def myCallback(): print "Something has happened"
...
>>> s=Sphere()
>>> n=NotificationForwarder(myCallback)
>>> s.radius_slot.addDependent(n)
Something has happened
>>> s.radius=5
Something has happened
>>> s.radius=2
Something has happened