Sidebar API

Sidebar API has been deprecated since Sygic Truck version 24.3.0

Introduction

With this feature you can share your information or provide a dedicated user interaction on the navigation screen through the sidebar display component.
Thus you can avoid switching between applications or you can avoid developing a split screen application.
The sidebar is located on the right side of the navigation screen, taking about 25% of the screen width and is available only in landscape screen orientation.
It is possible to interact with the sidebar via API on the go.

You can check the API reference manual for sidebar.

Sidebar concept

The sidebar can consist of four equally sized widgets, or a combination of widgets, where one or two widgets have double size. There are four available layouts.

Your application can control the widgets in navigation via SidebarAPI.jar library, which contains the set of Sidebar-related classes. The Sidebar library delivers the function calls to Sygic Navigation via AIDL and receives callbacks in the opposite direction. All your application needs to do is to setup the sidebar and register callback listeners. The widgets support user clicks and other actions and your app will get callbacks to handle them. Your application sets data updates that are displayed in the widget. The widget shows the data till it is replaced by another data. If you switch on widgets without filling them with data, they will appear blank.

The following picture shows the example of the layout type 3, where three widgets are applied in the sidebar suitable for a field work.
The first widget is the navigation widget, which is always displayed in two positions/slots. The second widget is the text widget possibly showing a job description. The third widget is the two buttons configuration for two click actions to be defined.

Requirements and Limitations

The sidebar is available in the landscape mode only and it is recommended to use it only with larger screen displays, 7" or more. The minimum resolution of the screen has to be 800x480.
The physical widget size on 7" tablet screen will be 38x21mm for a single sized widget and 38x42mm for a double sized widget. The pixel resolution of a widget on a screen with 800x480 pixels will be 213x120px for a single sized widget and 213x240px for a double sized widget. On larger screens the widgets will scale up accordingly in terms of physical size or pixel resolution.
To be able to use the sidebar functionality, you have to obtain a licence API key from us. The license key opens the access to the sidebar API.
Alternatively you can use the free trial API key ("0000000000000000"), which works in a combination with the navigation in a trial mode.

Try demo

The library with examples and navigation is provided in a standalone package release (SidebarAPI_Android_xxx.zip)
In order to obtain the package and a trial code please Contact our sales.
The package contains the following examples:

SidebarTuto - example demonstarting a basic use of sidebar integration
SidebarDemoJD - example mimicking a simple solution for a job dispatch function

For trying the Sidebar functionality with the provided examples you need the following steps:

install the Sygic truck navigation (the folder Navigation/Sygic3D)
activate it with the trial activation code provided to you (please check with your sales contact)
compile and install any of the examples (folder SidebarAPI/Examples)
run the example

Library overview

The library contains the following important classes shown in their full package path:

class	description
com.sygic.sidebar.Sidebar	the basic class
com.sygic.sidebar.SidebarConnection	the class handling the connection of sidebar to navigation
com.sygic.sidebar.SidebarConnection.SidebarConnectionListener	the interface for the connection callbacks
com.sygic.sidebar.widgets.Widget	the base class of sidebar widgets, which is extended to other classes
com.sygic.sidebar.widgets.TextWidget	class for text widget
com.sygic.sidebar.widgets.ButtonWidget	class for button widget
com.sygic.sidebar.widgets.ImageWidget	class for image widget
com.sygic.sidebar.widgets.NavigationWidget	class for showing the navigation instructions in sidebar
com.sygic.sidebar.widgets.OnSidebarActionListener	the interface for the callbacks providing user interactions on widgets

The details can be found in Sidebar Reference Manual

Getting started

In this tutorial section we will show a simple application, which will:

open up a connection to the sidebar
configure the sidebar with some widgets
set up the callback for user interaction
demonstrate text widget data updates
demonstrate button click interaction
demonstrate navigation control button operation modes
demonstrate image control

1. Opening connection

First it is necessary to open the connection through the SidebarConnection connect function. This function itself does not start the navigation. It must be running prior the call. Possibly you can start navigation through the use of the Sygic SDK. When the navigation is started, you have to select, which version of navigation you are trying to connect. It can be one of Truck, Taxi or Fleet. The initialization of the Sidebar is asynchronous, so it is necessary to create the listener for the events "connected" and "disconnected". As the result of the sucessfull connection you will get the reference to a valid sidebar object inside the onSidebarConnected callback.

Example

private Sidebar mSidebar = null;
...
SidebarConnection.getInstance().connect(getApplicationContext(), NaviType.Truck, "0000000000000000", new SidebarConnectionListener() {

    @Override
    public void onSidebarConnected(ConnectionResult result, Sidebar sidebar) {
        if(result.isConnected()) {
            mSidebar = sidebar;
        }
        else {
            Log.v("Sidebar", "connection error");
        }
    }

    @Override
    public void onSidebarDisconnected() {
        Log.v("Sidebar", "disconnected");
    }
});

