Skip to content

Original Design Document

Jump to bottom
mchaptel edited this page Oct 1, 2019 · 2 revisions

openHarmony Library Design document

This library works as a DOM (Document Object Model) to provide access to all the current elements of a scene but without reliance on string attributes and ids. It will be open source under MIT license (?) and provide streamlined access to the elements of a Toonboom Harmony scene. This initiative is independent from Toonboom and supported by its community only. The goal of this library is to make the API to access a Toonboom scripting interface easier to learn, access, and manipulate. It must provide powerful functions but also be as clear to read as possible, and consistent to use, to encourage adoption.

The library will be available at the github: https://github.com/cfourney/OpenHarmony/

Naming convention:

  • Every class starts with “o” then Capital letter to avoid duplicate class names with the official API that should remain accessible at all times.
  • When in doubt, american spelling will be used as per general programming convention (ex: color).
  • camelCase should be used for function names and variable names start with a lowercase as is common practice in JavaScript. When possible names should not be abbreviated.

Stylistic guide

  • We will avoid as much as possible functions called by calling the general class and passing a string parameter and instead create instances of these classes through the new keyword, as well as arrays of objects to simplify iterations.
  • Dot notation access should be used as much as possible
  • Focus will be put on simplicity of use and explicit names
  • Case convention must be followed always
  • Getter and setter functions will be used to wrap the official API and do the house keeping from within the object.
  • Arrays should start at 0 except for frames which should follow the ui numbers
  • Most parameters should be optional and have fallback default values

Structure of the Classes:

  • oApplication Object
  • oScene Object
  • oNode Object
    • oAttribute
      • oFrame
    • oColumn Objects
      • oFrame
  • oPalette Objects
    • oColor
  • oTimeline object
  • oFile Object
    • oXML parsing class
  • oMath Object
    • oMatrix
    • oPoint
    • oVector
    • oBox
  • oLibrary Object
    • oTemplate
  • oDialog Object
    • oConfirm dialog
    • oLoadUi (parse UI file properly, allow for window flags etc)
  • oPreferences Object

oScene Class:

Base class, contains elements of the opened scene.

Properties:

  • Integer duration
  • oVector size
  • Double framerate
  • String path
  • String version (name of xstage file)

Members:

  • Array nodes (array of the oNode Objects contained within the scene)
  • Array columns (array of the oColumn Objects in the scene)
  • Array palettes (array of oPalette Objects present in the scene and elements)
  • oTimeline timeline (singleton oTimeline object)

oNode Class:

Base class, represents a node in the node view or a layer in the timeline.

Properties shared by all nodes:

  • oPoint nodePosition (the position in the node view)
  • String name (string that appears as the name in the node view), must be a getter setter and not initialized with constructor
  • String path (address of the group in which the node appears)
  • oNode group (reference to the parent group oNode object)
  • oColor color (color object, defines the custom color of the node)
  • Array inNodes (array of references to connected oNode objects, by port index)
  • Array outNodes (double dimension array of references to connected oNodes objects, by port/link index)

interfaces :

These interfaces provide common functions between all node types. For example, a Drawing Node will implement drawingNode and pegNode interfaces. drawingNode will therefore inherit from pegNode which inherits from oNode.

oDrawingNode class: Type of oNode Object, that contains image information.

Properties:

  • Array elements (contains the paths of the actual drawing files)
  • Array frames (contains oFrame objects)
  • String folder
  • Double opacity

oPegNode class:

Type of oNode Object that contains transform information.

Properties:

  • oPoint pivot
  • oPoint position
  • oVector scale
  • oVector skew
  • oDouble rotation
  • oMatrix matrix

oEffectNode class:

Different properties based on effect types (too many for this document, should be dynamically generated from listAttr)

Each of these node properties are wrappers for oAttribute objects in the class and should be possible to get and set for any frame (optional parameter) by just passing an object of corresponding type (not necessarily an attribute object). The setter must recognise whether the attribute is linked to a column and set the Entry if the column exists or set a local value if it doesn’t. In the case of a frame being specified, a column will be created automatically in the event that no column is already linked.

For all other less common attributes, nodes should have an attributes property that is a hashmap of objects named after the textAttr they are a wrapper for. The hashmap can be accessed non linearly and iterated over, as well as return a list of its members.

oAttribute class :

Properties:

  • String name (string used to access the textAttr)
  • String type : data type (integer, string, double, object etc)
  • oColumn column : contains info for the linked column
  • Array frames : an array of oFrame objects ordered by frame number for index.

oFrame class:

Properties:

  • Boolean isKeyFrame
  • Object value : value of the attribute for each frame
  • Integer number : number of the frame
  • oPoint leftBezier / rightBezier : easy access to the func bezier easing points.
  • String marking : K,B, etc

oPalette class

Properties:

  • String name
  • String type (scene vs elements)
  • String id
  • String path
  • Array colors (contains oColor objects)
Clone this wiki locally