1. Introduction
2. Animation Properties
   • Implementation
   • Unique Features
3. Space Vessel Properties
   • Implementation
   • Unique Features
4. Quick Properties
   • Implementation
   • Unique Features
5. Shared Features
   • PropInputSetting
   • propChanged Method
   • Refreshing the Properties Dialog
   • Property Visibility

Introduction

End users will need to have some way to easily and intuitively manipulate each object in some way, and the main way we achieve this is by implementing what we call "Core Properties". It is a green dialog that appears in the top left of the view the user is currently in. This is introduced in the G2 era of CET.

There are only 3 sub-types of Core Properties as of writing this, and these are Animation Properties, Space Vessel Properties, and Quick Properties. ONLY ONE Property dialog is shown at all times, and it's shown from the highest priority to the lowest according to the previous sentence's order.

Animation Properties

As described by the name itself, these are properties created from within by any implementation of the Animation class. It is mainly used for the user to be able to manipulate a Snapper with one hand changing properties in the Properties dialog and another hand moving the Snapper around during an insert, drag, rotate, or drag animation.

An example use case is changing the rules of how a Snapper connects to other Snappers during insertion or dragging.

Implementation

Two different ways:

• Putting the #insert, #drag, #rotate, and/or #drag attribute to the PropInputSetting of the PropDef appended to the Snapper with G2 enabled:

  /**
   * Using G2.
   */
  public bool usingG2() { return true; }
  
  
  /**
   * Append PropDefs
   */
  public props {
      bool "animProp" : setting=PropInputSetting(attributes={#insert, #drag, #rotate, #stretch});
  }

  
  
  
• In the Animation class, the methods you can control are buildProperties(), createAnimationProperties(), and destroyAnimationProperties().
  When an Animation is entering a View, buildProperties() is called.
  (In coreProperties, buildProperties() will call createAnimationProperties())
  A common way of customizing this is to place this code into buildProperties:

  coreProperties.buildProperties(owner, finalize=true);

  This would create the properties of the PropObj you passed as the ownerargument. Meaning you can create your custom Animation with custom properties based on any PropObj you want.

Unique Features

In the Snapper class, there are methods that are called when the Animation Properties are changed. It also separates whether the change comes from the end-user, or from an internal code.

• animationPropertyChanged
• animationUserPropertyChanged

Use these if there are changes ONLY in the animation properties, and not in changes triggered from Schemes of from Quick Properties.

Space Vessel Properties

These are properties generated by a Vessel that belongs in a Space(hence a Space Vessel). These are mainly used if you want to generate properties that have nothing to do with Animations, Snappers, or Components, which is rarely a case, but good to know you have the option to generate properties from Space Vessels.

Implementation

Any PropDefs appended to a Space Vessel will have its Properties Dialog built by calling Vessel's showSpaceVesselProperties() . Vessels are G2 by default, therefore there will be no need to override usingG2(). You can refer and run the example in cm/core/test/testPropsConstraints.cm.

Do remember to destroy the Vessel or call hideSpaceVesselProperties() when you want the Property dialog to close as it is not automatically destroyed like Animation Properties and Quick Properties.

Unique Features

As this belongs only to the Vessel class, there are these two methods in the class which is called to modify the Vessel whenever changes to the properties are made:

• propertyChanged
• userPropertyChanged

Quick Properties

These are properties that are created by selecting a Snapper or Component. Usually used for end-users to individually manipulate properties of a selected Snapper or Component.

Implementation

/**
 * Using G2.
 */
public bool usingG2() { return true; }


/**
 * Append PropDefs
 */
public props {
    bool "quickProp" : setting=PropInputSetting(attributes={#quick});
}

Similar to how Animation Properties does it, but instead, the #quick attribute into the construction of the PropInputSetting instead. This applies to both Snappers and Components(are G2 by default).

Both Snappers and Components are PropObjs, therefore they share the same way of appending PropDefs. Refer to the Append PropDefs article.

Unique Features

Quick Properties also have a method in the Snapper class which is called if the Properties are changed.

• quickPropertyChanged

Shared Features

PropInputSetting

A PropInputSetting holds the instructions for creating a property (the look and behavior of the property). It is best understood that a PropInputSetting is required for a PropDef to be a property -- even if it does not contain anything.

In the PropInputSetting class, you can see there are a lot of fields that you can use to determine things like visibility, label, lockability, etc. Checking the subclasses of PropInputSetting also gives you the choices of how the property will be constructed, as in whether is this a checkbox property? buttons? a list of options? a range of distances? etc.

propChanged Method

In the PropObj class, there exists a method called propChanged(). This method is called whenever the PropDef value is changed. In other words, if there is a property that has changed and there is something you want to modify in your PropObj(Animation, Vessel, Snapper, Component), you can place the code into propChanged().

Refreshing the Properties Dialog

There are times you might want to "refresh" the Properties Dialog when there are changes made in the Properties Dialog. i.e. Changing the visibility/domain of a property.

The diffRebuildCoreProperties() function will do exactly that and it's found in cm/core/buildCoreProperties.cm.

You must first specify at what condition should it rebuild inside the rebuildFlag argument of the said function.

Property Visibility

If you have thought of setting the visibility true to false and vice versa through manipulateInputSettings() after you call diffRebuildCoreProperties(), you might realize it does not make the property go from invisible to being visible again. That is one of the limits of the visibility field in PropInputSetting, the field is intended more for the visibility on its initial construction of the Properties Dialog.

If you want to achieve that, you can instead override visibleInFactory() and return true or false on whether you want it to be visible in whatever conditions you deem suitable.

Or you could use the hideCoreProperty() and showCoreProperty() function in cm/core/corePropertiesManagerFunctions.cm.