The Element API

The Firebox Elements application programming interface (API) focus on simplicity and minimal expression. Specifically this means that when you want to move an element you call the #move method etc.. Every programming language has an API that simplifies how to accomplish an objective.

In this chapter we will look closer at the Element API and get to know how to navigate around the display. We will work more with creating scripts and how to run them.

The Display

Programming is a series of instructions that tell the computer what and when to to do some task. In Firebox when you work with elements you write code that instantly gives a visual reference to the code. This visual representation of the code occupy a two-dimensional coordinate plane. This means that an element has a position point with an x and y number.

The x coordinate represents the horizontal placement and the y represents the vertical placement. The display is 960 points wide and 640 points high and the center of the display is at point 480, 320.

To move the element anywhere in the display you specify its position x and y coordinates within the size of the display. Setting values beyond the display size will move it out of view. The position point holds the information about where the element is located. If you want to manipulate the direction the element is facing you adjust its angle which is defined in degrees. Elements can rotate 360 degrees where 0 degrees is the direction to the right, 90 degrees is the direction down, 180 degrees is the direction to the left and finally 270 degrees is the direction up.

Code

The code you write determines what happens inside the display. Behind the scene there could be multiple things happening when calling simple element methods. Knowing what to write is the hard part about programming. Examples, API documentation and knowledge built will be key to creating your own apps.

There are many different element methods that you need to learn in order to write your own code. Lets look at some of the movement methods.

To display an element of a specific type you call the display.* library.

display.emoji("🤩")

To move the emoji element you need to either change the x or y coordinate of the element. Making a handle to the element.

starman = display.emoji("🤩")

Now its possible to call methods on the starman element handle.

starman = display.emoji("🤩")

starman.goTo(100, 100)

starman.angle = 25

The starman handle is called a variable. A variable can hold different data types. And our starman variable holds an element of the type emoji.

There are many methods to call on the starman variable.

Movement

Now that we have looked at the basics of running code lets take a closer look at the ways we move elements around the display. There are multiple methods dealing with movement and motion which will give a different effect when moving elements around the display.

The #move(steps) method moves the element the number of steps specified as the argument. The number of steps is equal to the number of points across the display you want to move the element. If the number is positive the element will move in the direction the element is pointing to. If the number is negative the element will move away from the direction it is pointing to. For example the following code will move the element 10 points in the direction it is pointing.

elem = display.emoji("🤩")

elem.move(10)

To change to orientation in which the element is pointing there are several methods which can be used. The #turnRight(degrees) method turns the element clockwise amount of degrees depending on the value given. Likewise the #turnLeft(degrees) method rotates the element counterclockwise the amount of degrees given.

elem = display.emoji("🤩")

// rotate clockwise 10 degrees
elem.turnRight(10)

// rotate counterclockwise 10 degrees
elem.turnLeft(10)

As an alternative the #rotate(degrees) can also be used to achieve the same result.

elem = display.emoji("🤩")

// rotate clockwise 10 degrees
elem.rotate(10)

// rotate counterclockwise 10 degrees
elem.rotate(-10)

The #pointInDirection(degree) method can be used to set the direction for an element. Setting the elem.pointInDirection(90) rotates the element 90 degrees.

The #pointTo(other) method points the element to another element given as the method argument. The other object can be any other element that has a position coordinate point. This can for example be another element or the mouse input.

Example of an element pointing to the mouse input.

elem = display.emoji("🤩")

update(() => {
  elem.pointTo(input)
})

The #moveTo(point) sends the element sliding across the display to the point position given as an argument.

elem = display.emoji("🤩")

elem.moveTo(100, 100)

The #goTo(point) moves the element immediately from one position point to another without delay. It is also possible to call #goTo(input) which moves the element towards the mouse input. The goTo will work with both x, y coordinates and position point the input or another element in the display.

Use goTo to move to coordinates

elem = display.emoji("🤩")

elem.goTo(100, 100)

Use goTo to move to mouse input

elem = display.emoji("🤩")

update(() => {
  elem.goTo(input)
})

The #changeX(value) method changes and updates the x coordinate of the element. There are also multiple ways of achieving updating the x coordinate of the element.

The ways of modifying an elements x coordinate position by 10 points

elem = display.emoji("🤩")
elem.changeX(10)

// modify the x coordinate
elem.x += 10

// this is equivalent
elem.x = elem.x + 10

// modify the x coordinate position
elem.position.x += 10

There are multiple ways of achieving the same result in programming and you can choose what you think is the most suitable to use in the code you write.

The #changeY(value) method does the same to the y coordinate of an element as the changeX method does to the x coordinate for an element.

Ways of modifying the y coordinate include

elem = display.emoji("🤩")
elem.changeX(10)

// modify the y coordinate
elem.y += 10

// this is equivalent
elem.y = elem.y + 10

// modify the y coordinate position
elem.position.y += 10

The #setX(value) method sets the x coordinate to the value given which moves the element to that x position. There are also multiple ways to set the x coordinate to a value.

Set the x coordinate to a specified value

elem = display.emoji("🤩")

elem.setX(100)

// An equivalent way to set the x coordinate
elem.x = 100

Likewise the #setY(value) method sets the y coordinate of an element to a specified value. The element is moved to the specified y position.

Set the y coordinate to a specified value

elem = display.emoji("🤩")

elem.setY(100)

// An equivalent way to set the y coordinate
elem.y = 100

If an element reaches the edge of the screen and you want it to bounce back in the opposite direction the #ifOnEdgeBounce() method can be used. When an element reaches the edge of the display it will change orientation and move in the opposite direction of what it was moving.

Example of ifOnEdgeBounce() usage

elem = display.emoji("🤩")

update(() => {
  elem.move(2)
  elem.ifOnEdgeBounce()
})

The position coordinates and direction the element is heading can be printed for debugging.

xl = ui.label("x", 100, 50)
yl = ui.label("y", 100, 110)
al = ui.label("a", 100, 170)

elem = display.emoji("🤩")
elem.angle = random.num(0, 360)

update(() => {
  xl.value = elem.x.round()
  yl.value = elem.y.round()
  al.value = elem.angle.round()

  elem.move(5)
  elem.ifOnEdgeBounce()
})

Summary

In this chapter we looked at the Element API and how its focused on simplicity.

We looked at the Firebox display and how the elements are represented inside it in a coordinate system and that changing the elements position moves it around the display.

We looked at coding and how we can manipulate the elements in the display by changing its properties through the use of variables.

Then we looked at element methods to move and rotate the elements. We also looked at how we can get elements to point to other elements.

We also looked at the different ways of achieving the same result when manipulating the elements coordinates.

There were some examples of how to use the update loop method and at last we looked at the usage of ifOnEdgeBounce().

In the next chapter we will look at many different examples of how to handle user input and control elements in the display.