6) Focus Effects

Now that we’ve seen various introductory examples, we should take the next step and discuss the so-called focus effects.

Simply put, focus effects are what you use to guide your readers’ attention to certain aspects of your stickies.

Technically speaking, focus effects are specified together with a trigger: you attach the effect to a trigger.

The code below shows an abstract example of a narrative in which there is a trigger with no focus effect, followed by another trigger that comes with a focus effect.

Abstract Example
Trigger without focus effect @cr-sticky

Trigger with some focus effect [@cr-sticky]{effect="..."}

The reason why an effect is attached to a trigger is because a trigger is what Closeread uses to decide what to do with a sticky.

Syntax to Specify Focus Effects

The syntax to specify a focus effect is the following:

  • You wrap the trigger @cr-sticky with brackets: [@cr-sticky]

  • You append an attribute effect using braces [@cr-sticky]{effect="..."}

  • Inside the braces, you specify the name of the effect, followed by the equals sign =, followed by the value of the effect surrounded in quotes "..."

Available Effects in Closeread

As of this writing, Closeread comes with a handful of focus effects. In no particular order of importance we have:

  • Scaling: the scale-by effect is used to shrink or enlarge the size of a sticky (e.g. text, equations, images, code).

  • Panning: the pan-to effect is used to move a sticky up-down, and left-right, or if you prefer north-south, east-west (e.g. text, equations, images, code).

  • Zooming: the zoom-to effect is used to zoom-in (or out) into a code block or line of text or math equation.

  • Highlighting: the highlight effect is used to highlight certain parts of text or code of a sticky, while de-emphasizing the other parts of the sticky.

  • *Scale to fill: this is an additional effect that you attach to a sticky instead of a trigger to stretch the sticky in a way that it fills the viewport.

Let’s describe the syntax behind each of these effects.


Scaling

To shrink or enlarge a sticky element you use the scale-by effect, e.g.  [@cr-sticky]{scale-by="2"}

This attribute takes non-negative values. The figure below depicts the resulting effect of scale-by when used on text and images:

Figure 6.1

The scaling effect works on text (including math equations, and code) and images. Keep in mind that you include this focus effect by attaching it to a trigger, for example:

Scaling Effect
Normal scale @cr-sticky

Shrinking effect [@cr-sticky]{scale-by="0.5"}

Enlarging effect [@cr-sticky]{scale-by="2"}

Normal size again @cr-sticky


Panning

To move a sticky element you use the pan-to effect, e.g.  [@cr-sticky]{pan-to="10%,0%"}

This attribute takes a pair of x and y values that control the horizontal and vertical panning, respectively. The figure below depicts the resulting effect of pan-to—using different units—when applied on an image (but you can also apply it on text):

Figure 6.2

Notice that the value given to pan-to consists of two values separated by a comma: e.g. pan-to="20px,0px". The first value is the x-value that controls the amount of horizontal movement. The second value is the y-value that determines the amount of vertical movement.

x-component:

  • negative values: west (or left)
  • positive values: east (or right)

y-component:

  • negative values: north (or up)
  • positive values: south (or down)

Interestingly, x and y values can be provided in a variety of units:

  • pixels: pan-to="20px,0px"
  • percentages: pan-to="10%,0%"
  • millimeters: pan-to="5mm,0mm"
  • inches: pan-to="0.5in,0in"
  • centimeters: pan-to="2cm,0cm"
  • characters: pan-to=5ch,0ch"
  • other units of measurement in HTML and CSS such as em, ex, rem

In fact, values of pan-to can be any of the options in the analogous translate() CSS function.

Of course, you can give x-and-y values different from zero to simultaneously move up-down and left-right, for instance:

Figure 6.3

The panning effect also works on text (including a math equation, and code) and images. Again, you include this focus effect by attaching it to a trigger, for example:

Panning Effect
Normal position @cr-sticky

Panning to the left [@cr-sticky]{pan-to="-10px,0px"}

Panning to the right [@cr-sticky]{pan-to="0px,10px"}

Normal position again @cr-sticky


Highlighting

To highlight certain lines of text in a sticky element you use the highlight effect, e.g. [@cr-sticky]{highlight="1"}

The way highlight works is by emphasizing certain parts of text (e.g. a certain line or certain words) while de-emphasizing the rest of the text, as illustrated in the following diagram:

Figure 6.4

As you can tell from the above figure, to highlight the first line of text of a sticky poem with label #cr-sticky, you use [@cr-sticky]{highlight="1"}. In turn, to highlight the second line of the poem, you use [@cr-sticky]{highlight="2"}.

It turns out that you can highlight several lines of a sticky poem as well. One option is to provide a numeric range of values, say [@cr-sticky]{highlight="2-4"} which will highlight lines 2, 3, and 4. Likewise, you can also provide multiple non-consecutive numbers, separated by comma, for instance: [@cr-sticky]{highlight="2,4"} which will highlight lines 2 and 4, skipping line 3.

Since code is also considered to be text, you can also highlight lines of code:

Figure 6.5

Keep in mind that the highlighting effect only works on text (including code) but not on images.

Highlighting Effect
Normal text @cr-sticky

Highlighting first line [@cr-sticky]{highlight="1"}

Highlighting lines 2-4 [@cr-sticky]{highlight="2-4"}

Normal text again @cr-sticky

Highlighting certain parts (or words)

When you provide a numeric value to the highlight effect, e.g.  [@cr-sticky]{highlight="1"}, the entire line of text will be highlighted. Often, though, you may be interested in highlighting just a single word, or some part of a line of text. To obtain this type of highlighting you have to use a special type of sticky referred to as a named span and its corresponding span highlighting effect, as shown in the next figure:

Figure 6.6

Let’s discuss what’s going on in this highlighting example. There is one sticky component #cr-sticky involving four lines of text; notice that each line of text starts with the vertical bar | in order to render the text, line by line. Another thing to notice is the named span [fox]{#cr-fox} defined within the sticky. This is a kind of “sub-sticky” or “inner sticky” that only affects the word fox. Regarding the triggers, we have a first trigger @cr-sticky that will make the sticky appear, and then we have a second trigger [@cr-sticky]{highlight="cr-fox"} which will cause the highlighting effect on the named span which in this case corresponds to the word fox.


Zooming

With stickies consisting of text or code, in addition to all the previous effects, you scan also focus the view on a line number or named span with zoom-to

Zooming Effect
Normal text @cr-sticky

Zooming to first line [@cr-sticky]{zoom-to="1"}

Zooming to named span [@cr-sticky]{zoom-to="cr-fox"}

Normal text again @cr-sticky


Scale to Fill

In addition to the four focus effects previously described, there is an extra effect called scale-to-fill. The purpose of this effect is to stretch a sticky (e.g. text or image) in a way that fills the entire region containing such sticky, as depicted in the next figure.

Figure 6.7

scale-to-fill is a special kind of effect because instead of attaching it to a trigger, you attach it as an attribute when defining a sticky, for example:

Scale to fill
Triggering text @cr-sticky

:::{#cr-sticky .scale-to-fill}
| The quick
| brown fox
| jumps over
| the lazy dog
:::

While scale-to-fill has some resemblance to scale-by, they are not the same. Unlike scale_by, when scale-to-fill is triggered, the sticky will fade in and transform such that it fills the viewport.