Tutorial: Creating a navigation bar

31 December 2013

Tutorial: Creating a navigation bar

Using Corona, it’s easy enough to create our own top navigation bar — just draw the background, add some title text, and place the buttons as necessary. But if we want to adhere to the “DRY” programming theory (Don’t Repeat Yourself), including an entire set of navigation bar code in every scene of an app is more work than it should be.

About the navigation bar

In the iOS vernacular, the top navigation bar is known as the UI Navigation Bar and it has fairly consistent behavior:

• a background
• an optional left button
• an optional right button
• an optional title

This tutorial illustrates how to create a standard iOS-style “UI Navigation Bar” widget in which we provide the definitions for two buttons, the functions to handle button interaction, and some basic information to draw the bar.

Setup

Like we did in the Customizing text input tutorial, let’s begin by expanding the core widget library and defining the default parameters:

When creating a top nav bar, there are a few things to consider, and we’ve done so in this code. For example, does the app have a device-specific status bar? If so, the nav bar should be positioned below it, but the area the status bar occupies is still space that we’re responsible for. Because we cannot programmatically detect if the status bar is showing or not, we must pass in a flag that states if we decided to show or hide the status bar. The function will then calculate the status bar height and adjust placement of the nav bar accordingly.

Next, let’s construct the bar itself:

In this code block, we start by creating a container group to hold all of the visual objects. Then, a rectangle is created for the “background” and it’s added to the container group. Next, the passed-in parameters determine how to fill the rectangle — either with a specified image, a solid color, or (if nothing is provided) a solid white fill.

Now, let’s add the “title” of the page to the nav bar, if provided (note that some iOS apps don’t use titles):

Now, let’s set up the buttons. There will be two buttons in this example: a “left” button and a “right” button. To keep things simple, we’ll use the existing widget.newButton() widget — essentially, we’ll pass the parameters to the button constructor:

If images are provided via the defaultFile attribute, the code looks for the parameters associated with image-based widget buttons (see the documentation). If simple text buttons are preferred, we can specify a label, font, fontSize, and labelColor array. Once both buttons are set up, we just return the container to the caller as a reference to the object.

Using the navigation bar widget

To use this new widget, we simply include the above code in main.lua. It will be added to the widget library, so in other modules where you require("widget"), it will be available to you. Then, when we need to display a new navigation bar, we follow three basic steps:

1. Write the button listeners

The buttons on the nav bar will not be very useful unless there are callback listeners associated with tap action upon them. As such, let’s include some basic listener functions in the module where we want to use the nav bar:

2. Declare the navigation bar buttons

Now, let’s configure the buttons specific to this nav bar. In this example, the left button will be a two-image button and the right button will be a simple text button. Notice that we are also including a reference to the callback listeners we just wrote so that our buttons respond to touch.

3. Declare the navigation bar

Finally, we declare the actual navigation bar as follows:

Where from here?

There’s plenty of room for you to expand on this concept. First, this is very iOS-friendly, but it doesn’t build Android-style navigation bars. The Android-style top bar is more like the iOS Toolbar, with a series of buttons on the right side and a “hamburger” icon and graphic title on the left. Secondly, this example could be expanded to support more button styles than 2-image or basic text buttons. Finally, this example doesn’t support the navigation chevrons (less-than and greater-than symbols), but it could be configured easily enough.