What Makes the Table Scroll and Table Navigate Actions Different?

If you’re looking at manually updating a scrollable table, you’ve likely come across these two functions: Table Scroll (gra.table.scroll) and Table Navigate (gra.table.navigate).

At first glance both of these functions seem to do the same thing, but there are some key differences which set them apart. 

First, it’s important to understand what it means to “scroll” a table. The term “scroll” is used to describe the actual moving of a table cell to a new position based on a given direction. You can think of this as the “animation” of the cell’s movement.

Second, you should also understand the concept of an active index. When a user presses a table cell, that cell’s index is now considered “active” (think: in focus). This is so that we can track which specific cell has been interacted with (row, col). So if you press the first cell in a table, the active index would be 1,1. 

With this in mind let’s now take a look at these table actions.

The Table Navigate action actually sets the active index of a given table. It won’t perform a scroll animation unless the active index is currently not visible. In which case it will scroll to said active cell.  

The Table Scroll action simply performs this scrolling “animation” and doesn’t adjust the active index at all.

To better illustrate, take a look at the following.

This sample table is set up so that when a cell becomes active, the number in the cell will change its color from black to green.

Here is the table being adjusted via Table Scroll:

Notice how the scroll animation occurs each time the button is pressed. Also we can see that the first cell of the table is green, because it is active on startup, but as we scroll, no other cell turns green because Table Scroll does not affect a cell’s active status.

Now let’s look at adjusting it via Table Navigate:

Notice how the table doesn’t immediately scroll on button press. Instead the action is changing which cell is active (visualized by turning the color green) and it is only when the next active cell is not currently visible that the table is scrolled to show the next cell.

The benefit of having a cell set to active is that you can now trigger behavior based on said active cell. This means Table Navigate is really beneficial if your goal is to create a way to actually navigate your application without having to press the table. Some examples of this may be if you want to create navigational buttons such as arrows to walk through your menu or walk through your application via external hardware like a keyboard.

These are the key differences between these two actions. Depending on your goals, one will suit your needs better than the other.