Skip to content

Dev Tools

Jump to bottom
Shane Brinkman-Davis edited this page Feb 2, 2016 · 3 revisions

NOTE: 2016-02-02 I think most of these still work in some way, but many have changed in their details.

Neptune Namespaces

All Art.* libraries are bound to the global Neptune namespace:

Neptune.Art.Foundation
Neptune.Art.Atomic
Neptune.Art.Canvas
Neptune.Art.Engine
Neptune.Art.React
Neptune.Art.Flux

If your project also uses Neptune-Namespaces, it, too, will be bound to Neptune:

Neptune.KimiLife
Neptune.Qtp

Art Namespace Global Binding

2016: Not currently supported in the new NPM packages.

Invoking Art.bindGlobally() will bind some core methods and classes globally:

From Art.Foundation:
  inspect
  eq
  log

From Art.Atomic:
  color
  rect
  matrix
  point

  Color
  Rectangle
  Point
  Matrix

Art.DevTools.DomConsole

The "DomConsole" is an alternative console to the browser's built-in console. It is display-only. You should still enter javascript commands in the browser console. However, when enabled, the Art.Foundation "log" function will log to both the DomConsole and the browser's console. The DomConsole has the following benefits:

  1. it displays images
  2. it displays the color of Art.Atomic.Color objects and standard HTML color strings
  3. it has a friendlier collapsable hierarchy for complex objects.
  4. it has limited syntax highlighting
  5. many Art classes know how to be inspected for "pretty" display

NOTE: It's useful to bind the "log" function globally: Art.bindGlobally()

Enable the DomConsole:
DomConsole = require 'art-foundation/dev_tools/dom_console'
DomConsole.enable()
API
# enable or disable the dom console
DomConsole.enable()
DomConsole.disable()

# once enabled, you can show or hide it
DomConsole.show()
DomConsole.hide()

# clear the dom-console's contents
DomConsole.reset()

Art Engine

Inspecting the ArtEngine Interface Model (AIM)

First, bind Art globally.

Then access:

> Art.activeCanvasElements
 => [CanvasElement]

This returns an array of all active CanvasElements. Typically there is one per HTML Canvas tag you are using with the ArtEngine. For many apps there will only be one, so typically this is what you'll use:

> Art.activeCanvasElements[0]
 => CanvasElement

element.find

The CanvasElement is always the root of the AIM tree. From there you can use Element methods to explore the tree. The most useful one is the @find method:

> Art.activeCanvasElements[0].find("Element")
 => [...] // all Elements in the tree

@find searches the entire tree and does a simple string or regex match on the element's "@pathStringWithNames". pathStringWithNames for an element contains the element's full classname and its @name/key property prepended with its parent's pathStringWithNames. This allows you to find elements based on their location in the AIM.

Example:

> Art.activeCanvasElements[0].find(/button.*Text/)[1].pathStringWithNames
 => "Art.Engine.Core.CanvasElement/Art.Engine.Core.Element/Art.Engine.Core.Element:button/Art.Engine.Elements.TextElement"
// An example finding the first element with the name 'caption'
> Art.activeCanvasElements[0].find("caption")[0].inspectedName
 => "Art.Engine.Core.Element:129:caption"
find pattern, findAll: true

By default find won't return children of found objects. Set the findAll:true option to true to return all objects that match the pattern regardless of structure.

find (element) -> true/false

Instead of a string or regex pattern, you can pass a function to find. This function is run on every Element. If it returns a value Javascript considers true, then that Element will be in the result set.

// function(element) # => anything, interpreted as true/false via "!!result"
// Example returning all elements with a color property:
> Art.activeCanvasElements[0].find(function(e){return e.color;}, {findAll: true})
 => [...] // all Elements in tree with a color property
find pattern, verbose: true

find has a verbose option which outputs info on found Elements:

> Art.activeCanvasElements[0].find(/button.*Text/, {verbose: true})
// Example verbose output:
//   found: "Art.Engine.Elements.TextElement"
//   pattern: /button.*Text/
//   matched: "Art.Engine.Core.CanvasElement/Art.Engine.Core.Element/Art.Engine.Core.Element:button/Art.Engine.Elements.TextElement"
//
//   found: "Art.Engine.Elements.TextElement"
//   pattern: /button.*Text/
//   matched: "Art.Engine.Core.CanvasElement/Art.Engine.Core.Element/Art.Engine.Core.Element:button/Art.Engine.Elements.TextElement"
 => [...] // all Elements in the tree

Directly Manipulating Element Properties

For the example property "compositeMode":

# get the property
element.compositeMode
element.getCompositeMode()

# set the property
element.compositeMode = "normal"
element.setCompositeMode("normal")
# Note: Setting a property triggers an update Epoch
# In the console the epoch will fire and resolve immediately.

