Creating a Kotlin Android rotary knob

Recently I created an Android Metronome app. My initial implementation used a SeekBar to control BPM (Beats per Minute) — the rate at which the metronome ticks. However, as the project progressed, I wanted to make it resemble a physical digital unit, as used by many musicians in the real physical world.

Physical units do not have a “SeekBar View”, and I wanted to mimic the rotary knob an actual unit might have.
Rotary knobs are very useful UI controls. They are much like a slider or SeekBar, usable in many situations. Here are some of their advantages:

• They consume very little real estate in your app
• They can be used to control continuous or discrete ranges of values
• They are immediately recognizable by users from real world applications
• They are not standard Android controls and thus bestow your app with a unique “custom” feel

While a few open source knob libraries for Android exist, I didn’t find quite what I was looking for in any of them.
Many were an overkill for my modest needs, with functionality such as setting background images or handling taps for two or more mode operations, etc.
Some did not have the customizability I wanted to fit my project and came with their own knob image.
Others assumed a discrete range of values or positions.
Many of them seemed much more complex than needed.

So I decided to design one myself — which turned into a fun little project in itself.

In this article I’ll discuss how I built it.

The resulting metronome app and it’s rotary knob

So let’s see how we can create a rotary knob.

Designing a knob

The first step was to create the graphic for the knob itself. I’m no designer by any means, but it occurred to me that the key to creating a sense of “depth” and movement in a knob control would be to use an off center radial gradient, in order to create the illusion of a depressed surface and light reflection.

I used Sketch to draw the knob, then exported it to svg, and imported back into android studio as a drawable.
You can find the knob drawable in the github project at the link at the bottom of this article.

Creating the view in xml

The first step in creating the View is creating a layout xml file in the res/layout folder.

The view can be completely created in code, but a good reusable View in Android should be created in xml.
Notice the <merge> tag — we use that since we’ll be extending an existing Android Layout class and this layout will be the inner structure of that layout.
We’ll use an ImageView for the knob, which we’ll rotate as the user moves it.

To make the knob configurable by xml, we create attributes for the range of values the knob will return, as well as for the drawable it will use for visuals.
We’ll create an attrs.xml file under res/values.

Next, Create a new Kotlin class file, RotaryKnobView that extends RelativeLayout and implements the interface GestureDetector.OnGestureListener.

We’ll use RelativeLayout as the parent container for the control, and implement OnGestureListener to handle the knob’s movement gestures.

@JvmOverloads is just a shortcut to overriding all three flavors of the View constructor.

We’ll initialize some default values and define class members.

A note about the divider variable — I wanted the knob to have a starting and end positions, rather than being able to rotate indefinitely, much like a volume knob on a stereo system. I set the start and end points at -150 and 150 degrees respectively. So the effective motion for the knob is only 300 degrees. We’ll use the divider to distribute the range of values we want our knob to return upon these available 300 degrees — so that we can calculate the actual value based on the knob’s position angle.

Next, we initialize the component:
Inflate the layout.
Read the attributes into variables.
Update the divider (to support the passed in minimum and maximum values.
Set the image.

The class will not compile just yet, as we need to implement OnGestureListener’s functions. Lets handle that now.

Detecting user gestures

The OnGestureListener interface requires that we implement six functions:
onScroll, onTouchEvent, onDown, onSingleTapUp, onFling, onLongPress, onShowPress.

Of these, we need to consume (return true) on onDown and onTouchEvent, and implement the movement login in onScroll.

Here is the implementation of onScroll, we’ll fill the missing parts in the following paragraph.

onScroll receives two coordinate sets, e1 and e2, representing the start and end movements of the scroll that triggered the event.
We’re only interested in the e2 — the new position of the knob — so we can animate it to position and calculate the value.

I am using a function we’ll review in the next section to calculate the angle of rotation.

As mentioned earlier, we’re only using 300 degrees from the knobs start point to its end point, so here we also calculate what value should the knob’s position represent using the divider.

Calculating the rotation angle

Now let’s write the calculateAngle function.

This function calls for a bit of explanation and some 8th grade math.

The purpose of this function is the calculate the position of the knob in angles, based on the passed coordinates.
I opted to treat the 12 o’clock position of the knob as zero, and then increase its position to positive degrees when turning clockwise, and reducing to negative degrees when turning counterclockwise from 12 o’clock.

We get the x, y coordinates from the onScroll function, indicating the position within the view where the movement ended (for that event).
X and y represent a point on a cartesian coordinate system. We can convert that point representation to a polar coordinate system, representing the point by the angle above or below the x axis and the distance of the point from the pole.

Converting between the two coordinate systems can be achieved by the atan2 function. Luckily for us, the Kotlin math library provides us with an implementation of atan2, as do most Math libraries.

We do however, need to account for a few differences between our knob model and the naive math implementation.

1. The (0,0) coordinates represent the top right corner of the view and not the middle. And while the x coordinate progresses in the right direction — growing as we move to the right — the y coordinate is backwards — 0 is the top of the view, while the value of our view’s height is the lowest pixel line in the view.
   To accommodate that we divide x and y by the respective width and height of the view to get them on a normalized scale of 0–1.
   Then we subtract 0.5 from both to move the 0,0 point to the middle.
   And lastly, we subtract y’s value from 1, to reverse its direction.
2. The polar coordinate system is in reverse direction to what we need. The degrees value rises as we turn counter clockwise. So we add a minus sign to reverse the result of the atan2 function.
3. We want the 0 degrees value to point north, otherwise passing 9 o’clock, the value will jump from 0 to 359.
   So we add 90 to the result, taking care to reduce the value by 360 once the angle is larger than 180 (so we get a -180 < angle < 180 range rather than a 0 < x < 360 range)

The next step is to animate the rotation of the knob. We use Matrix to transform the coordinates of the ImageView.

We just need to pay attention to dividing the view’s height and width by 2 so the rotation axis is the middle of the knob.

And last but not least, let’s expose an interface for the consuming Activity or Fragment to listen to rotation events:

Using the knob

Now, let’s create a simple implementation to test our knob.

In the main activity, lets create a TextView and drag a view from the containers list. When presented with the view selection, select RotaryKnobView.

Edit the activity’s layout xml file, and set the minimum, maximum and initial values as well as the drawable to use.

Finally, in our MainActivity class, inflate the layout and implement the RotaryKnobListener interface to update the value of the TextField.

This example project is available on github as well as the original metronome project.
The Android Metronome app is also available on Google’s play store.