Creating Your First Tizen .NET Application
PUBLISHED
The Tizen .NET framework allows you to efficiently and easily create beautiful applications for Tizen. A great way to experience this yourself is to follow the steps to your first Tizen .NET application. If you have to set up your development environmnet, please go to set up the development environment.
To get started,
After completing the above steps, you will have created your first application. You can go to Enhancing your application.
Creating a Project
To build a Tizen .NET application, you must follow these general steps:
- Create a project.
- Design the user interface for the application.
- Write code to implement the logic of the application.
- Build and deploy the application.
You can perform all of these steps in the IDE. The Tizen .NET preview works in Microsoft's Visual Studio (2015). After making sure the development environment is properly set up, you can create a new Tizen .NET project:
- Launch Visual Studio.
- To create a new project, select File > New > Project.
- In the New Project window, select Tizen in the Templates tree on the left, and select Blank App (Tizen Xamarin.Forms Portable). Visual Studio defines a name, location and solution name for you, but you can modify the values: at least set the name to something meaningful.
Once you are happy with the name and location, click OK. A solution with 2 projects is created:
- One project is named <projectname> (Portable) and contains the Xamarin.Forms code, which can be shared across platforms.
- Another project is named <projectname>.Tizen and contains the code to instantiate your application within the Tizen framework.
If you are already familiar with Xamarin.Forms, this is the exact same structure as a Xamarin.Forms portable application, with the "Portable" project being the portable class library and the others being the platform-specific projects; however, for the Tizen .NET preview, only the Tizen platform-specific project is generated.
The .cs
file in the portable project already contains simple Xamarin.Forms code, which makes a basic UI. Therefore, you can now build and run your application.
When you are done running your first application, you can enhance it further by reading a brief overview of what the code generated by the template is doing, and learning about a few more concepts to add to your application appeal.
Building and Running Your Application
When you have created your first project, you can build and run it:
- Register an author certificate.
- Build the solution.
- Deploy the application to a target.
- Run the application.
1 Registering an Author Certificate
If you already registered a certificate in Visual Studio, you can skip this step.
After installing the Visual Studio plugin, and before the first build, it is useful to set up a signing certificate. If the certificate is not in place and known to Visual Studio, the last step of the build (the creation of the Tizen .tpk
package) fails.
You have 2 options:
- Use an existing Tizen author certificate - if you have used Tizen Studio or Tizen SDK and already generated a certificate, the
.p12
file can be copied over to your Windows development machine and registered. - Use the
author_test.p12
test certificate. This certificate is fine for experimentation, though you cannot use it in production. The test certificate is the default on installation, so it does not need to be registered. However, in the preview, there is a bug where occasionally this certificate does not work first time; if a signing error occurs during the build process, come back to the registration section below, navigate to the test certificate, and click OK to register it. The password is author_test.
To register a certificate in Visual Studio, go to the Tools > Options menu, scroll down, and open the Tizen > Certification section. Locate the author key file, enter its password, and click OK. The following figure shows the test certificate filled in. Only set up the author certificate, do not change the distributor certificate.
Figure: Author certificate registration
2 Building the Solution
To build the solution, go to Build > Build Solution in the main Visual Studio menu (you can also right-click the solution title in the Solution Explorer window and select Build). If the build process works all the way through to the end, the final part of the build output window shows something similar to the following figure - indicating that a .tpk
package was built.
Figure: Building process output
Tizen .NET applications are always deployed as installed packages. The package files take the suffix .tpk
, and the package generation is controlled by the manifest file. The Visual Studio template generates a package manifest, which is named tizen-manifest.xml
and placed at the top level of the .Tizen project. The default manifest is sufficient to build these example applications without modification. If you need to make any changes, such as changing the icon displayed when the application is installed (it defaults to the Tizen logo), or installing resources that are used by the application at runtime, see Packaging Your Tizen .NET Application for more information.
3 Deploying the Application
To run the application, you must first deploy it to the target: either a device or an emulator. Deploying means transfering the .tpk
(package file) to the target and invoking the Tizen package manager to install it; this usually happens in a single command.
To deploy, attached a target:
- The target can be a development device (connected to a USB port), or the Tizen emulator. Launch the emulator from the Visual Studio menu by going to Tools > Tizen > Run Emulator.
- The emulator launches after a small delay. When it is up and running, the display inside Visual Studio changes a bit, and the green debug button updates to show the running emulator.
Communication with the device happens through the SDB program (Smart Development Bridge). Visual Studio uses this program behind the scenes, so you normally do not have to use it directly, but in case there are problems, you can run the SDB manually to check that it actually finds the device. To check:
- On Linux with Tizen Studio installed, navigate to
$HOME/tizen-studio/tools
(on Linux with the earlier Tizen SDK installed, navigate to$HOME/tizen-sdk/tools.
), and typesdb devices
. - On Windows® with the Tizen Visual Studio tools installed, open a command shell (type
cmd
in the search box to do this easily), and navigate to theTools
directory and type:sdb devices
.For Windows®, you can check the
Tools
location from the same menu as shown in the earlier section about setting the certificate - just go to Tools instead of Certification. The path is usuallyC:\Program Files (x86)\Tizen\Tools
.
The following figure shows an example of a successful emulator detection.
Figure: Emulator detection
For the Tizen .NET preview, the detection is partially automated: you cannot yet click the deploy checkbox in the Visual Studio configuration manager or select Deploy from the various menus. However, if you click the Debug button (or select it from the menus), the package is deployed if it has changed since the last deployment, which is pretty much the same thing. For the initial simple example, where you are not expected to need to debug anything, go to the Debug menu and select Start Without Debugging.
4 Running the Application
After the deployment, you can launch the application. If the deployment was successful, the application icon is visible on the device screen. Click it to launch the application. The following figure shows the launched application (as seen on the emulator).
Figure: Application running
If the deployment had problems, try to use the SDB to install the applicaton:
$ sdb install <path-to-package>/XamarinApplication1.Tizen.tpk
If the installation succeeds, the application shows up on the emulator or device screen, and you can click to launch it.
Enhancing Your Tizen .NET Application
The C# code from your first application displays a label centered on the screen, containing the Welcome to Xamarin Forms! text. The Hello application (created from the template) is set up and ready to be built and run by Visual Studio right after you create it, as shown in the preceding sections of this topic.
Xamarin.Forms provides a way to build portable applications which run in a native way: it provides a set of controls to help build a user interface, as well as generating code which adapts that user interface code to use the native facilities of the supported platforms. The following information just scratches the surface of these controls, enough to give you an idea of how to build on the initial application.
The following example shows the portable code portion of the Tizen Xamarin.Forms Portable project Xamarin-Application1.cs
file, generated by the template:
using System; using System.Collections.Generic; using System.Linq; using System.Text; using Xamarin.Forms; namespace XamarinApplication1 { public class App : Application { public App() { // Root page of your application MainPage = new ContentPage { Content = new StackLayout { VerticalOptions = LayoutOptions.Center, Children = { new Label { HorizontalTextAlignment = TextAlignment.Center, Text = "Welcome to Xamarin Forms!" } } } }; } protected override void OnStart() { // Handle when your app starts } protected override void OnSleep() { // Handle when your app sleeps } protected override void OnResume() { // Handle when your app resumes } } }
The Xamarin.Forms controls used to create the user interface of a Tizen .NET application can be roughly categorized into 4 groups:
- Pages represent screens within an application. The UI of an application is built from one or more pages and with a navigation mechanism, if needed. The navigation scheme is specified by the
INavigation
interface. Many pages are of theContentPage
type, which describes the view of a single screen. - Layouts are containers used to compose views into logical structures. Some available types are absolute, grid, relative, and stack layouts; each provide mechanisms, such as orientation, spacing, and padding, to control the layout. The
StackLayout
class is a basic layout where you just stack controls on top of one another (or side-by-side). Layouts can be bundled and nested in each other. - Views are the controls displayed on the user interface, such as labels, buttons, and text entry boxes.
- Cells are specialized elements used for items in tables and lists, which help describe how the items must be rendered.
You can read all about how Xamarin.Forms works at the Xamarin Developer Center. In addition, there is a comprehensive book about Xamarin.Forms from Microsoft Press, which is available as a free download. This topic does not duplicate the definitive documentation, only introduces the controls in use in the example above, and a bit more.
The Xamarin.Forms controls in play in this application:
- The
App
class is declared, deriving from the Application class, which is the Xamarin.Forms class that represents a cross-platform mobile application. - The
App
class constructor creates aContentPage
instance (line 14) where you set up the view to display. - You assign what you want to display to the
Content
property of that class.In this case, the content is a container, specifically a
StackLayout
instance (line 16). This is just a layout that positions its child elements in a single vertical (by default) or horizontal line - thus the name: the elements are "stacked" on top of one another. - You set up the child elements by adding to the
Children
property (line 19) - in this case just a singleLabel
instance (line 20), whoseText
property you set to the message you want to display. - Some lines (18 and 21) implement some control over the layout.
- Besides the
App
constructor, the rest of the file is just boilerplate - event handlers from theApplication
class that can be filled in if the application needs code to handle application state changes.
That is a very brief view without any real details; the Xamarin.Forms documentation goes into much more detail on each of the classes, interfaces, properties, and attributes involved and is a good place to do further research.
The code does not show the instantiation of the App
class. Since application launching is platform-specific, the launching part, including the instatiation of the App
class and the declaration of the Main()
method (required as the entry point of every C# program), happens in the .Tizen project, in the matching file there. For example, if the file you are looking at in the portable project is named XamarinApplication1.cs
, the platform-specific file is XamarinApplication1.Tizen.cs
in the .Tizen project. For an application like this one, which just uses Xamarin.Forms controls, the generated code at the .Tizen part of the project contains everything needed, and you do not need to make any modifications. The following example shows the content of the XamarinApplication1.Tizen.cs
file:
using System; namespace XamarinApplication1.Tizen { class Program : global::Xamarin.Forms.Platform.Tizen.FormsApplication { protected override void OnCreate() { base.OnCreate(); LoadApplication(new App()); } static void Main(string[] args) { var app = new Program(); global::Xamarin.Forms.Platform.Tizen.Forms.Init(app); app.Run(args); } } }
Defining a Button
The basic template uses a label, which displays text in an area of the screen. The properties inherited from the base classes of Label
give lots of control over the display: font attributes, families, and sizes as well as layout options. A button control is relatively similar, but is specifically designed to react to click events. As a result, the Button
class defines an event called Clicked
, which tells the application what to do when the click event takes place. To instantiate a generic button:
Button button = new Button { Text = "Click here!" }; button.Clicked += OnButtonClicked;
The above example adds the OnButtonClicked
method to the button's Clicked
event, and you need to define that method. When an event triggers, 2 parameters are delivered to any handler set up to watch it. The first parameter is an object representing the control that triggered the event and the second parameter is the event data appropriate to the event type:
void OnButtonClicked(object sender, EventArgs e) { // Do something with the click event }
Adding a Label to be Updated When the Button is Clicked
To build the modified application, create a new project. The default name for the second project is XamarinApplication2 (as shown in the namespace declaration in the following code example), but of course you can name it anything you want.
In order to do something visible on the screen to show that you actually got the click event, define another label. Give the label a value (by setting the Text
property) to be displayed in the initial state, and have the event handler update the Text
property (and color) once the click event triggers:
- Since the the click event triggers outside the class constructor, you must declare the label and a click counter up at the class level (lines 11-12).
- The button is instantiated (line 16) as is the new label (line 23): these 2 are then included as children of the
StackLayout
(lines 41-42), so they are stacked below the label from the initial program. - In this example, the initial text of the first label is changed to "Welcome to Tizen!".
- The event handler is added (lines 47-52). In it, increment the click counter, build a string showing how many times the button has been clicked, and set the
Text
property of the label to that string. Just for visual effect, also set the color of the label to something different than the initial color (which was set at line 26).
The following example shows the modified code:
using System; using System.Collections.Generic; using System.Linq; using System.Text; using Xamarin.Forms; namespace XamarinApplication2 { public class App : Application { Label label; int clicks = 0; public App() { Button button = new Button { Text = "Click here!", BackgroundColor = Color.Red, HorizontalOptions = LayoutOptions.Center, }; button.Clicked += OnButtonClicked; label = new Label { Text = "unclicked", HorizontalOptions = LayoutOptions.Center, }; // The root page of your application MainPage = new ContentPage { Content = new StackLayout { VerticalOptions = LayoutOptions.Center, Children = { new Label { HorizontalTextAlignment = TextAlignment.Center, Text = "Welcome to Tizen!" }, button, label, } } }; } void OnButtonClicked(object s, EventArgs e) { clicks += 1; label.Text = String.Format("Number of clicks: {0}", clicks); } protected override void OnStart() { // Handle when your app starts } protected override void OnSleep() { // Handle when your app sleeps } protected override void OnResume() { // Handle when your app resumes } } }
The following image shows what happens if you try out the modified code and run the application with it. At the startup, the button is red and the text below the button is unclicked. After a couple of clicks, the click counter is displayed below the button, and the button color has changed.
Figure: Enhanced application
Packaging Your Tizen .NET Application
This section gives a basic overview of packaging, to aid in understanding how to make simple changes. For more complex applications, see the packaging information in the Tizen documentation.
A Tizen .NET application is deployed in the form of an installable package, where the package file takes the suffix .tpk
. A Tizen .NET package has a relatively simple structure: internally it is a zipfile with content that matches the directory layout of the project.
In the following figure, the layout of the platform specific (.Tizen) project is shown. It includes the lib
, res
, and shared
(with a res
subdirectory containing an image file) directories , and the tizen-manifest.xml
file. There is also the bin
directory, which Visual Studio only shows if you select the Show all files option for the solution. These pieces all go into the package.
Figure: Project layout
Package generation (and in fact installation) is controlled by a package manifest file, which is named tizen-manifest.xml
(for more information, see Tizen .NET Application Structure). The Visual Studio template generates a package manifest, and places it at the top of the directory tree of the .Tizen project. The following figure shows the .tpk
file for the initial application, to illustrate how the combination of the directory layout and the package manifest leads to the actual package.
Figure: Package content
The initial points to learn here are:
- The
shared
directory is for items that are considered systemwide (shareable). The application icon is packaged inshared/res
: on installation, the icon appears on the home screen with the icons for the other applications. You can either replace the icon (which is just a copy of the default Tizen logo) with one of your own using the file name generated by Visual Studio, or put a new icon in the same project directory and update the package manifest to indicate the new name. - The
res
directory is for application-private resources. If the application needs a file to open at runtime, it can be placed here. - The
bin
directory contains the generated application executable. - The
lib
directory contains the generated application support code. - The package manifest is included in the package, as it is used at the installation time.
- 2 signature files (author and distributor) are included, as they are checked at the installation time.
Other information relating to packaging includes declarations of features and privileges, and the placement of language-specific files.