1. Style JSON Objects

Many image commands accept one or more style JSON objects. They all follow the same basic ideas:

Below are the most common patterns.

  1. Style JSON Objects
    1. Color Style
    2. Line / Stroke Style
    3. Fill + Line Combined Style
    4. Font Style
    5. TextBox / Paragraph Style
    6. ImageRect Style
    7. Background Style (NewImage)

1.1. Color Style ↑

A basic color style is used for fills, lines and fonts:

JSON style = JSON ( "color", "red", "alpha", 0.5 );

Supported keys:

Examples:

JSON redFill  = JSON ( "color" , "red" );             // solid red
JSON softGrey = JSON ( "color" , "808080" ; "alpha" ; 0.3 );
JSON named    = JSON ( "color" , "orange" );          // mapped to hex internally

1.2. Line / Stroke Style ↑

Used for outlines (borders, lines, polygon edges, etc.).

JSON stroke = JSON ( "color", "black", "width", 2.0, "alpha", 0.8 );
ImageSetLineStyle ( img, stroke );

Supported keys:

Usage examples:

// Global line style for following commands:
ImageSetLineStyle ( img, JSON ( "color", "red", "width", 3 ) );

// Per-shape style:
ImageRect ( img, 100, 100, 200, 80,
            JSON ( "color", "blue", "width", 1 ) );

1.3. Fill + Line Combined Style ↑

Some shape helpers (like pie segments, polygons, stars) use a combined style:

ImagePieSegment ( img,
    400, 400, 100, 0, -90, 120,
    JSON (
        "fill", JSON ( "color", "red",  "alpha", 0.8 ),
        "line", JSON ( "color", "grey", "width", 1.0 )
    )
);

Convention:

This allows you to set fill and border independently.

1.4. Font Style ↑

Font styles are used by ImageSetFont, ImageDrawText, ImageDrawTextBox, and ImageCornerBanner.

JSON fontStyle =
    JSON ( "name", "Chalkboard",
           "size", 24,
           "color", "blue",
           "alpha", 1.0 );

ImageSetFont ( img, fontStyle );

Supported keys:

Note: Font style set by ImageSetFont are used globaly in all font drawing commands until next ImageSetFont. The individual drawing commands can override this by having the font-style set in the styleOptions parameter for that command. It does not affect the font style for the next drawing command. Such styleOptions given in the font-drawing commands can override one or more properties of the currently selected font, to example size, style, color or name of font.

Examples:

ImageSetFont ( img, JSON ( "name", "Helvetica", "size", 18, "color", "black" ) );
ImageDrawText ( img, 100, 200, "Hello ACF!", JSON ( "color", "red" ) );

1.5. TextBox / Paragraph Style ↑

ImageDrawTextBox and ImageCornerBanner can use extra layout-related keys in their style:

Common keys:

Example for a centered corner banner:

JSON bannerStyle =
    JSON ( "size", 24,
           "color", "red",
           "valign", "middle" );

ImageCornerBanner ( img,
    50, 55, "tr",
    "SPECIAL\nOFFER",
    bannerStyle );

Example for a centered textbox:

JSON boxStyle =
    JSON ( "color", "black",
           "align", "center",
           "valign", "middle" );

ImageDrawTextBox ( img,
    100, 300, 300, 100,
    "Centered text\nin a box",
    boxStyle );

1.6. ImageRect Style ↑

Those use the same style as described in "Fill + Line Combined Style" above. In addition, you can specify rounded corners in this way: 

ImageRect ( img,
    400, 400, 100, 200,
    JSON (
        "fill", JSON ( "color", "red",  "alpha", 0.8 ),
        "line", JSON ( "color", "grey", "width", 1.0 ),
        "corners", "rounded"  // default radius of 8.
    )
);

The "corners" tag is optional, and it can have those alternative versions: (Note: Setting a radius to Zero makes no rounding). 

"corners", 16   // all four corners, radius 16
// or for individual radii (Top Left, Top Right, Bottom Left, Bottom Right). 
"corners", JSON ( "tl", 20, "tr", 16, "bl", 8, "br", 4)
// or for one corner have a different rounding than the rest. 
"corners", JSON ( "radius", 20, "tl", 16)
// or only the top left rounded
"corners", JSON ("tl",20)

The Corners key can also be used on text-boxes having borders.

1.7. Background Style (NewImage) ↑

The optional third parameter to NewImage is also a style JSON. It controls the initial background fill or background image:

// Solid white background
JSON img = NewImage ( 800, 600,
                      JSON ( "color", "white", "alpha", 1.0 ) );
                      
// Background from container variable :bilde
JSON img2 = NewImage ( 800, 600,
                       JSON ( "image", ":bilde", "alpha", 0.25 ) );

Supported keys: