DEV Community: Aspen James

Scroll-able Menus with Curses in Ruby

Aspen James — Mon, 01 Jul 2019 22:52:48 +0000

This is part 2/n of a blog series in which I develop a terminal-based Kanban
board application. To read part 1, go here. I want to talk about one
feature that I needed for this and how I implemented it using Ruby, and that's
having scroll-able menu options.

The Goal

I wanted a way to display a menu of options to my users that they could
navigate by scrolling (with their keyboard), and make a selection using the
Enter key. I initially expected there to be a method or class to perform this
function for me since it seemed like such a common use case, but that's not the
case! Turns out we need to do things a bit more manually. Let's start with a
basic example:

Simple Scroll-able Menu

I've made a really basic example of a scroll-able menu here.
All this program does is display a collection of items as a list and allow
users to scroll through it. I've defined a constant, OPTIONS, which is an
array of strings - these are going to be our list items. We also have an
instance variable, @highlight, which will serve as a pointer to the
index of the currently "selected" item, initialized at 0. You'll also
find methods named move_highlight_up and move_highlight_down. These handle
moving the highlighted item up and down. The way they are currently written,
the selection wraps around from bottom to top and top to bottom when reached.
In other words, if you're trying to scroll down while at the bottom of the
list, then the selection wraps around to the top. Let's have a look at one of
these to see how it works:

def move_highlight_down
  if @highlight == OPTIONS.length - 1
    @highlight = 0
  else
    @highlight += 1
  end
end

Since we're moving down the list, we want to check first if we're at the
bottom. The index of the last item in a collection will be one less than its
length, so that's why we're subtracting 1 from the OPTIONS.length. If that's
the case, we want to wrap back to the first item, index 0. If we're not at the
bottom, we increment the highlight pointer. We do the same in reverse for
moving the highlight up. If we wanted a user to be able to scroll to the end of
a list and stop instead of wrapping, we could write the method like so:

def move_highlight_down
  unless @highlight >= OPTIONS.length - 1
    @highlight += 1
  end
end

In this example, we're only going to increment the highlight pointer if we're
not yet at the bottom of the list. There are a couple other ways to implement
this (as with anything Ruby), but this should give you a couple starting
options.

Displaying the menu

We have a method called display_menu that actually handles drawing the menu
on the user's screen. This is where the visual element of "selecting" an item
comes in. We're going to use some attributes in order to make our
selected item visually different from the rest. The attribute we're interested
in is A_STANDOUT because it makes text well... standout. We want to apply
this attribute when an item's index matches our highlight pointer. That code
looks like this:

def display_menu
  current_line = 1

  OPTIONS.each_with_index do |opt, idx|
    WINDOW.setpos(current_line, 1)
    if @highlight == idx
      WINDOW.attron(Curses::A_STANDOUT)
      WINDOW.addstr(opt)
      WINDOW.attroff(Curses::A_STANDOUT)
    else
      WINDOW.addstr(opt)
    end
    current_line += 1
  end

end

It looks like there's a lot going on here, but it's not as complicated once we
break it down. First, we want to initialize a variable to hold our current line
position. We iterate over all of the list items (OPTIONS here). For each
iteration, we are setting the cursor position (using our current_line
variable) and using WINDOW.addstr to display that option. However, we're also
checking to see if that option's index matches our highlight pointer first. If
that is true, then we're applying the A_STANDOUT attribute. We also don't
want to forget to increment our current_line in each iteration!

Letting our users scroll

Now that we have our nice helper methods to display the menu and move our
highlight around, we need a way to let our users interact with our menu. I'm
going to focus on keyboard navigation, but Curses does support mouse
integration as well. My application won't have mouse support (maybe a
stretch goal), so we'll skip over that for now. The way I've made these
scrolling menus work is with a basic loop like this:

loop do
  display_menu
  Curses.refresh
  ch = WINDOW.getch

  case ch
  when 'j'
    move_highlight_down
  when 'k'
    move_highlight_up
  when 'q'
    break
  end

end

The first three lines of the loop call our display_menu method, refresh the
screen, and waits for a key press from the user. We store which key is pressed
in a variable called ch, and run a case statement on that. Our control
characters are 'j', 'k', and 'q' for this basic example. Any control characters
you define as "exit" characters will break the loop and allow the program to
continue. Right now the only other thing it does is close, so pressing 'q' here
quits the program. Pressing 'j' calls our move_highlight_down method, and 'k'
calls our move_highlight_up method.

Making a Selection

We now have a menu that our users can scroll through, but that's not super
useful all on its own. What makes this actually useful is when we can use that
scroll-able menu to enable our users to make a selection from that menu in
order to perform an action. Our options above are structured as an array, and
our @highlight pointer is a reference to the index of whichever item is
currently selected. This is structured like so intentionally, because that
means we can use the pointer to return a specific element from that array!
Let's take a look at what that code may look like:

def get_choice
  loop do
    display_menu
    Curses.refresh
    ch = WINDOW.getch

    case ch
    when 'j'
      move_highlight_down
    when 'k'
      move_highlight_up
    when 10 # '10' is the key code for 'Enter'
      return OPTIONS[@highlight]
    end
  end
end

The main difference (besides being put into a method) is that we use the enter
key as a control character to define making a selection, and we've removed the
option to quit with the 'q' key. That's optional, we could leave the quit
option there as a way to break out of the program quickly, entirely up to how
you would like to define the interface. The important thing is that we're
returning the currently highlighted option when the user presses enter.

More complicated menus

Having a basic menu is great, but for my use case I needed a way for users to
scroll options both vertically and horizontally. The interface I'm working with
has three collections of items arranged in three columns, so a basic pointer
didn't seem like the ideal way to do this. In rethinking which data structure
would be appropriate, I narrowed it down to a couple key features I wanted - a
data structure that would hold two integers and let me access those in a way
that made their purpose clear. For this, I turned to a Struct. A
struct would let me access the information in a way that semantically made
sense, while reducing the overhead of creating an entire class. It looks a
little something like this:

@highlight = Struct.new(:col, :itm).new(1, 1)

The advantage this gives us over our simpler highlight pointer before is that we now can hold references to the column number as well as the row number. The way we access these are also descriptive of their values - @highlight.col to access the selected column and @highlight.itm to get the index of the item within that collection. You can see this code in action in the [tknbn repository][tknbn] under the curses-playground branch. In the lib/tknbn/curses/main_menu.rb file, we've got a Project object that we're working with. That object has many Items in three different stages - TODO, In Progress, and Done. The methods for moving the highlight up and down are largely the same with the addition of a get_num_items method which returns the length of the collection for the currently selected column. Our methods for moving left and right look like this:

def move_cursor_right
  if @hl.col == 3 # If rightmost selected
    @hl.col = 1   # Move to leftmost
    num_items = get_num_items
    if @hl.itm > num_items
      @hl.itm = num_items
    end
  elsif @hl.col == 1 # If leftmost selected
    @hl.col = 2      # Move to middle
    num_items = get_num_items
    if @hl.itm > num_items
      @hl.itm = num_items
    end
  else
    @hl.col = 3 # Move rightmost
    num_items = get_num_items
    if @hl.itm > num_items
      @hl.itm = num_items
    end
  end
end

def move_cursor_left
  if @hl.col == 1 # If leftmost selected
    @hl.col = 3   # Move to rightmost
    num_items = get_num_items
    if @hl.itm > num_items
      @hl.itm = num_items
    end
  elsif @hl.col == 3 # If rightmost selected
    @hl.col = 2      # Move to middle
    num_items = get_num_items
    if @hl.itm > num_items
      @hl.itm = num_items
    end
  else
    @hl.col = 1 # Move leftmost
    num_items = get_num_items
    if @hl.itm > num_items
      @hl.itm = num_items
    end
  end
end

If you notice the repeated code, you're right! There is an opportunity to
refactor some pieces there. What we're trying to accomplish with the line
@hl.itm = num_items is a way to handle adjusting which item index we're
pointing to in case it is outside the range of the collection that @hl.col
now refers to. This can happen if we have the 5th element of a column selected
and we move to a column that has less than 5 elements. Whenever we move to a
new column, we want to make sure we're pointing to a valid element. There's
another method I'm working on there called adjust_highlight that does much
the same thing, but can also account for deleting the last item in a
collection, etc. I don't write many recursive methods/functions, so it could
likely be optimized, but I think it's pretty cool.

What's next

I'm starting to feel like I have most of the pieces of this project figured
out, so it's just about time for a round of some major refactoring and cleaning
up code. I have intentionally been letting myself write code all over the place
while I learn some of the best ways to work with this library with the idea
that there would be a pretty major refactor back into the master branch once I
got somewhere comfortable. I want to explore forms next, which I'll
probably do in the same fashion before refactoring. The next blog installment
will likely be about that major refactor itself.

Writing a Terminal Application in 2019

Aspen James — Thu, 06 Jun 2019 19:39:59 +0000

I'm building an application that lives and runs inside of the terminal! This will be a blog series that documents my process, struggles, wins, and motivations for doing so when most of us live in feature-rich graphical user interfaces.

What's Wrong With a GUI?

Nothing is "wrong" with a GUI (graphical user interface). These are the types of applications we're (most likely) most familiar with interacting with these days. Examples would be the browser with which you're likely reading this (unless you use lynx, w3m, or another terminal browser client), your development environment if you're using a tool like Atom or VS Code, photo editors, video editing programs, etc. These are applications that run in their own window and have full, rich graphics, colours, and interactivity.

So why am I creating a TUI (text/terminal user interface) application? Short story is that I'd like to. There are a lot of benefits that come with an application that runs entirely on text within a shell - portability, speed, and vastly lower system resources. Most modern browsers use astronomical amounts of RAM, and depending on what they're doing can also tie up your CPU. How you define "astronomical amounts of RAM" is probably different from how I do, but nobody can deny that their browser is often RAM-hungry. I also value things that run offline. In addition to not needing to be connected to the Internet to even run, it is not affected by any number of security threats that are present with Internet-connected applications.

