1. Introduction
2. ConnectRule & ConnectType
3. ConnectRule Subclasses
4. Example ConnectRules File
5. Naming Conventions

Introduction

While specifying what connector can snap/attach to another connector, a lot of criteria might need to be evaluated in its current context. During each frame of movement in an Animation, each Connector within its vicinity is checked on its connection eligibility, therefore a lot of processing resources might be used.

ConnectRules are made in an attempt to circumvent such bulky computation. The ConnectRules are used as a fast means of filtering out alignments/connections that will NEVER be possible. This limits the more complex calculations to run on alignments/connections that might be possible.

ConnectRule & ConnectType

One ConnectRule is defined by one or more ConnectTypes. ConnectTypes are further separated by snapping ConnectTypes and attaching ConnectTypes. Below is a visual example of how this works using USB Micro-B 2.0 and USB Micro-B 3.0:

There are 4 Connectors in the example: Cable 2.0, Cable 3.0, Port 2.0, and Port 3.0. The snapping connectors are the cables, and the attaching connectors are the ports. Each Connector can have only one ConnectRule:

• Cable 2.0 ConnectRule:
  

  Snap ConnectType: CableToPort2CType

  Attach ConnectType: -

   

• Cable 3.0 ConnectRule:
  

  Snap ConnectType: CableToPort3CType

  Attach ConnectType: -

   

• Port 2.0 ConnectRule:
  

  Snap ConnectType: -

  Attach ConnectType:CableToPort2CType

   

• Port 3.0 ConnectRule:
  

  Snap ConnectType: -

  Attach ConnectType: CableToPort2CType, CableToPort3CType

   

Cable 2.0's Connector ConnectRule has a CableToPort2CType as it's snap ConnectType, therefore it can attach to whatever Connector that has a CableToPort2CType attach ConnectType. Which in this example Port 2.0 and Port 3.0 accept Cable 2.0.

Having nothing in its snap ConnectType means this Connector cannot snap to another Connector. Likewise, having nothing in its attach ConnectType means this Connector cannot be attached from other Connectors.

ConnectRule Subclasses

Knowing the various sub-classes of ConnectRule is typically unnecessary as the helper functions described later will automatically create ConnectRules of the appropriate class. However, it is important to distinguish between symmetric and asymmetric ConnectRules. Symmetric ConnectRules specify what ConnectTypes they permit in both the snapping and attaching context. Asymmetric ConnectRules may specify specific ConnectTypes they permit in each snapping or attaching context.

For example, magnets(disregarding their polarity) attaches and/or snaps to other magnets. Therefore it makes sense that this is placed as symmetric ConnectRule.

On the other hand, USB cables and ports have specific rules to differ what should snap and what should attach. As it wouldn't make sense to take the port(usually built in the computer) to connect to the cable.

The easiest way to create ConnectRules is by calling one of the makeConnectRule() functions. All variations take a str key as a first argument. Currently, this argument is not very important, so it is typically the same as the name of the global variable that will contain the resulting rule. Following the key, the arguments used to depend on the desired rule:

• Symmetric
  Pass a single ConnectType, where the snap ConnectType and attach ConnectType are the same single ConnectType.
• 1 to 1 Asymmetric
  Pass a single ConnectType for snapping and a single ConnectType for attaching. Either may be null to prevent alignment/connection in that context.
• Many-Many Asymmetric ConnectType
  Pass a set of ConnectTypes for snapping and a set of ConnectTypes for attaching. Either may be null to prevent alignment/connection in that context.
• Many-Many Asymmetric ConnectRule
  Pass a set of ConnectRules for snapping and a set of ConnectRules for attaching. Either may be null to prevent alignment/connection in that context.

The makeConnectRule() functions all return a ConnectRule. This ConnectRule should be stored in a global scope so it can be used by Connectors throughout the extension that defines them and any other dependent extensions. Setting aside a file specifically for ConnectRules is a common practice. Note that the actual initialization of the ConnectRules takes place inside of an init block. This is not necessary but is often practical. Putting the code in an init block ensures the rules will be available when referenced but saves start-up time.

Example ConnectRules File

public class MagnetToMagnetCType extends ConnectType { }
public class CableToPort2CType extends ConnectType { }
public class CableToPort3CType extends ConnectType { }

public ConnectRule magnetRule;
public ConnectRule usbCable2Rule;
public ConnectRule usbCable3Rule;
public ConnectRule usbPort2Rule;
public ConnectRule usbPort3Rule;
public ConnectRule magneticUsbCable3Rule;

init {
    // Example 1: Symmetric
    magnetRule = makeConnectRule("magnetRule", MagnetToMagnetCType);

    // Example 2: 1 to 1 Asymmetric
    usbCable2Rule = makeConnectRule("usbCable2Rule", CableToPort2CType, null);
    usbCable3Rule = makeConnectRule("usbCable3Rule", CableToPort3CType, null);
    usbPort2Rule = makeConnectRule("usbPort2Rule", null, CableToPort2CType);

    // Example 3: Many to Many Asymmetric ConnectType
    usbPort3Rule = makeConnectRule("usbPort3Rule", {ConnectTypeClass: },
                                   {ConnectTypeClass: CableToPort2CType, CableToPort3CType});

    // Example 4: Many to Many Assymmetric ConnectRule
    magneticUsbCable3Rule = makeConnectRule("magneticUsbCable3Rule", [magnetRule, usbCable3Rule], [magnetRule]);
}

Naming Conventions

The name of the ConnectRule itself can't give the full context to the nature of the connection, and thus the job falls to the naming of the ConnectType. In the example, notice the naming convention of the ConnectType. The naming should clearly show "what connects to what"CType.

This is for developers to easily troubleshoot connection issues. The "CType" at the end is to avoid possible class naming clashes and show clearly the class is a ConnectType.

Refer to cm/core/connectRule.cm for more details.