Please note the above example connects Sidebar to the Sygic Truck Navigation application (NaviType.Truck) and the API license key is 0000000000000000.

2. Configuring sidebar

The sidebar needs to be populated with widgets. You have to create your widgets and then fill them into the sidebar. You can create multiple widgets and switch between them.

Example

private TextWidget mTextarea;
private ButtonWidget mButtons;
private NavigationWidget mNavi;
...
mTextWidget = new TextWidget("Message");
mTextWidget.setText("Lorem ipsum");
mButtonWidget = new ButtonWidget("buttons");
mButtonWidget.setCount(2);
mButtonWidget.setText(ButtonWidget.BUTTON_1, "Accept");
mButtonWidget.setText(ButtonWidget.BUTTON_2, "Reject");
mNaviWidget = new NavigationWidget("navi");

mSidebar.setWidget(Sidebar.WIDGET1, mNaviWidget);
mSidebar.setWidget(Sidebar.WIDGET3, mTextWidget);
mSidebar.setWidget(Sidebar.WIDGET4, mButtonWidget);

mSidebar.show(true);

The above example instantiates 3 widgets, inserts them into selected positions, and finally switches on the visualization in navigation.
Please note that the navigation widget occupies two positions, so setting it to the WIDGET1 position takes automatically positions WIDGET1 and WIDGET2.
Also please note that a state of the navigation sidebar is kept across multiple calls of an external application as long as the navigation keeps running.
Setting a widget to an already occupied position leads to an error. Therefore it is often the best to start application with cleaning of the sidebar as follows:

mSidebar.setWidget(Sidebar.WIDGET1, null);
mSidebar.setWidget(Sidebar.WIDGET2, null);
mSidebar.setWidget(Sidebar.WIDGET3, null);
mSidebar.setWidget(Sidebar.WIDGET4, null);

3. Defining callbacks

Most of the widgets provide callbacks, through which you can handle the user interactions.
The callback is defined through using the setOnSidebarActionListener method on widgets.
The most obvious is the callback attached to buttons of the Button widget.
Here the onSidebarAction method returns the action parameter, which can be checked to identify the button being clicked (in the case of button widgets).

Example

mButtons.setOnSidebarActionListener(new OnSidebarActionListener() {

    @Override
    public void onSidebarAction(Widget widget, int action, Bundle extras) {
        if(action == ButtonWidget.EVENT_BUTTON_1_CLICKED) {
            // perform action 1
        }
        else {
            // perform action 2
        }
    }
});

The callback mechanism (using setOnSidebarActionListener) is available with the following widgets: ButtonWidget, TextWidget, ImageWidget. It is not available with NavigationWidget.

4. Add text widgets

The widget supports a simple HTML style formatting of text and multilining. You can use following formatting tags:

tag	description
	creates a new line
	vertical space where x defines number of points
	space
	font size, can be even number between 10 and 34
	the type can be normal, bold, italic or special.
	color defined by RGB

The font tags can be combined into one. It is not necessary to use . The tags cannot be nested. The last tag overrides all the preceding.
The special font type selects characters from special.ttf font file, which can be found in the resource directory of the navigation and contains various pictograms.

Examples

mTextWidget.setText("New job for you, Dude ! Pick up Viktor at the airport");
mTextWidget.setText("<font size=\"15\" type=\"bold\" color=\"#ff0000\">New job for you, Dude !<br><nbsp><font size=\"18\" type=\"normal\" color=\"#ffff00\">Pick up Viktor at the airport!";);

5. Add button widgets

This widget shows a number of buttons (currently 1 or 2) with a defined formatting and provides callback on clicking.
The available methods are:

method	description
setCount(int count)	defines whether 1 or 2 buttons are displayed in the widget
setText(int buttonID, string text)	defines the caption of the given button
setBgColor(int buttonID, Color bgColor)	defines the color of the given button
setTextColor(int buttonID, Color textColor)	defines the font color of the given button
setFont(int buttonID, int font)	defines the font of the given button, where 0 is normal and 1 is special
setOnSidebarActionListener(...)	defines the callback method trigger with click action

The Color can be set from a predefined set of colors like RED, ORANGE, GREEN, BACKGROUND, WHITE, BLACK. Or it can be defined through the RGB scheme with the function rgb(..).

Example

<mButtonWidget.setCount(2);

mButtonWidget.setText(ButtonWidget.BUTTON_1, "Accept");
mButtonWidget.setBgColor(ButtonWidget.BUTTON_1, Color.rgb(0,255,0));
mButtonWidget.setTextColor(ButtonWidget.BUTTON_1, Color.BLACK);