I also value protection of data. I believe that a user's data is their own, and they should own and be in control of it. Many either don't agree or don't care, but in a world where software users have little power in how their data is collected and used, I place high value on being able to own and control one's own data. When using my application, your data will live on your machine. You own it, it's yours, I don't (and can't) see or touch it. I think that's beautiful.

What Am I Making?

I am aiming to make a simplified version of a Kanban board manager - something akin to Trello. These tools are extremely useful for planning out and organizing work on projects, and are especially useful for managing a software project. I like using them, but everything I can find is Internet-connected. Most of these (like Trello) are proprietary applications, and I have no idea where my data lives, who owns it, and how it's being used. There are ways to find this information occasionally, but they can be complicated and tedious. Complicated and tedious are not things that I value when trying to plan out my projects.

There are Free and Open Source solutions available, and many of these will allow you to set up, configure, and own your own server instance. Taiga is one option that I have been using and enjoying lately. But even in creating your own server, you need to be connected to run this application - either via the Internet to a hosted server instance, or locally on your own machine. Both of these are not ideal, as they are either Internet-connected, or are RAM-hungry. If I'm running both a server AND a browser instance to connect to said server, I have solved almost no problems and am using even more RAM than before.

The Tools

I have chosen to use the Curses library for Ruby. I chose Ruby because I love it, and it's a great language. Also my students were building their command-line applications using Ruby, so I wanted to build a project using similar technologies in a similar fashion. I chose Curses because there are a number of applications I use and love that use either Curses or ncurses.

Ncurses is software that allowed terminal applications to have more advanced interfaces and features and served as a precursor to modern GUI environments. It is an improvement over the earlier BSD Curses implementation (that is now deprecated). It supports creating sub-windows, forms, creating scroll-able menus, colours, highlighting, and many other features.

The Current Struggles

I have never used Curses/Ncurses prior to diving into this project. The existing Ruby documentation for the Curses library seems to assume a prior familiarity with the C implementation of Curses, as it is more or less a list of methods and signatures. This makes discovery of features and knowing the abilities/limitations of the library difficult. I found this tutorial from another friendly developer that was extremely helpful in just getting off the ground.

Beyond that, I have been finding examples of programs in C that do what I want to do, reading and understanding them (as best I can, I don't know C beyond a cursory understanding), and trying to match those features to methods available in the Ruby docs. It's been a fairly slow process and discovery takes a while, but it's been working! My goal in this blog series will be to illuminate some various features of the Ruby Curses library and hopefully make breaking into writing rad terminal applications with Ruby less intimidating.

Show Me The Code!

At the time of writing this (June 6, 2019), this application is very bare-bones. It lives on here on GitHub, is licensed under the GNUGPL v.3, and as such is free for you to (more or less) do what you like with it. Fork it, improve it, redistribute it, read it, copy it, etc.

Most of my current work is in the curses-playground branch, and as the name suggests, it's a playground. I'm leaving some descriptive comments, but it's far from structured or DRY. Once I get an MVP working there, I'm going to restructure and rewrite onto master. Is this ideal? No. Is it working for me? Yes. Should you program this way? Up to you!

I chose to have a space to just dump code and play around with the library, because that's the way I learn best. I like to break things and find limitations, write sloppy code, and clean it all up later. It really helps me to get out of reading forever and into actually building something, but that may not be the ideal path for everyone. I'm interested in hearing other folks' workflows, I'm not particularly interested in anyone's opinion of my own. Do what makes you happy!

Phones Are Scary

Aspen James — Mon, 11 Mar 2019 22:10:12 +0000

Your cell phone may be tracking, logging, and reporting more than you ever expected. Most of us know that our phones can transmit a lot of data about who we are, where we are, and what we're doing. I thought I knew a fair amount about this, but the more I looked into this, the more I realized how much more is possible to collect from the sensors built into your phone. The fact is that as these technologies improve, so do the ways attackers can use these technologies to obtain information about you.

Before we get in to all of this, I want to address something. I'm going to talk about specific products and companies in this post, and that's because I think what they're doing is really cool. I am not sponsored nor do I gain any benefit from sharing this information. I think these things are important for everyone to know, and I'd rather give some potential solutions rather than just state problems, and there isn't a great way to do that without naming specific products.

That all sounds pretty ambiguous...

Ambiguity is lame, so let's look at a specific example: your accelerometer.

What does an accelerometer do? An accelerometer measures acceleration. This makes things like detecting the orientation of your phone possible, as well as detecting movements. Orientation and movements are extremely useful for navigation with a map application, and can enable some pretty cool features in some mobile games. This article from 2013 explains that your accelerometer data does not require your permission to collect and use (aka you won't see a pop-up asking if it's okay to use this data). Some fairly simple analysis on this data can get a good approximation of your PIN or pattern used to unlock your phone.

Even if you have GPS tracking disabled, pairing speed and direction data (from your accelerometer) along with detecting nearby WiFi access points (which your phone will do, even if you have location services turned off) can theoretically give a great estimate of your location as well.

For some added paranoia, check out this article which describes how your ambient light sensor (useful for adjusting your backlight, amongst other things) can be used to "fingerprint" a user. The article also talks about how it's theoretically possible to use this ambient light data to map out a building.

Sounds like some Tin Foil Hat stuff

I will concede that this all sounds like your run-of-the-mill "The Government is Watching Me" paranoia, but this is real and this is happening. Since so much of this data does not require explicit permissions, so much of your personal and identifying information can be collected by any number of organizations. The products and services you use are undoubtedly collecting your data and using it to drive profits in one way or another, and they are doing it without your explicit knowledge or permission. I'm okay with being perceived as wearing a tin foil hat - sometimes that's the cost of consciousness and concern for privacy.

What can I do?

While we can't always stop this data from being collected and used against our will, we can take steps to prevent this. One of the easiest things you can do is to use a VPN (Virtual Private Network). There are many advantages to using a VPN, as well as many factors to consider when choosing one. That list is too long for this short article, but some searching around can find you some good articles, comparisons, and a lot of opinions. I use Private Internet Access - it is easy to use and suits my needs, but I encourage you to shop around and find one that fits your needs.

Another line of defense is to get privacy-respecting hardware. Purism is a rad company that makes hardware that respects users' privacy and runs on free software. They have a line of laptops available now, as well as a phone that you can pre-order now. These devices feature "hardware kill switches" - physical switches that disconnect your camera, microphone, WiFi adapter, etc on a hardware level, meaning that there is physically no way to collect data from them. This blog post from their website goes into more detail the points I made above, as well as how their hardware and software solutions address these issues.

In short, try to find products that respect your privacy and security, and be aware of what sorts of data the companies whose products you use may be collecting from you. When in doubt, choose open source.