Header Bar Widget

The header bar widget can be used to allow the user to navigate around your app and take actions, providing a visual structure to your app. The widget emulates the iOS navigation bar and the Android app bar. If you are working on Mac a header bar widget will be themed like an iOS navigation bar, if you are working on Windows or Linux it will be themed like an Android app bar.

Windows / Linux / Android

Windows header

Mac / iOS

Mac header

For example in the iOS Clock app the header bar allows the user to choose to edit or add an alarm by navigating to another screen within the Alarm section of the app.

Clock app header

As well as navigating around the app the header bar can also be used to provide access to options such as search, save and delete.

Creating a Header Bar

A header bar widget can be created by dragging it out from the Tools Palette, where it appears with the following icon:

Alternatively it can be created in script using:

create widget as "com.livecode.widget.headerbar"

Using the Header Bar

The header bar gets a mouseUp message when it is clicked on, you handle this message to take the appropriate action for the chosen action.

The default mouseUp handler of the header bar is

on mouseUp
   local tActionName
   put the mouseAction of me into tActionName

   if tActionName is not empty then
      -- Execute script triggered by the given action
   end if
end mouseUp

Firstly we get the value of the mouseAction property, which gives us the name of the header action that was just clicked, allowing us to do something different depending of what action was clicked. For example

on mouseUp
   local tActionName
   put the mouseAction of me into tActionName

   if tActionName is "back" then
      go to card "messageList"
   else if tAction is "add" then
      go to card "newMessage"
   end if
end mouseUp

Note: it is import to remember that the mouseAction property gives you the action name, not the label. Both can be set in the Property Inspector.

Property Inspector 1

The label is the text that is displayed for an action, when the Action display style is set to “text”. The name is the name of the action, as returned by the mouseAction property.

Customising the Header Bar

The actions displayed in the header bar, and the appearance of the header bar itself, can be controlled using the Property Inspector.

The header bar can:

The Property Inspector also allows you to set up all the actions that are shown on the header bar, setting the label, icon and highlight icon for each action and allowing you to reorder, add and delete actions.

Property Inspector 2

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.

The colors of the navigation bar are controlled by the foregroundColor, backgroundColor, borderColor, and hiliteColor properties as usual for LiveCode controls. Changing these properties allows you to customise the header bar to fit in with the design of your app.

## Examples

Messages Header

Messages app header Android Messages app header iOS

Notes Header

Notes app header Android Notes app header iOS

Scripting

Beyond handling the mouseUp message and using the mouseAction property to act on the selected action the other thing you might want to do with your header is to update it depending on the state of the app. For example if you choose to edit an item in a list the header options might change to “cancel” and “save”, or similar. You can change the header actions in script by setting the itemLabels, itemNames, itemIcons or hilitedItemIcons properties of the header bar widget. The values of these properties are comma-delimited lists and can be updated using chunk expressions.

This example shows how to switch a header bar action between “edit” and “done”

Header bar edit Header bar done

on mouseUp
    local tActionName, tActionNames, tActionLabels
    put the mouseAction of me into tActionName 
    put the itemNames of me into tActionNames 
    put the itemLabels of me into tActionLabels 

    if tActionName is "edit" then 
        put "done" into item 2 of tActionNames 
        put "Done" into item 2 of tActionLabels 
        set the itemNames of me to tActionNames 
        set the itemLabels of me to tActionLabels 
    else if tActionName is "done" then 
        put "edit" into item 2 of tActionNames 
        put "Edit" into item 2 of tActionLabels 
        set the itemNames of me to tActionNames 
        set the itemLabels of me to tActionLabels 
    end if 
end mouseUp

Switching Theme

Setting the theme of the header bar to "Android" or "iOS" will temporarily display it using the metrics of the chosen platform. This property is transient - it is not saved with the stack as it uses the appropriate mobile theme for the platform is is running on.