Announcing the visualcounter module

It has been almost two years since I posted about the main idea of the visualcounter module. I am happy to announce the official release of the module. I have been using this module in my presentations for almost two years without any problems, so I believe that it is stable enough to be released.

At present, the module is available on github and it should be available through ConTeXt garden soon. Look at the documentation to see some of the features of the module (in particular, the "star rating" example based on Jim Hefferon’s article in the Practex Journal).

The module provides six counters. Two of these were created for proof of concept and are not well tested; the remaining four—scratchcounter, mayanumbers, markers, and countdown—are well tested and, hopefully, their interface will not change.

This was my first module that uses the ConTeXt namespace macros. If you peek into the module, you’ll notice that I only define one macro; everything else is handled by the ConTeXt namespace macro \definenamespace.

The other interesting feature of this module is that I use a separate metapost instance for displaying the counters. This avoids conflict with user definitions. For example, if a user decides to change the metapost definition of fill for whatever reason,

\startMPdefinitions
let fill = draw;
\stopMPdefnition

such a change will not affect the visual counter module!

Any feedback is appreciated.

visual counter for Maya numbers

The other day I saw the documentary breaking the Maya code. At one stage they showed how the Maya number system worked. If you haven’t seen the documentary, see the wikipedia page on Maya number system. I thought that this would be a nice way to visually represent page numbers in presentations. So, I added a new style to the visual counter, unimaginatively called mayanumbers. A test file comparing this affect with other visual counters from the module is in the github directory of the module.

Have a look at the output pdf. It uses four counters; cycically from the top-left corner they are: countdown, pulseline, scratchcounter, and finally, mayanumbers. !’ll definitely experiment with mayanumbers in my next presentation.

Introducing the visual counter module

A typical document usually contains many contains many counters: page numbers, section numbers, enumerations, theorems, and so on. Displaying all these numbers gets boring quickly. Do you want to spice up the document a bit? Enter the visual counter module.

The idea is simple. Each counter already keeps track of its current and maximum value. So, we can just pass that information to MetaPost and display the counter in a visually attractive manner. For example, to display page numbers, I use:

\usemodule[visualcounter]

\definevisualcounter
  [fancypage]
  [alternative=pulseline,
   counter=userpage]

\setuppagenumbering[location=]
\setupheadertexts[\usevisualcounter{fancypage}]

The options are pretty self explanatory. counter sets the name of the counter that we want to display (the module figures out its current and maximum (last) value) The alternative selects the type of visual counter that you want to use. The \usevisualcounter macro displays the counter. Currently, I have only implemented two alternatives: countdown and pulseline. (Here is an example showing both of them). I plan to add others in the future. Suggestions are welcome!

At the moment, there is no documentation. I am still playing around with the API and the code is in a state of flux. Nonetheless, you can take a look in the tests directory to see a few examples of how things work. Stay tuned for more posts on this module.

I am also using the new name space code in the module. It is very very elegant. The entire module has just three macros (two of them are just for convenience). Everything else is just a matter of setting the values for different options. A big advantage of the name space code is that the macros to access the value of a particular option are fully expandable. This means that they can be used directly inside Metapost. No need to have an extra \setMPvariables to pass values to Metapost. Yipee!

Note: It appears that github is down at the moment. Hopefully, it will come back up soon.

Who’s your daddy?

For a new module (see github) I needed to place a Metapost graphic so that it aligns with the baseline of the text. The simplest way to do this is

\framed[location=low,frame=off]{...}

or more rigorously

\defineframed[visualcounterframed]
             [location=low,frame=off]
...
\visualcounterframed{....}

However, something like this is error prone because every framed inherits settings from \setupframed. So, if the user sets:

\setupframed[offset=10cm]

suddenly all the frames used inside the module will have a 10cm offset. I could correct this by adding offset=0mm in \defineframed. But what if the user sets foregroundstyle=bold? Now I all Metapost labels will be bold. I could again correct by setting forgroundstyle=normal in \defineframed. If I follow this path, then I will need to set all the options of \setupframed to some sane values. But what about a module like simpleslides that uses 10 frames; I need to set defaults for all of them (Thomas, are you listening).

What I really want is that one instance of \defineframed should not inherit from \setupframed. In MkIV, the inheritance model is configurable. Almost all setup commands now accept a parent key. When an option for a command is not set, the parent name space is searched for that option.

For example, deep inside the definition of \defineframed is

\getparameters[\??ol#1][\s!parent=\??ol,#2]%

This sets \??ol as the parent name space for \defineframed. The \setupframed command sets option in the \??ol name space, and hence the inheritance.

So, to make sure that my \visualcounterframed is not affected by \setupframed, I just need to change its parent name space. First, I define a new name space:

\definenamespace
       [VISUALCOUNTER]
       [type=module,
        name=visualcounter,
        setup=yes]

This defines a name space, \????VISUALCOUNTER, with the name visualcounter. I do not know what type=module does, but that was present in all the examples that I looked. The option setup=yes defines a command \setupvisualcounter that can be used to set the \????VISUALCOUNTER name space. I could have also set parent=... if I wanted this name space to inherit from another one.

And now, all I need to do is set \????VISUALCOUNTER as the parent name space for \visualcounterframed:

\unprotect
\setupframed[visualcounterframed]
             [parent=\????VISUALCOUNTER]
\protect

and voila, isolation from default options of \setupframed. I think that all module that internally use a \framed should consider choosing an isolated parent name space.