Introduction

LG QCircle Design Template Overview

In order to develop an application for LG QuickCircle, you have to use the LG QCircle SDK. The LG QCircle SDK provides the broadcast intents and QuickCircle position information, but it does not provide the circle layout to display on QuickCircle. Therefore, the developer should design a circle layout and display the layout based on the position information of QuickCircle per model.

The official release site is http://developer.lge.com .

The LG QCircle SDK makes development easy, but whenever you build an application, there are simple repetitive tasks to complete, such as designing circle layout, receiving the broadcast intents to verify opening and closing of QuickCircle case, and back button operation processing.

The LG QCircle design template library provides the layout designs and basic UI elements through API, enabling developers to save time designing and using repetitive tasks. The LG QCircle design template library provides various circle layouts and receives QuickCircle broadcast intents, adjusts layout position, and handles back button operation.

What are the features?

The LG QCircle design template provides a library file. In this library, the following features can be used:

• Applying various circle layouts on application for QuickCircle
• Automatically displaying layouts on QuickCircle's position per model
• Receiving and processing QuickCircle broadcast intent

What kind of templates does the library support?

The LG QCircle design template provides 5 circle layouts as follows: (The title bar and the back button can be added according to developer's choices.)

1. Empty content This provides an empty circle space. Any View can be added to this area. However, even though the visible part is a circle, the actual content is a squared figure, so the Views on the four corners can be invisible. To avoid this, place important content away from the four corners when adding a View to the content area.

2. Content with a horizontal sidebar This is a circle space with a sidebar on the left. The width of this sidebar can be adjusted. Any View can be added to both sides of the sidebar and the content area. The sidebar and the content area is simply meant to divide the space, the actual space for content is not important. As with the Empty content, avoid putting important content on the four corners of the square.

3. Content with a vertical sidebar This is a circle space with a sidebar on the upper part. The height of this sidebar can be adjusted. Any View can be added to both sides of the sidebar and the content area. The sidebar and the content area is simply meant to divide the space, the actual space for content is not important. As with the Empty content, avoid putting important content on the four corners of the square.

4. Content with two top bars This is a circle space with two top bars divided in half equally. The height of this sidebar can be adjusted, but the width for two spaces cannot be changed. This layout consists of three spaces - two top bars and one content area. Any View can be added to each space. The sidebar and the content area is simply meant to divide the space, the actual space for content is not important. As with the Empty content, avoid putting important content on the four corners of the square.

5. Content with two sidebars This is a circle space with two sidebars on the left and right sides. The width of these sidebars cannot be adjusted. This layout consists of three spaces - two sidebars and one content area. Any View can be added to each space. However, because these sidebars are limited in size, they cannot show much content. As with the Empty content, avoid putting important content on the four corners of the square.

Usage

For a reference guide about the LG QCircle design template library, see the API reference guide included in the design template compressed file. When an error occurred while using the LG QCircle design template library, a ‘warning’ appears on the Android logcat, reference the log when application of the design templates does not work

Setting a Template

In order to make an application for QuickCircle with the LG QCircle design template, you have to set the circle layout. You have to use an instance from QCircleTemplate class included in the library in order to use LG QCircle design template in the application. This section describes the basic guide for QCircleTemplate class along with the codes.

Setting a layout

You have to create a QCircleTemplate instance in order to apply the circle layout provided by LG QCircle design template to the application. Select which circle layout to use while creating the QCircleTemplate instance. The circle layout of QCircleTemplate cannot be changed once it has been created.

Following code is for applying the content with a horizontal sidebar circle layout.

QCircleTemplate template = new QCircleTemplate(
                                           this, 
                                           TemplateType.CIRCLE_HORIZONTAL
                                 );

The first parameter is for the Activity to apply this layout, and the second parameter refers to the content with a horizontal sidebar. When no second parameter is input, QCircleTemplate basically applies an Empty content circle layout. Usable layout is defined in the TemplateType class. The following table shows the layouts for constants for each type.

In order to show the circular layout, use setContentView() in Android Activity. QCircle template library has an API, getView(), which returns the View of the created template. The following codes will set the view in your Activity.

setContentView(Template.getView());

You can see the initial circular layout you set when you execute the above code line.

There is no title bar or a back button in the initial circle layout. These two elements should be added to each layout, if necessary. The following section explains how to add a title bar or a back button.

Adding a title bar

Once it adds a title bar to the circle layout, the title appears at the top of QuickCircle. A title bar consists of a TextView with a transparent background.

To add a title bar, use the following code.

QCircleTitle mTitle = new QCircleTitle("My Title");

The first parameter is the text which appears as the title bar, the second parameter is a ratio of title bar's height. The ratio of title bar height refers to the ratio between the occupied height by the title bar and the entire height of QuickCircle. If this value is not entered, then the default value of 20% is used (LG QCircle UI/UX guide presents this value).

The title bar added to the content layout with a horizontal sidebar is as follows: [picture]

The height of the left sidebar and the height of the main content window are adjusted automatically to avoid overlapping with the title bar. Since the background of the title bar is transparent, the background picture is displayed below the title bar, as well when any background color or picture is applied for the entire QuickCircle.

When you want to use a complex layout that includes an image, etc. instead of a text on the title bar, create a XML layout file or generate a layout with Java code and apply it to the title. The following code is for applying a XML layout file to the title.

View titleView = (View) getLayoutInflater().inflate(R.layout.titlebar, null); 
template.setTitle(titleView, 0.3f);

Adding a back button

When a back button is added to the circle layout, it appears at the bottom of QuickCircle. The back button consists of a single button and the background is light gray. The back button's height is fixed at 20% of QuickCircle's height. If you tap this back button, it shuts down the current Activity.

When you create a QCircleTemplate instance, the back button only works after the current Activity is handed over as a Context.

To add a back button, use the following code:

QCircleBackbutton mBackbutton = new QCircleBackbutton(this);

The added back button to the content layout with a horizontal sidebar is as follows: [picture]

The added title bar and a back button to the content layout with a horizontal sidebar are as follows: [picture]

The height of the left sidebar and the height of the main content window are adjusted automatically to avoid overlapping with the title bar.

The back button cannot be adjusted by developers. When you need to modify it, you should use a back button that you have created, instead of the button provided in QCircle design template.

However, you can make the background of the back button transparent to apply the QuickCircle's background. The way to do this is described in the section Customizing layout.

Using the Template

There is a content area and a sidebar on a circle layout provided in the QCircle design template. Each of them can be freely decorated by developers. This section explains how to add content to the content area or sidebars on the layout.

Customizing layout

1. Adjusting the size of sidebar There is a content area and a sidebar on the circle layout. Each space can be modified according to the developer’s preference.

QCircle design template provides the API that controls the space ratio between the sidebar and the content area when using content layouts with a horizontal sidebar, a vertical sidebar, and two top bars. The following code sets the sidebar size to 50% of the entire circle content window.

template.setSidebarRatio(0.5f);

The first parameter is the sidebar ratio. This ratio does not relate to the entire QuickCircle, but rather to the total circle content window. That is, if there is an area occupied by a title bar or a back button, this ratio excludes those areas.

If you use the content with a horizontal sidebar, the ratio is about the width of the sidebar and if you use either the content with a vertical sidebar or the content with two top bars, then the ratio is about the height of the sidebar.

The above method references the properties of circle layout when called. Therefore, the sidebar space ratio will not change by adding a title bar or a back button after the above method is called. If you want to change the sidebar ratio according to the rest of circle content area after you add a title bar or a back button, call the above method again.

1. Setting the UI properties per area The content area and the sidebar belong to the RelativeLayout. QCircleTemplate provides the API that returns RelativeLayout in order for developers to modify each area for themselves.

The following code imports theRelativeLayout for the main content area.

RelativeLayout main = template.getLayoutById(TemplateTag.CONTENT_MAIN); 

The first parameter refers to an ID that assigns the area of the circle layout. The IDs for each area are saved in the TemplateTag class. Provided constants for area IDs are as follows:

Because this layout includes the content area and the sidebar, you must be careful not to twist the layouts of existing child Views when adding other layouts to this layout. TemplateTag.CONTENT_MAIN | The main content window. It is the same as the content window in the Empty content. TemplateTag.CONTENT_SIDE_1 | The first sidebar. It has no significance when there is no sidebar in the layout. TemplateTag.CONTENT_SIDE_2 | The second sidebar. It has no significance when there are less than two sidebars in the layout.

You can find out where each area is placed in each circle layout in the section What kind of templates does the library support?

You can change the properties of the imported RelativeLayout using Android API. The following code changes the background color of the main content.

main.setBackgroundColor(Color.BLUE);

Like the content with two sidebars, there is a layout that does not provide API to control the sidebar's size on the QCircleTemplate. In this case, you can adjust the size using the Android API. The following code changes the width of the first sidebar in the content layout with two sidebars.

RelativeLayout side1 = template.getLayoutById(TemplateTag.CONTENT_SIDE_1);
LayoutParams params = side1.getLayoutParams();
params.width = 400;
side1.setLayoutParams(params);

Caution You must be careful when changing layout parameters of each area using the Android API. The layout can be twisted when changed by developers because the circle layout that LG QCircle design template provides configures the layout parameters in order for each area to be positioned properly.

1. Setting the entire background You can specify the background for each area by using the method described above. However, even if you use TemplateTag.CONTENT, it does not affect the title bar or the back button's area. If you want to set a background for the entire QuickCircle including the title bar and the back button, use the following code:

// set background color
template.setBackgroundColor(Color.BLACK, true);

// set background image
Drawable mypic = getResources().getDrawable(R.drawable.beanbird);
template.setBackgroundDrawable(mypic, true);

The first parameter refers to the color or image source to be applied to the background, the second parameter refers to a flag to make the back button background transparent. The title bar area is set to be transparent by default. If you specified a custom title using the setTitle(View view, Context context), then the title's background should be set to be transparent to apply the above code.

The following image shows the content layout with a horizontal sidebar that applied the entire background image. To display the sidebar's position, it paints a translucent color on the sidebar. [picture]

Adding content

The information provided by the application should be output on the content area or the sidebar of the circle layout. As mentioned previously, you can add the Android UI component freely to this layout because the content area and the sidebar are the RelativeLayout. For example, you can add a TextView to the content area or add an ImageView to the sidebar. You can also add a complex layout that has both a TextView and an ImageView. Similar to the previous description, add the desired UI component using the Android API after retrieving the RelativeLayout for each area.

The following code is to add the layout generated with the layout XML to the content area and to add the image to the sidebar.

// main content
View myContent = (View) getLayoutInflater().inflate(R.layout.activity_main, null);
RelativeLayout main = template.getLayoutById(TemplateTag.CONTENT_MAIN);
main.addView(myContent);

// sidebar
RelativeLayout side1 = template.getLayoutById(TemplateTag.CONTENT_SIDE_1);
side1.setBackgroundResource(R.drawable.sidebarimg);

The image below shows that a content layout with a horizontal sidebar which has an icon on the sidebar as well as the text and a button on the content area. [picture]

Others

Setting an Intent for full screen

The application for LG QuickCircle has to display a circle layout when the QuickCircle case is closed, and display a full screen layout when the case is open. LG QCircle design template enables running a specific Intent when the case is open. When this Intent is a general Android's Activity, it runs as full screen by default.

You can set which Intent to run by using the following code:

Intent intent = new Intent(this, FullActivity.class);
template.setFullscreenIntent(intent);

You should first select the Activity to run as full screen. In order to use a new Activity, first make the Activity in the application and then create an Intent that runs the Activity as shown above. QCircleTemplate does not care which Intent is set, it just runs it by using startActivity(). Therefore, the information and properties of Intent that you want to run should be set in your application.

Extra Tips

Adding a Custom Layout

LG QCircle design template provides 5 circle layouts by default. Besides these, users can add custom layouts to the template. In order to add custom layouts, the following are required:

• Layout XML file
• The resource files used on the layout (such as image, text, animations, etc.)

Creating a custom layout

To make a layout XML file for LG QCircle design template, you must include the required UI component. A circle layout of LG QCircle design template consists of the following required items: [picture]

root, circlelayout, and content are the ID of each layout. root is a FrameLayout, and others are RelativeLayouts. content has the same height as the circlelayout when there is no title bar or back button. In the content, there can be a content area or a sidebar. If you use the getLayoutById(TemplateTag.CONTENT) from QCircleTemplate, you can obtain the total circle content area, in other words, content.

The custom layout must have the above layout structure. Each type and ID of layouts should also be the same as above. Also, if you overlap the image with a hole in the center to the squared circlelayout to make a circle, the image must be under root and have its ID assigned as 'circle'. Otherwise, the layout can be twisted because the overlapped image cannot be processed when the circle layout is moved according to the QuickCircle's position information of each model.

There is no specific rule for the layout or the UI component in content. However, when you need to get the content area or a sidebar in content using the getLayoutById(), you should make each layout as RelativeLayout. In addition, when you need to use the ID defined in the TemplateTag, the ID for the content area should be specified as ‘main’ and the ID for the sidebar should be specified as ‘side1’ or ‘side2’.

The following is the custom XML file with four parts:

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/root"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@android:color/background_dark" >

    <RelativeLayout
        android:id="@+id/circlelayout"
        android:layout_width="@dimen/square_size"
        android:layout_height="@dimen/square_size"
        android:layout_gravity="center_horizontal"
        android:background="@android:color/background_light"
        android:gravity="center_horizontal" >

        <!-- child #1: Title -->
        <!-- child #2: content -->
        <RelativeLayout
            android:id="@+id/content"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:layout_centerHorizontal="true"
            android:gravity="center_vertical"
            android:padding="@dimen/margin" >

            <LinearLayout
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                android:orientation="horizontal"
                >
                <LinearLayout
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                android:orientation="vertical"
                android:layout_weight="1"
                >
                <RelativeLayout
                    android:id="@+id/main"
                    android:layout_width="match_parent"
                    android:layout_height="match_parent"
                    android:gravity="center_vertical"
                    android:layout_weight="1"        
                   >
                </RelativeLayout>
                <RelativeLayout
                    android:id="@+id/side1"
                    android:layout_width="match_parent"
                    android:layout_height="match_parent"
                    android:gravity="center_vertical"
                    android:layout_weight="1" 
                    >
                </RelativeLayout>
            </LinearLayout>
            <LinearLayout
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                android:orientation="vertical"
                android:layout_weight="1"
                >
                <RelativeLayout
                    android:id="@+id/side2"
                    android:layout_width="match_parent"
                    android:layout_height="match_parent"
                    android:gravity="center_vertical"
                    android:layout_weight="1"
                   >
                </RelativeLayout>
                <RelativeLayout
                    android:id="@+id/side3"
                    android:layout_width="match_parent"
                    android:layout_height="match_parent"
                    android:gravity="center_vertical"
                    android:layout_weight="1"
                   >
                </RelativeLayout>
            </LinearLayout>
            </LinearLayout>
        </RelativeLayout>

        <!--  child #3: Button -->
    </RelativeLayout>

    <View
        android:id="@+id/circle"
        android:layout_width="@dimen/square_size"
        android:layout_height="@dimen/square_size"
        android:layout_gravity="center_horizontal"
        android:background="@drawable/circlebackground" />

</FrameLayout>

Using a custom layout in applications

In order to apply a custom layout to the application, you must include the created XML layout file and other resource files in the res directory in the application.

Use the following code to apply the created layout to the QCircleTemplate.

QCircleTemplate template = new QCircleTemplate(
                                           this, 
                                           R.layout.circle_custom
                                 );

There are four areas in this layout, each area's IDs are main, side1, side2, and side3.
main, side1, and side2 are the defined value in the TemplateTag, so you can use the method explained in the previous chapter. However, because the side3 is the newly added ID, it cannot be used in the TemplateTag and you should get the layout by its ID.

The following code adds text lines in four areas:

RelativeLayout main = template.getLayoutById(TemplateTag.CONTENT_MAIN);
TextView text1 = new TextView(this); 
text1.setText("main");
main.addView(text1);

RelativeLayout side1 = 
                template.getLayoutById(TemplateTag.CONTENT_SIDE_1);
TextView text2 = new TextView(this); 
text2.setText("side1");
side1.addView(text2);

RelativeLayout side2 = 
                template.getLayoutById(TemplateTag.CONTENT_SIDE_2);
TextView text3 = new TextView(this); 
text3.setText("side2");
side2.addView(text3);

RelativeLayout side3 = template.getLayoutById(R.id.side3);
TextView text4 = new TextView(this); 
text4.setText("side3");
side3.addView(text4);

As shown above, the ID, side3 that is not supported in the TemplateTag is input in the getLayoutById() directly.

The image when the custom layout is actually applied is as follows: To distinguish four areas, different colors are used on each area, and the size and position of the text are adjusted. [picture]