Once I finally figured out that keyboard events require objects derived from UWP’s Control class, the rest was pretty easy. UWP has a large library of common controls to draw from, but none really fit what I’m trying to present to the user.

What came closest is a ScrollViewer, designed to present information that does not fit on screen and allows the user to scroll around the full extents much as my camera on a 3D printer carriage can move around the XY extents of the 3D printer. However, the rendering mechanism is different. ScrollViewer is designed to let me drop a large piece of content (example: a very large or high resolution image) into the application and let ScrollViewer handle the rest independently. But that’s not what I have here – in order for scrolling to be mirrored to physical motion of 3D printer carriage, I need to be involved in the process.

Lacking a suitable fit in the list of stock controls, I proceeded to build a simple custom control (based on the UserControl class) that is a composite of other existing elements, starting with the CaptureElement displaying the webcam preview. And unlike on CaptureElement, the OnKeyDown and OnKeyUp event handlers do get called when defined on a UserControl. We are in business!

Once called, I have the option to handle it, in this case translating directional desire into G-code to be sent to the 3D printer. My code behavior fits under the umbrella of “inner navigation”, where a control can take over keyboard navigation semantics inside its scope.

I also have the ability to define special keys inside my scope, called accelerators ([Control] + [some key]) or access ([Alt] + [some key]) keys. I won’t worry about it for this first pass, but they can be very powerful when well designed and a huge productivity booster for power users. They also have a big role in making an application keyboard accessible. Again while it is a very important topic for retail software, it’s one of the details I can afford to push aside for a quick prototype. But it’ll be interesting to dive in sometime in the future, it’s a whole topic in and of itself. There’s literally a book on it!

In the meantime, I have a custom UserControl and I want to draw some of my own graphics on screen.

For my computer-controlled camera project, I thought it would be good to let the user control position via arrow keys on the keyboard. My quick-and-dirty first attempt failed, so I dived into UWP documentation. After spending a lot of time reading about nuts and bolts of keyboard navigation, I finally found my problem and it’s one of the cases when the answer has been in my face the whole time.

When my key press event handlers failed to trigger, the first page I went to is the Keyboard Events page. This page has a lot of information up front and center about eligibility requirements to receive keyboard events, here’s an excerpt from the page:

For a control to receive input focus, it must be enabled, visible, and have IsTabStop and HitTestVisible property values of true. This is the default state for most controls.

My blindness was reading the word “control” in the general sense of a visual element on the page for user interaction. Which is why I kept overlooking the lesson it was trying to tell me: if I want keyboard events, I have to use something that is derived from the UWP Control object. In other words, not “control” in the generic language case but “Control” as a specific proper name in the object hierarchy. I would have been better informed about the distinction if they had capitalized Control, or linked to the page for the formal Control object, or any of a number other things to differentiate it as a specific term and not a generic word. But for whatever reason they chose not to, and I failed to comprehend the significance of the word again and again. It wasn’t until I was on the Keyboard Accessibility page did I see this requirement clearly and very specifically spelled out:

Only classes that derive from Control support focus and tab navigation.

The CaptureElement control (generic name) used in the UWP webcam example is not derived from Control (proper name) and that’s why I have not been receiving the keyboard events. Once I finally understood my mistake, it was easy to fix.

In a UWP application, we have two major ways for navigating UI controls using the keyboard: a linear path using Tab key (and shift-Tab to go backwards), and a two-dimensional system with the four arrow keys. A part of what makes learning UWP keyboard navigation difficult is the fact that these two methods are both active simultaneously and we have to think about what happens when an user switches between them.

Application authors can control tabbing order by setting TabIndex. It is also the starting point of keyboard navigation, since the initial focus is on the element with the highest TabIndex. Occasionally the author would want to exclude something from tabbing order, they could turn that off by setting IsTabStop to false. I thought that was pretty easy until I started reading about TabFocusNavigation. This is where I’m thankful for the animation illustrating the concept on this page or else I would have been completely lost.

On the arrow navigation side, XYFocusKeyboardNavigation is how authors can disable arrow navigation. But since it is far from a simple system, selectively disabling certain parts of the app would have wildly different effects than simple “on” or “off” due to how subtrees of controls interact. That got pretty confusing, and that’s even before we start trying to understand how to explicitly control the behavior of each arrow direction with the XY focus navigation strategies.

Even with all these complex options, I was skeptical they could cover all possible scenarios. And judging by the fact we have an entire page devoted to programmatic focus navigation, I guess they didn’t manage. When the UI designer wants something that just can’t be declared using existing mechanisms, the application developer has the option of writing code to wrangle keyboard focus.

But right now my problem isn’t keyboard navigation behaving differently from what I wanted… the problem is that I don’t see keyboard events at all. My answer was elsewhere: I had no control, in both senses of the word.

After a quick review of the of UWP keyboard event basics, I opened up the can of worms that is keyboard navigation. I stumbled into this because I wanted to use arrow keys to move the 3D printer carriage holding a camera, but arrow keys already have roles in an application framework! My first effort to respond to arrow keys was a failure, and I hypothesized that my code conflicted with existing mechanisms for arrow keys. In order to figure out how I can write arrow key handlers that coexist with existing mechanisms, I must first learn what they are.

Graphical user interfaces are optimized for pointing devices like a mouse, stylus, or touchscreen. But that’s not always available, and so the user needs to be able to move around on screen with the keyboard. Hence the thick book of rules that is summarized by the UWP focus navigation page. As far as I can tell, it is an effort to put together all the ways arrow keys were used to move things around on screen. A lot of these things are conventions that we’ve become familiar with without really thinking about it as a rigorous system of rules, many were developed by application authors so it “felt right” for their specific application. It reminds me of the English language: native speakers have an intuitive sense of the rules, but trying to write down those rules is hard. More often than not, the resulting rules make no sense when we just read the words.

And, sadly, I think the exact same thing happened in the world of keyboard navigation. But in a tiny bit of good news, we’re not dependent on understanding words, this page also had a lot of animated graphics to illustrate how keyboard navigation functions under different scenarios. I can’t say it makes intuitive sense, but at least seeing the graphics help understand the intent being described. It’s especially helpful in scenarios where tab navigation interacts with arrow key navigation.

I wanted to have keyboard control of the 3D printer carriage, moving the webcam view by pressing arrow keys. I knew enough about the application framework to know I needed to implement handlers for the KeyDown and KeyUp events, but in my first implementation those handlers are never called.

If at first I don’t succeed, it’s time to go to the manual.

The first stop is the overview for UWP Events and Routed Events, the umbrella of event processing architecture including keyboard events. It was an useful review and I was glad I hadn’t forgotten anything fundamental or have missed anything significantly new.

Next stop was the UI design document for keyboard interactions. Again this was technically a review, but I’ve forgotten much of this information. Keyboard handling is complicated! It’s not just an array of buttons, there are a lot of interactions between keys and conventions build up over decades as to what computer literate users have come to expect.

When I think of key interactions, my first reaction is to think about the shift key and control key. These modifier keys change the meaning of another button: the difference between lowercase ‘c’, uppercase ‘C’ and Control+C which might be anything from “interrupt command line program” to “Copy to clipboard.”

But that’s not important to my current project. My desire to move the camera carriage using arrow keys opened up an entirely different can of worms: keyboard navigation.