LiveCode Widgets: The Navigation Bar

by Ali Lloyd on May 5, 2016 10 comments

One of the first widgets we decided to include in LiveCode 8.0 was the navigation bar. The IDE previously included a mobile template as a sample stack, but the ability to provide this key bit of functionality as a drag and drop object in the tools palette was a no-brainer. It will hopefully prove to be an extremely useful tool for building native-looking mobile applications rapidly; it also demonstrates some of the power of the LiveCode Builder language that widgets are written in and the seamless integration of widgets in the IDE.

The most common way to use the navigation bar is as a way of allowing the user to switch between the screens of your app. Typically the navigation bar will contain just a few lines of code:

on hiliteChanged
    go to card the hilitedItemName of me
end hiliteChanged

Note: it is important to understand the distinction between the name and the label of each navigation item. If you open up the property inspector for the navigation bar, you can change both of them.

navbar pi

The text that is actually displayed for a navigation item, provided the display style is either “text” or “both”, is the label.

navbar label

The value of the hilitedItemName property is the name of the currently highlighted navigation item. This allows multiple items to have the same label and still be distinguishable from script.

When using the navigation bar in this way, the simplest thing to do is to put the widget into a group and set the group to behave like a background. This will ensure the navigation bar is automatically placed on new cards of the stack. This is how the navigation bar is used (in conjunction with the header bar widget) in the interactive tutorial app.

bmi app

Customising a navigation bar

Individual properties of each navigation item, and the order they are displayed, can be changed using the property inspector.

navbar pi editor

When one of the icons is clicked, a scrollable icon picker is popped up to allow you to choose a new icon. The current selection is highlighted as shown.

icon picker

The icon and highlighted icon can be different, to allow further visual feedback about what is currently selected. One way of using this is to turn the navigation bar as a single-selection option control, as might be used in a multiple choice quiz app.

navbar2

navbar3

navbar4

The colors of the navigation bar are controlled by the foreColor, backColor, borderColor, and hiliteColor properties as usual for LiveCode controls. You can even set the various pattern properties if you want, although we take no responsibility for the beauty or otherwise of the outcome.

navbarpattern

Scripting

Aside from responding to a change in the highlight using the hiliteChanged message, there is generally not very much that requires scripting when using the navigation bar. However, each of the various aspects of the navigation bar items’ display (icon, highlighted icon, label) can be set individually from script using the itemLabels, itemIcons and hilitedItemIcons properties. The values of these properties are just comma-delimited lists. It can be handy to write utility functions to set these if you are going to do so often, for example:


command setLabelAtIndex pLabel, pIndex
  local tLabels
  put the itemLabels of widget "navbar" into tLabels
  put pLabel into item pIndex of tLabels
  set the itemLabels of widget "navbar" to tLabels
end setLabelAtIndex

Alternatively, it is possible to set all the data of the navbar at once, using the itemArray property.


local tNavItems
put "Contacts" into tNavItems[1]["label"]
put "contacts" into tNavItems[1]["name"]
put "user" into tNavItems[1]["icon_name"]
put "user" into tNavItems[1]["hilited_icon_name"]
...
set the itemArray of widget "navbar" to tNavItems

If you can think of any interesting ways to use the navigation bar widget let me know in the comments!

Ali LloydLiveCode Widgets: The Navigation Bar

Related Posts

Take a look at these posts

10 comments

Join the conversation
  • James Nicholson plank - May 6, 2016 reply

    Congrats on the release of version 8
    I’ve contributed to 64 bit mac, and other projects.
    Everything looks brilliant
    All except the old debugger. And until this works with iOS and android, I can’t use this tool for making commercial products.
    I love the concept, but it’s too slow to debug mobile. It was very unfortunate that it didn’t get funded

  • Richmond Mathewson - May 7, 2016 reply

    To be honest, this seems the first widget that is comparatively straightforward, and I am extremely impressed.

    Richmond Mathewson - May 7, 2016 reply

    I wonder if it is possible to replace those flat icons with different ones of one’s own choice. I assume they are SVG images.

    Ali Lloyd - May 10, 2016 reply

    Yes, that would be a very nice enhancement for this widget actually- an itemIconPaths property which takes a line-delimited list of SVG paths.

  • Jim S - May 12, 2016 reply

    Re: on hiliteChanged command

    This is the first time I’ve seen this command. Is it specific to the Navigation Bar and not generic like a mouseUp command? I found no reference to it in the LiveCode Dictionary Script section but found it in the Navigation Bar section. Aside: is it possible to search all the dictionary if you don’t know in advance which section to look in?

  • Jim S - May 13, 2016 reply

    Re: on hiliteChanged command

    This is the first time I’ve seen this command. Is it specific to the Navigation Bar and not generic like a mouseUp command? I found no reference to it in the LiveCode Dictionary Script section but found it in the Navigation Bar section. Aside: is it possible to search all the dictionary if you didn’t know which in advance which section to search?

    Ali Lloyd - May 16, 2016 reply

    It is indeed a new message for widgets – it is also used by the segmented control. We thought it a general enough phenomenon to warrant a new message!

    It is not currently possible to search the whole dictionary, but it’s something we hope to look at soon.

  • Simon - May 15, 2016 reply

    Hi, this is very helpful but for some reason it doesn’t show on the iPhone Simulator (Version 9.3 (SimulatorApp-645.9 ). Any hint? Many thanks in advance

    Ali Lloyd - May 16, 2016 reply

    Hi Simon,
    You may not have the widget selected for inclusion in the standalone application. Have a look at this lesson for more info:
    http://lessons.livecode.com/m/33498/l/535490-how-to-include-a-widget-in-standalone-app

  • Hiba - August 24, 2017 reply

    About the position of each icon, I didn’t know How to put them in other position I mean they are always behind each other but I want them to cover all the page like a menu. So How ?

Join the conversation

*