Q & A

Q: What are the available AIM elements?

A: Short answer below. For more, see ArtEngine-Elements.

Element
CanvasElement
Rectangle
CustomShapeElement
TextElement
Fill
Outline
Bitmap
Blur
Shadow
PagingScrollElement
TextInput

Q: How does element flow work in AIM? How do the layout arguments to AIM elements work?

A: Element Geometry and Element Layout should answer those.

Q: How do you overlay AIM elements?

A: This is partially answered by geometry and layout above, but you may want to know how ArtEngine handles "z-index". The answer is an Element's children are drawn in the order they are listed. The last element is drawn on top of all the rest.

Q: What events can an AIM element respond to, and what are their hooks?

A1: This list may be incomplete, but it's close to complete:

# PointerEvents
# NOTE: pointer* events happen with touches or mice when buttons are down.
#       mouse* events only happen on PCs with the mouse moves with no button down.
# NOTE: On mobile, each touch gets its own set of pointer* events. Each touch has
#       its own unique ID so you can track it. See the demos/paint.
pointerCancel
pointerDown
pointerUp
pointerMove
pointerClick
mouseOut
mouseIn
mouseMove

# focus/blur
focus
blur

# supported, but haven't been tested in a LONG while... may need updating
dragOver
dragEnter
dragLeave
drop

# KeyEvents
keyPress
keyUp
keyDown

A2: To listen to events:

Element
  on:
    pointerClick: (event) ->
    keyPress: (event) ->
    drop: (event) ->
    etc...
# NOTE:
# Event handlers have one input, the Events.Event object. PointerEvent and KeyEvent
# objects inherit and extends the base Art.Events.Event object.

Q: How do you style AIM elements?

A1: 'Styles' are just sets of property values.

A2: If you mean "where are all the background, border, etc..." settings, there are none. In ArtEngine the idea is you generate such styling out of simpler elements. In general its much more flexible.

The only ways to draw pixels to the screen are: Shape Elements, Shape-Draw-Children Elements, the Bitmap element and Filter elements.

Here's how you'd do the same kinds of effects in the ArtEngine:

# a border
Element {},
  # ... other children elements below the outline
  Rectangle # a rectangular shape
    layout: ss:1 # cover all of the parent area
    Outline # draw the outline of the rectangle shape
      lineWidth: 4
      color: "red"
  # ... other children elements above the outline

# a solid color background
Element {},
  Rectangle
    layout: ss:1 # cover all of the parent area
    color: "red"
  # ... other children elements

Q: Is there a prescribed method for centralizing styles?

A: Not yet. There is a pattern I'm using in the oz/app that seems promising:

# 'styles' defined in: oz/style/style_props.coffee
  class StyleProps
    @poster:
      fontSize: 10
      fontFamily: "'Open Sans'"
      color: Colors.darkTextPrimary # from oz/style/colors

# 'styles' used in: oz/app/pages/post.coffee
  TextElement merge StyleProps.poster,
    # overrides:
    axis:1, text: user.name, layout: ls:1, l:-10

Q: How do you nest both AIM and React components?

First a clarification:

# This pattern:
{Element, Rectangle, TextElement, Gradient, Outline} = ReactArtEngine.Aim

# This is the same pattern used in Facebook's React:
{div, h1, h2, span, form, input} = React.DOM

# In both cases, in "common speech", AIM and DOM refer to the
# TRUE object trees used to render the page and respond to events.
# However, in both cases, above, what's actually happening is
# "Element", "Rectangle" as well as "div" and "h1" are all actually
# functions for generating Virtual-AIM and Virtual-DOM nodes.

A1: Components can nest inside (virtual)AIM nodes as follows:

Foo = createComponent
  render: ->
    Rectangle color: "red"

Bar = createComponent
  render: ->
    Element {},
      Rectangle color: "blue"
      Foo()

A2: It is legal, but not recommended to pass "children" to a component. In almost all cases the best practice is for each component to be responsible for the creation of all VirtualElements returned by its render function.

Passing VirtualElement children is usually only useful for wrapper components such as the "shell" of a page which provides scrolling and other common functions but needs to be "customized" to have unique contents. Here's how you do it:

Foo = createComponent
  render: ->
    Element {},
      Rectangle color: "red"
      # special implicit property "children" contains an array of VirtualElements passed in
      @props.children

Bar = createComponent
  render: ->
    Element {},
      Rectangle color: "blue"
      Foo {},
        # one or more VirtualElements can be passed into another Component as @props.children
        Rectangle color: "green"

Q: How do you pass properties to nested React components?

A: Properties work the same for (virtual) AIM nodes as they do for Components. In both cases you are invoking a function with the signature: (props, children...) -> VirtualNode. Ex:

Bar = createClass
  render: ->
    TextElement
      text: @props.label

Foo = createClass
  render: ->
    Element {},
      Bar label: "hello world"

Q: What are the supported properties for the various Element types?

A: TODO!