Angle fields

An angle field stores a number as its value, and a string as its text. Its value is a number between 0 and 360 (this range can be changed), while its text could be any string entered into its editor.

Angle field

Angle field with editor

Collapsed angle field

Creation

JSON

{
  "type": "example_angle",
  "message0": "angle: %1",
  "args0": [
    {
      "type": "field_angle",
      "name": "FIELDNAME",
      "angle": 90
    }
  ]
}

JavaScript

Blockly.Blocks['example_angle'] = {
  init: function() {
    this.appendDummyInput()
        .appendField('angle:')
        .appendField(new Blockly.FieldAngle(90), 'FIELDNAME');
  }
};

The angle constructor takes in an optional value and an optional validator. Zero is used as the default value if no value is given or the given value does not cast to a number.

Serialization and XML

The XML for an angle field looks like so:

<field name="FIELDNAME">0</field>

Where the name attribute contains a string referencing an angle field, and the inner text is the value to apply to the field. The inner text value follows the same rules as the constructor value.

Customization

Snapping

The Blockly.FieldAngle.ROUND property changes what values the angle picker "snaps" to when using a mouse.

Here is an example with a ROUND value of 70:

Angle field with a ROUND value of 70

The ROUND property defaults to 15. Set it to 0 if you want to disable snapping.

This is a global property, so it will modify all angle fields when set.

Directionality

The Blockly.FieldAngle.CLOCKWISE property changes which direction makes the angle value increase. Setting this value to true makes the angle increase as the selector is moved clockwise, setting it to false makes the angle increase as it is moved counter-clockwise.

CLOCKWISE set to true

Angle field with CLOCKWISE set to true

CLOCKWISE set to false

Angle field with CLOCKWISE set to false

The CLOCKWISEproperty defaults to false, meaning counter-clockwise motion will make the angle increase.

This is a global property, so it will modify all angle fields when set.

Zero position

TheBlockly.FieldAngle.OFFSET property sets where 0 degrees is located. By default zero degrees is aligned with the positive x-axis (towards the right) and then this property "offsets" that position by a number of degrees.

Angle picker zero at right

Angle picker zero at top

The OFFSET property defaults to 0, meaning zero degrees is aligned with the positive x-axis.

This is a global property so it will modify all angle fields when set.

Range

The Blockly.FieldAngle.WRAP property sets the range of values. The range of values is equal to (-360 + WRAP, WRAP). This means that a WRAP value of 360 will give a range of (0, 359.9) and a WRAP value of 180 will give a range of (-179.9, 180).

Angle picker with wrap value of 180

The WRAP property defaults to 360, meaning the range of the field is (0, 359.9).

This is a global property so it will modify all angle fields when set.

Angle picker size

The Blockly.FieldAngle.HALF property changes the size of the angle picker. This value defines the radius of the outer circle in pixels.

Angle picker with default editor size

Angle picker with large editor

The HALFproperty defaults to 50.

This is a global property so it will modify all angle fields when set.

Common modes

The direction and zero position can be used together to create some fun combinations. Here are two common ones:

Protractor

0 degrees is right, 90 degrees is up.

Blockly.FieldAngle.CLOCKWISE = false;
Blockly.FieldAngle.OFFSET = 0;

Angle picker configured as a protractor

Compass

0 degrees is up, 90 degrees is right.

Blockly.FieldAngle.CLOCKWISE = true;
Blockly.FieldAngle.OFFSET = 90;

Angle picker configured as a compass

Creating an angle validator

An angle field's value is a number, so any validators must accept a number and return a number, null, or undefined.

Here is an example of a validator that forces the value to be a multiple of 30:

function(newValue) {
    return Math.round(newValue / 30) * 30;
}

Angle picker with a validator

Note how the angle field's [ROUND](#snapping) property is still set to 15, so the graphical elements of the field display multiples of 15, rather than 30.