# Structure of CirclePack display commands

The ability to display circles and other geometric objects in canvases is central to the power of CirclePack. Display actions are carried out using the disp command (short for display). Here are two examples, the first illustrating an elementary call of the type available via right-mouse actions in canvases. The second illustrates more sophisticated actions which are available in command lines and scripts.

disp -w -c
disp -w -cf a(1 10) -df b -gt5c40

The commands disp and Disp apply to the active packing's canvas or to a specified canvas (using the -p{.} flag). (Note that using the capital D makes the command persistent, so it will be reapplied whenever that canvas is redrawn.)

In this document we describe the display command structures available to the user. There are three components: First is the command disp; then an optional -p{n} to indicate the packing to which the command applies; and finally a sequence of one or more "flag segments". The real action is in these flag segments.

## Flag Segment Structure

The more complicated display command shown above has four flag segments, as grouped here:

disp -w -cf a(1 10) -df b -gt5c40
We will describe each as illustrative of general construction principles. Each flag begins with a dash '-' followed by a letter indicating the action or the object type.

- -w : this wipes the canvas clean.
- -cf a(1 10): the c indicates the objects are circles and attribute f means circles filled with their recorded colors. The list of which circles to draw is given next: in this case a(1 10) indicates all circles with indices from 1 to 10, inclusive.
- -df b : The d indicates dual objects and in this case the df indicates dual faces. (If there were a further f, that would indicate to draw them as filled.) The b gives the list of dual face indices, namely "boundary" dual faces in this case.
- -gt5c40: The g tells CirclePack to draw its currently stored closed path. The t is a thickness attribute, setting to 5 in this case, and c is a color attribute, color code 40 (light blue) in this case.

The specifications of lists used here are examples of the huge range available, as described in the List Specs tab in the Help window. For details on the many objects which can be displayed and their structures, look for disp in the Command Details tab in the Help window.

## Attribute Encoding

The display attributes of an object follow the letter for the object with no intervening spaces. They are specified with letters, and perhaps digits. An f specifying a "filled" object must immediately follow the object letter, but other attribute can be included in any order. After this first string of letters in a flag segment, any remaining characters specify "data" for that flag segment, namely, the list of targets that call is applied to --- circles, faces, edges, etc. In many cases, the default (an empty data string) is taken to mean "all". Thus, disp -w -c will wipe the canvas and display all circles, while disp -w -c b will wipe the canvas but then display only the boundary circles. (See the List Specs tab in the Help window.)

We illustrate attributes with some typical examples:

- -cffg and -cfbg: circles filled with foreground fg or background bg color. Typically, these are dark grey and white, respectively.
- -ccbg: this displays circles with the background color; essentially this can make the circle disappear.
- -cfc5: filled circles with color 5 (dark blue)
- -cc5t8: circles with color 5 and thickness 8. Thickness can range from 0 (minimal) to 15.
- -t2ft3: "trinket" of type 2 (a triangle) positioned at the center of a circle, filled with the color of that circle. The t3 determines the thickness (actually size); this grows rapidly, in this case the base size times 8 (2 to the power 3).

## Some Final Notes

The drawing actions specified by the flag segments of a display command are carried out in order first to last, and that order can make a difference in outcome, as later drawing can obscure early drawing, depending on a canvas's 'transparency' settings.

- Recall that Disp creates a persistent display command; until superseded, redrawing of a canvas (as when it is moved by the mouse) will reuse the specification. Persistent display commands can also we recalled or specified in the canvas's Screen -> Display Options menu.
- The command disp (with no flags) will redraw the canvas using the current persistent display command, as will disp -wr after wiping the canvas first.
- Colors use codes 0 (background) to 255. Codes 1 to 200 are a spread from dark blue to dark red, with 100 being white. Those from 201 to 255 are a mixture of additional colors, with those from 232 to 248 being a nicely separated spread.
- Objects for packing p can be displayed on the screen of packing q. This is an example: disp -p1 -q2 -f.
- The post command for generating PostScript images of the canvases is parallel to the disp command in nearly all features.