Sliders and Documentation
Lately most of my software development time has been spent on a mobile application for coffee evaluation. I’d say that it’s a cupping app, but this would cause people to expect that it is similar to other programs for handling cupping data (including the last two that I wrote) when it goes beyond cupping to a more general problem. Between consideration of some of the other use cases and experience using a prototype of the application, I decided that I needed a new user interface element.
A slider widget is a user interface element that allows the selection of value from a finite range. As they allow direct manipulation, they are particularly well suited to touch oriented interfaces. For numeric input, there are a few alternatives. Text fields can be constrained to only accept numeric input, but typing values can be cumbersome. A spin box provides controls for incrementing and decrementing a value, but it takes too long to change the value from one side of the range to the other. The basic slider widget also has its limitations, but with the ability to quickly tap a value near the desired one and drag across the widget if needed to fine tune that selection, it’s probably the fastest option, but I wanted a few features a slider does not provide.
Consider evaluating a coffee for quality assurance purposes. There would exist a specification for that coffee: a list of scored attributes with an accepted range of values for each attribute. It would be useful for the slider widget to provide a visual indication of whether the selected value is within the specified tolerance. This can be done by subclassing a slider class, replacing the code that draws the widget, and providing a way to specify what color to draw the value area for various value ranges. Tick marks could be drawn across the widget at the edges of differently colored regions to provide an additional visual aid when selecting values.
Next, there is the problem that sliders do not display their value. When a program is used on a device with a large screen, this isn’t a problem. If the selected value needs to be visible, it can be shown on a label next to the slider. Unfortunately, the usability of a slider widget depends on both the width of the widget and the number of distinct values the slider represents. On a mobile device with limited screen space, it would be better to display the value in the widget rather than next to it.
Finally, there are many cases where a person would like to be able to select fractional values, but slider widgets only select integer values. As long as the number of selectable values is finite and enumerable, it is possible to map those values onto a set of integers the slider can use.
While writing the classes that implement these features in a slider widget, I decided to try providing two different styles of documentation. Typically, when documenting software, the author will document either the interfaces provided by that software or the design of that software. Put another way, the documentation describes either how to use the software or how the software works. For these slider widgets, I decided I would do both and see which set of documentation is most useful in the long term.
To document how the software works, I wrote the classes and documentation in such a way that it could be run through CWEB. This is a system that allows me to write the source code as comments to the documentation. It also allows me to split functions into named chunks which can be documented separately. For example, the code that handles drawing the described widget looks like this:
The full documentation can be read here.
The other style of documentation is generated by Doxygen. This takes specially formatted comments and produces documentation what parts make up that software and how to use them. That documentation is available here.