# Epoch stuff
# If you read back what you set immediately you won't see the change.
# Normally, as an App author you shouldn't care, but you can get details if you want:
element.pendingCompositeMode # get the new compositeMode that will be set
element.getPendingCompositeMode()
element.compositeModeChanged # t/f - is that property changing in the next epoch?
element.getCompositeModeChanged()

Why support both "getCompositeMode()" and "compositeMode"? The former is far faster on some browsers, the latter is nicer in code.

Inspecting an Element

Some useful methods for inspecting an element.

element.props         # all props and their current values
element.concreteProps # props which are actually stored in the object
element.virtualProps  # props which are computed from concreteProps
element.path          # array of element's parents all the way up to CanvasElement

Rendering an Element

Sometimes it's handy to render an element and see what it looks like in isolation.

# enable the DomConsole so you can see logged bitmaps
Art.DevTools.DomConsole.enable()

# render the element to a bitmap and log it
# logBitmap accepts all toBitmap options.
# Ex: render/log element's "drawArea":
element.logBitmap()

# Ex: render/log element's "logical area"
element.logBitmap({area: "logicalArea"})

# Ex: render/log element as-drawn in it's parent's "logical area"
element.logBitmap({area: "parentLogicalArea"})

Render & Log Element and Each Child

# accepts all toBitmap arguments
# render element in its own logicalArea, but render all children in
# their parent's (the elements) logicalArea.
element.logInspectRender({size: 100})

# render all element and children each in their own spaces:
# render all element and children each in their own logicalAreas:
element.logInspectRender({size: 100, area: "logicalArea})

NOTE: All toBitmap options apply to both the element and its children EXCEPT area. That parameter only applies to the children. The element's area is always "logicalArea" (its own logical-area).

Example:

# load: http://localhost:9000/neptune/demos/art_react/quixx/?dev=true
# in the console:
Art.activeCanvasElements[0].find("qwixx")[0].logInspectRender({size:100})

element.toBitmap

###
Creates and returns an bitmap with the current element drawn on it
options: [defaults]
  backgroundColor: [transparent]  #
  area: ["drawArea"]
    "logicalArea"         means => drawArea: @logicalArea,                  elementToDrawAreaMatrix: identityMatrix
    "paddedArea"          means => drawArea: @paddedArea,                   elementToDrawAreaMatrix: identityMatrix
    "drawArea"            means => drawArea: @elementSpaceDrawArea,         elementToDrawAreaMatrix: identityMatrix
    "parentLogicalArea"   means => drawArea: @parent.logicalArea,           elementToDrawAreaMatrix: @elementToParentMatrix
    "parentPaddedArea"    means => drawArea: @parent.paddedArea,            elementToDrawAreaMatrix: @elementToParentMatrix
    "parentDrawArea"      means => drawArea: @parent.elementSpaceDrawArea,  elementToDrawAreaMatrix: @elementToParentMatrix
    "targetDrawArea"    to be used with custom elementToDrawAreaMatrix - sets drawArea to include @elementSpaceDrawArea in the specificed target-space
  size: [drawArea.size]     # Bitmap size. Will be multiplied by pixelsPerPoint for the final size.
  mode: ["fit"], "zoom"     # determines how the requested drawArea is scaled to fit the bitmap size
  pixelsPerPoint: [1]       # Ex: set to "2" for "retina" images [default = 1]
  elementToDrawAreaMatrix:  # the draw matrix [see area's defaults]
  drawArea: [see area]      # the area to capture in drawArea-space (overrides area's drawArea)
  bitmapFactory: [null]     # overrides default bitmapFactory
callback: (bitmap, elementToBitmapSpaceMatrix) -> # => null
###
toBitmap: (options={}, callback) -> # => null

Usually you will only need the area and possibly size options. Examples:

# Render a bitmap with max dimensions of 100 (aspect ratio maintained)
# Only include the element's logicalArea.
element.toBitmap area: "logicalArea", size: 100, (bitmap) -> ...

# Render element to a bitmap the size of parent's logicalArea.
# Render element in is proper place within the parent's logicalArea.
element.toBitmap area: "parentLogicalArea", (bitmap) -> ...

See: Element Geometry#logicalarea-vs-paddingarea-vs-drawarea

Inspect Structure

A handy way to inspect the structure of an Element and its children recursively.

# enable the DomConsole and bind "log" globally
# not strictly required, but a much better experience
Art.DevTools.DomConsole.enable()
Art.bindGlobally()

# inspectChildrenStructure returns a simplified description of an element and all its children.
# log + DomConsole gives a nice way to browse it
log(element.inspectChildrenStructure())

# inspectParentStructure returns a simplified description of an element and all its parents.
log(element.inspectParentStructure())

NOTE: If you set the "name" property on your elements, it will show up in both inspect_____Structures. Useful for finding the element you are interested in.

Clone this wiki locally