--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+ <meta http-equiv="X-UA-Compatible" content="IE=9" />
+ <link rel="stylesheet" type="text/css" href="../../css/styles.css" />
+ <link rel="stylesheet" type="text/css" href="../../css/snippet.css" />
+ <script type="text/javascript" src="../../scripts/snippet.js"></script>
+ <script type="text/javascript" src="../../scripts/jquery.util.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/common.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/core.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/search.js" charset="utf-8"></script>
+ <title>Watch Application</title>
+ </head>
+ <body onload="prettyPrint()" style="overflow: auto;">
+
+ <div id="toc-navigation">
+
+ <div id="toc_border"><div id="toc">
+ <p class="toc-title">Dependencies</p>
+ <ul class="toc">
+ <li>Tizen 4.0 and Higher</li>
+ </ul>
+ <p class="toc-title">Content</p>
+ <ul class="toc">
+ <li><a href="#prerequisites">Prerequisites</a></li>
+ <li><a href="#lifecycle">Managing the Application Life-cycle</a></li>
+ <li><a href="#systemrelated">Managing System-related Events</a></li>
+ <li><a href="#timehandle">Drawing the Watch UI</a></li>
+ <li><a href="#current">Getting the Current Time</a></li>
+ <li><a href="#ambient">Using the Ambient Mode</a></li>
+ </ul>
+ <p class="toc-title">Related Info</p>
+ <ul class="toc">
+ <li><a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchApplication.html">Tizen.Applications.WatchApplication Class</a></li>
+ </ul>
+ </div></div>
+</div>
+
+<div id="container"><div id="contents"><div class="content">
+
+<h1>Watch Application</h1>
+<p>You can create a watch application and manage its life-cycle to <a href="#current">retrieve the current date and time</a> and display it accurately on the screen.</p>
+
+
+<p>The main features of the <code>Tizen.Applications.WatchApplication</code> class include:</p>
+<ul>
+<li>Managing the application life-cycle
+<p>You can control the application execution by <a href="#lifecycle">overriding methods controlling the application state changes</a> during the application life-cycle. You can also <a href="#systemrelated">react to system events</a> by overriding applicable methods.</p></li>
+<li>Managing the time handle and displaying the time
+<p>You can manage the time handle and retrieve the window object for the watch UI. With the time handle, you can <a href="#timehandle">draw the UI</a> for your watch application.</p></li>
+<li>Managing the ambient mode
+<p>On a low-powered wearable device, an ambient mode is available. In this mode, the watch application shows a limited UI and receives the ambient tick event only once a minute to reduce power consumption.</p>
+<p>To use the ambient mode, the user must enable it in the device settings. You can <a href="#ambient">override methods monitoring when the application enters and exits the ambient mode</a>.</p>
+</li>
+</ul>
+
+<p>When a watch application is successfully installed on a device, its UI is visible in the <strong>Clock</strong> menu of the device <strong>Settings</strong> menu. The user can use the settings to change between available watch application UIs.</p>
+
+ <p align="center"><strong>Figure: Clock menu</strong></p>
+ <p align="center"><img alt="Clock menu" src="../../images/setting_to_clock.png" /></p>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+ <p>To enable your application to use the watch functionality:</p>
+<ol>
+<li>
+<p>To use the <code>OnAmbientTick()</code> method of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchApplication.html">Tizen.Applications.WatchApplication</a> class in the ambient mode, the application has to request permission by adding the following privilege to the <code>tizen-manifest.xml</code> file:</p>
+<pre class="prettyprint">
+<privileges>
+ <privilege>http://tizen.org/privilege/alarm.set</privilege>
+</privileges>
+</pre>
+</li>
+
+<li>To use the method and properties of the <code>Tizen.Applications.WatchApplication</code> class, include the <a href="https://developer.tizen.org/dev-guide/csapi/namespaceTizen_1_1Applications.html">Tizen.Applications</a> namespace in your application:
+<pre class="prettyprint">
+using Tizen.Applications;
+</pre></li>
+<li>Edit the watch application settings in the <a href="../../../../preview/html/tools/manifest_editor.htm">manifest</a> file.</li>
+</ol>
+
+<h2 id="lifecycle">Managing the Application Life-cycle</h2>
+<p>You can create and initialize a watch application with the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchApplication.html">Tizen.Applications.WatchApplication</a> class. To start an event loop, use the class's <code>Run()</code> method.</p>
+
+
+<p>To manage the application state changes, override the following methods of the <code>Tizen.Applications.WatchApplication</code> class:</p>
+<ul>
+<li>The <code>OnCreate</code> method is triggered before the application main loop starts. In this method, you can initialize the application resources, such as create windows and data structures:
+<pre class="prettyprint">
+protected override void OnCreate()
+{
+ /// Hook to take necessary actions before the main event loop starts
+ /// This usually means initializing the UI and application data
+
+ base.OnCreate();
+}
+</pre>
+</li>
+<li>The <code>OnAppControlReceived</code> method is triggered when another application sends a launch request to the application:
+<pre class="prettyprint">
+protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
+{
+ /// Handle the launch request
+ /// Show the user the task requested through the "AppControlReceivedEventArgs" parameter
+
+ base.OnAppControlReceived(e);
+}
+</pre>
+</li>
+<li>The <code>OnPause</code> method is triggered when the application is completely obscured by another application and becomes invisible:
+<pre class="prettyprint">
+protected override void OnPause()
+{
+ /// Take necessary actions when application becomes invisible
+ /// Release the resources needed to draw the normal watch
+
+ base.OnPause();
+}
+</pre>
+</li>
+<li>The <code>OnResume</code> method is triggered when the application becomes visible:
+<pre class="prettyprint">
+protected override void OnResume()
+{
+ /// Take the necessary actions when application becomes visible
+ /// Acquire the resources needed to draw the normal watch
+
+ base.OnResume();
+}
+</pre>
+</li>
+<li>The <code>OnTerminate</code> method is triggered when the application main loop exits:
+<pre class="prettyprint">
+protected override void OnTerminate()
+{
+ /// Release all resources
+
+ base.OnTerminate();
+}
+</pre>
+</li>
+<li>The <code>OnTick</code> method is triggered at least once per second. The watch application can get the current time from the <code>watch_time</code> time handle of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchTime.html">Tizen.Applications.WatchTime</a> class to draw a normal watch.
+
+<pre class="prettyprint">
+protected override void OnTick(TimeEventArgs time)
+{
+ /// Called at least once per second
+ /// Draw a normal watch with the hour, minute, and second info
+
+ base.OnTick(time);
+}
+</pre>
+</li>
+</ul>
+
+<h2 id="systemrelated">Managing System-related Events</h2>
+
+<p>To manage events related to system status changes, override the following methods of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchApplication.html">Tizen.Applications.WatchApplication</a> class:</p>
+<ul>
+<li><code>OnLocaleChanged()</code>: Triggered when the system language changes and the messages are translated.</li>
+<li><code>OnRegionFormatChanged()</code>: Triggered when the time zone changes.</li>
+<li><code>OnLowMemory()</code>: Triggered when the system is running low on memory. Use the method to save the current work and release resources; if this is not enough, the platform frees resources automatically and can even kill some applications.</li>
+<li><code>OnLowBattery()</code>: Triggered when the system is running low on battery (less than 5%). Use the method to save the current work and avoid battery-draining workloads.</li>
+</ul>
+<pre class="prettyprint">
+protected override void OnLocaleChanged(LocaleChangedEventArgs e)
+{
+ /// Take the necessary actions when the language setting changes
+
+ base.OnLocaleChanged(e);
+}
+
+protected override void OnRegionFormatChanged(RegionFormatChangedEventArgs e)
+{
+ /// Take the necessary actions when the region setting changes
+
+ base.OnRegionFormatChanged(e);
+}
+
+protected override void OnLowBattery(LowBatteryEventArgs e)
+{
+ /// Take the necessary actions when the system is running low on battery
+
+ base.OnLowBattery(e);
+}
+
+protected override void OnLowMemory(LowMemoryEventArgs e)
+{
+ /// Take the necessary actions when the system is running low on memory
+
+ base.OnLowMemory(e);
+}
+</pre>
+
+
+<h2 id="timehandle">Drawing the Watch UI</h2>
+<p>To draw an accurate clock in various formats on the screen, use the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchApplication.html">Tizen.Applications.WatchApplication</a> class getter methods with the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchTime.html">Tizen.Applications.WatchTime</a> class. You can get the <code>Tizen.Applications.WatchTime</code> instance with the <code>GetCurrentTime()</code> method.</p>
+
+<p>With the <code>Tizen.Applications.WatchTime</code> class, you can draw the UI for your watch application by getting the window object with the <code>ElmSharp</code> methods:</p>
+
+<pre class="prettyprint">
+private static Label _time;
+private static Window _win;
+private static Box _mainLayout;
+private static Conformant conformant;
+
+protected override void OnCreate()
+{
+ base.OnCreate();
+
+ _win = this.Window;
+
+ _mainLayout = new Box(_win);
+
+ _time = new Label(_win)
+ {
+ Text = "Test Time",
+ WeightX = 1,
+ WeightY = 1
+ };
+
+ _mainLayout.PackEnd(_time);
+
+ _mainLayout.Show();
+ _time.Show();
+
+ conformant = new Conformant(_win);
+ conformant.Show();
+ conformant.SetContent(_mainLayout);
+</pre>
+
+
+<div class="note">
+ <strong>Note</strong>
+ To draw the UI, use a single window that is initialized in the <code>Tizen.Applications.WatchApplication</code> class. Do not create additional windows. A stack of watch application windows gets corrupted, because the platform handles the watch application window in a special way.
+</div>
+
+<h2 id="current">Getting the Current Time</h2>
+
+<p>You can get the current local time in various formats using the <code>GetCurrentTime()</code> method of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchApplication.html">Tizen.Applications.WatchApplication</a> class and the properties of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchTime.html">Tizen.Applications.WatchTime</a> class.</p>
+
+<pre class="prettyprint">
+ WatchTime wt = GetCurrentTime();
+ int hour = wt.Hour24;
+ int min = wt.Minute;
+ int sec = wt.Second;
+
+ _time.Text = hour + ":" + min + ":" + sec;
+}
+</pre>
+
+<p>You can also get the UTC time and time zone, if needed, using the <code>UtcTimestamp</code> and <code>TimeZone</code> properties of the <code>Tizen.Applications.WatchTime</code> class.</p>
+
+<h2 id="ambient">Using the Ambient Mode</h2>
+
+<p>The details of the limited UI drawn in the ambient mode depend on the device. In addition, due to the ambient mode being a low power mode, there are limits to the colors that can be shown on the screen. Usually, when designing the ambient mode UI, draw it with limited colors (cyan, magenta, yellow, red, green, blue, black and white), and use less than 15% of the pixels on the screen. If you do not want to draw your own ambient mode UI, set the <code>ambient-support</code> attribute to <code>false</code> in the watch application <a href="../../../../preview/html/tools/manifest_editor.htm">manifest file</a> to allow the platform to show a default ambient mode UI.</p>
+
+<p>Some devices introduce a high color mode for the ambient mode. In the high color mode, you can use more colors (usually, 24-bit color) for drawing the ambient mode UI.</p>
+
+<p>Override the ambient mode methods of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchApplication.html">Tizen.Applications.WatchApplication</a> class to use the ambient mode:</p>
+<ul><li><p>The <code>OnAmbientChanged()</code> method is triggered when the ambient mode is enabled or disabled on the device. You can use the method to initialize your ambient mode UI.</p></li>
+<li><p>The <code>OnAmbientTick()</code> method is triggered when the device enters the ambient mode and every minute while the device is in the ambient mode. You can use the method to get the current time from the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Applications_1_1WatchTime.html">Tizen.Applications.WatchTime</a> class and draw the ambient mode watch. In this method, do not perform time-consuming tasks and always update the UI as quickly as possible. The platform can put the device to sleep shortly after the ambient tick expires.</p></li>
+</ul>
+
+<pre class="prettyprint">
+protected override void OnAmbientTick(TimeEventArgs time)
+{
+ base.OnAmbientTick(time);
+
+ /// Update information
+}
+
+protected override void OnAmbientChanged(AmbientEventArgs mode)
+{
+ base.OnAmbientChanged(mode);
+
+ if (mode.Enabled)
+ /// Prepare to enter the ambient mode
+ else
+ /// Prepare to exit the ambient mode
+}
+</pre>
+
+
+<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
+<script type="text/javascript" src="../../scripts/showhide.js"></script>
+</div></div></div>
+
+<a class="top sms" href="#"><img src="../../images/btn_top.gif" alt="Go to top" /></a>
+
+<div id="footer">
+<p class="footer">Except as noted, this content - excluding the Code Examples - is licensed under <a href="http://creativecommons.org/licenses/by/3.0/legalcode" target="_blank">Creative Commons Attribution 3.0</a> and all of the Code Examples contained herein are licensed under <a href="https://www.tizen.org/bsd-3-clause-license" target="_blank">BSD-3-Clause</a>.<br/>For details, see the <a href="https://www.tizen.org/content-license" target="_blank">Content License</a>.</p>
+</div>
+
+<script type="text/javascript">
+var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-25976949-1']);
+_gaq.push(['_trackPageview']);
+(function() {
+var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();
+</script>
+
+</body>
+</html>
</tr>
<tr>
<td style="border:none;"> </td>
+ <td colspan="6" style="border:none;"><code><a href="#watch_app"><watch-application></a></code></td>
+ </tr>
+ <tr>
+ <td style="border:none;"> </td>
+ <td style="border:none;"> </td>
+ <td colspan="5" style="border:none;"><code><a href="#watch_label"><label></a></code></td>
+ </tr>
+ <tr>
+ <td style="border:none;"> </td>
+ <td style="border:none;"> </td>
+ <td colspan="5" style="border:none;"><code><a href="#watch_icon"><icon></a></code></td>
+ </tr>
+ <tr>
+ <td style="border:none;"> </td>
<td colspan="6" style="border:none;"><code><a href="#shortcut-list"><shortcut-list></a></code></td>
</tr>
<tr>
<td>1 (optional)</td>
</tr>
<tr>
+ <td><code><a href="#watch_app"><watch-application></a></code></td>
+ <td>1 (optional)</td>
+ </tr>
+ <tr>
<td><code><a href="#shortcut-list"><shortcut-list></a></code></td>
<td>1 (optional)</td>
</tr>
</ui-application>
</pre>
+<h3 id="watch_app"><watch-application> Element</h3>
+ <p>This element contains the settings for a watch application.</p>
+ <p>For more information on the relationship between the elements, see the <a href="#hierarchy">element hierarchy</a>.</p>
+ <p><strong>Occurrences:</strong> </p>
+ <ul>
+ <li>1 (optional)</li>
+ </ul>
+
+ <p><strong>Expected children:</strong> </p>
+ <table border="1"><tbody>
+ <tr>
+ <th width="50%">Child element</th>
+ <th>Occurrences</th>
+ </tr>
+ <tr>
+ <td><code><a href="#watch_label"><label></a></code></td>
+ <td>1 or more</td>
+ </tr>
+ <tr>
+ <td><code><a href="#watch_icon"><icon></a></code></td>
+ <td>1 or more</td>
+ </tr>
+ </tbody></table>
+
+ <p><strong>Attributes:</strong> </p>
+ <ul>
+ <li><code>ambient-support</code>
+ <p>Indicates whether the application draws the ambient mode UI itself (available values: <code>true</code>, <code>false</code>)</p>
+ <p>If the value is <code>false</code>, the system default ambient mode UI is shown when the device enters the ambient mode.</p></li>
+ <li><code>appid</code>
+ <p>Watch application unique ID (string)</p></li>
+ <li><code>exec</code>
+ <p>Watch application executable file path (string)</p></li>
+ <li><code>type</code>
+ <p>Tizen application type (available value: <code>dotnet</code>)</p>
+ </ul>
+
+<pre class="prettyprint">
+<watch-application ambient-support="true" appid="org.tizen.watchsample" exec="watchsample.dll" type="dotnet">
+ <label>.....</label>
+ <icon>.....</icon>
+</watch-application>
+</pre>
+
+<h4 id="watch_label"><label> Element</h4>
+ <p>This element contains the watch application text.</p>
+
+ <p><strong>Occurrences:</strong> </p>
+ <ul>
+ <li>1</li>
+ </ul>
+
+ <p><strong>Expected value:</strong> </p>
+ <ul>
+ <li>Label value in string</li>
+ </ul>
+
+ <p><strong>For example:</strong></p>
+
+<pre class="prettyprint">
+<label>watchsample</label>
+</pre>
+
+<h4 id="watch_icon"><icon> Element</h4>
+ <p>This element contains the watch application icon image.</p>
+
+ <p><strong>Occurrences:</strong> </p>
+ <ul>
+ <li>1</li>
+ </ul>
+
+ <p><strong>Expected value:</strong> </p>
+ <ul>
+ <li>Icon file name</li>
+ </ul>
+<pre class="prettyprint">
+<icon>watchsample.png</icon>
+</pre>
+
<h3 id="shortcut-list"><shortcut-list> Element</h3>
<p>This element contains the shortcut template list used for adding a shortcut to the home screen.</p>
<feature name="http://tizen.org/feature/fmradio">true</privilege>
</pre>
-
<script type="text/javascript" src="../scripts/jquery.zclip.min.js"></script>
<script type="text/javascript" src="../scripts/showhide.js"></script>
</body>
-</html>
\ No newline at end of file
+</html>
projects / sdk / online-doc.git / commitdiff