mButtonWidget.setText(ButtonWidget.BUTTON_2, "Reject");
mButtonWidget.setFont(ButtonWidget.BUTTON_2, 1);

6. Add image widgets

The widget supports displaying a single PNG bitmap. The bitmap is not scaled. Again you can attached the click listener on the widget.

Example

mImageWidget.setPath(Environment.getExternalStorageDirectory() + "/PetrolStation.jpg");

7. Add navigation widget

Using this widget in sidebar rearranges the application layout. If the navigation widget is used inside the sidebar the driving instructions panel disappears from the screen bottom, which provides more space for a map view. This is useful, if you don't need to show many items in the sidebar, but you would like to provide more space on the screen for navigation. If the navigation widget is not used inside the sidebar the driving instructions panel retains at the screen bottom as default. The layout with using the navigation widget versus without using is shown here:

Full sample reference

<pre class="code-yellow">package com.sygic.sidebargetstarted;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import com.sygic.sidebar.Sidebar;
import com.sygic.sidebar.Sidebar.NaviType;
import com.sygic.sidebar.SidebarConnection;
import com.sygic.sidebar.SidebarConnection.ConnectionResult;
import com.sygic.sidebar.SidebarConnection.SidebarConnectionListener;
import com.sygic.sidebar.widgets.*;
import com.sygic.sidebardemo.R;
import android.net.Uri;

public class MainActivity extends Activity {

    private Sidebar mSidebar = null;
    private TextWidget mTextWidget;
    private ButtonWidget mButtonWidget;
    private NavigationWidget mNaviWidget;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        initScreen();

        SidebarConnection.getInstance().connect(getApplicationContext(), NaviType.Truck, "0000000000000000", new SidebarConnectionListener() {

            @Override
            public void onSidebarConnected(ConnectionResult result, Sidebar sidebar) {
                if(result.isConnected()) {
                    mSidebar = sidebar;
                    InitSidebar();
                }
                else {
                    Log.v("Sidebar", "connection error");
                }
            }

            @Override
            public void onSidebarDisconnected() {
                Log.v("Sidebar", "disconnected");
            }
        });
    }

    @Override
    protected void onDestroy() {
        SidebarConnection.getInstance().disconnect();
        super.onDestroy();
    }

    private void InitSidebar()
    {
        mSidebar.setWidget(Sidebar.WIDGET1, null);
        mSidebar.setWidget(Sidebar.WIDGET2, null);
        mSidebar.setWidget(Sidebar.WIDGET3, null);
        mSidebar.setWidget(Sidebar.WIDGET4, null);

        mTextWidget = new TextWidget("text");
        mTextWidget.setText("Lorem ipsum");
        mButtonWidget = new ButtonWidget("buttons");
        mButtonWidget.setCount(2);
        mButtonWidget.setText(ButtonWidget.BUTTON_1, "Accept");
        mButtonWidget.setBgColor(ButtonWidget.BUTTON_1, Color.rgb((byte)0,(byte)255,(byte)0));
        mButtonWidget.setTextColor(ButtonWidget.BUTTON_1, Color.BLACK);
        mButtonWidget.setText(ButtonWidget.BUTTON_2, "Reject");
        mButtonWidget.setFont(ButtonWidget.BUTTON_2, 1);
        mNaviWidget = new NavigationWidget("navi");
        mSidebar.setWidget(Sidebar.WIDGET1, mNaviWidget);
        mSidebar.setWidget(Sidebar.WIDGET3, mTextWidget);
        mSidebar.setWidget(Sidebar.WIDGET4, mButtonWidget);

        mSidebar.show(true);

        mButtonWidget.setOnSidebarActionListener(new OnSidebarActionListener() {

            @Override
            public void onSidebarAction(Widget widget, int action, Bundle extras) {
                if(action == ButtonWidget.EVENT_BUTTON_1_CLICKED) {
                    mTextWidget.setText("you clicked Accept, thank you");
                    mSidebar.updateWidget(mTextWidget);
                }
                else {
                    mTextWidget.setText("you clicked Reject, we are sorry");
                    mSidebar.updateWidget(mTextWidget);
                }
            }
        });
    }

    private void initScreen() {
        setContentView(R.layout.activity_main);
        ((Button)findViewById(R.id.btnSendTask)).setOnClickListener(new View.OnClickListener() {

            @Override
            public void onClick(View v) {
                String msg = "<font size=\"15\" type=\"bold\" color=\"#ff0000\">New job for you, Dude !<br><nbsp><font size=\"18\" type=\"normal\" color=\"#ffff00\">Pick up Viktor at the airport!";
                mTextWidget.setText(msg);
                mSidebar.updateWidget(mTextWidget);
                String str = "com.sygic.aura://";
                Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(str));
                startActivity(intent);
            }
        });
    }

}

Previous article: Online API
Next article: Hud API