update popup mobile guide page

- TODO : guide how to make custom popup theme

PS2: [LB] Reviewed

Change-Id: I6d7eaa1d3b6235cc73a2bfb1e581b1d6642a9137
Signed-off-by: Jinyong Park <j4939.park@samsung.com>

diff --git a/org.tizen.guides/html/images/popup.png b/org.tizen.guides/html/images/popup.png
index 96751cb..320c8bc 100644 (file)
Binary files a/org.tizen.guides/html/images/popup.png and b/org.tizen.guides/html/images/popup.png differ

diff --git a/org.tizen.guides/html/native/ui/efl/component_popup_mn.htm b/org.tizen.guides/html/native/ui/efl/component_popup_mn.htm
index 06a75a3..0af5724 100644 (file)
--- a/org.tizen.guides/html/native/ui/efl/component_popup_mn.htm
+++ b/org.tizen.guides/html/native/ui/efl/component_popup_mn.htm
@@ -27,16 +27,15 @@
                </ul>
                <p class="toc-title">Content</p>
                <ul class="toc">
-                       <li><a href="#add">Adding a Popup Component</a></li>
-                       <li><a href="#styles">Using the Popup Styles</a></li>
-                       <li><a href="#areas">Setting the Popup Content</a></li>
-                       <li><a href="#orientation">Configuring and Hiding the Popup</a></li>
-                       <li><a href="#callback">Using the Popup Callbacks</a></li>
+                       <li><a href="#basic">Basic Usage</a></li>
+                       <li><a href="#feature">Features</a></li>
+                       <li><a href="#style">Styles</a></li>
+                       <li><a href="#callback">Callbacks</a></li>
                </ul>
                        <p class="toc-title">Related Info</p>
                <ul class="toc">
                        <li><a href="../../../../../org.tizen.native.mobile.apireference/group__Edje.html">Edje API for Mobile Native</a></li>
-                       <li><a href="../../../../../org.tizen.native.mobile.apireference/group__Elementary.html">Elementary API for Mobile Native</a></li>
+                       <li><a href="../../../../../org.tizen.native.mobile.apireference/group__Elementary.html">Elementary API for Mobile Native</a></li>                      
                </ul>
        </div></div>
 </div> 
@@ -44,26 +43,13 @@
 <div id="container"><div id="contents"><div class="content">
 <h1>Popup</h1>
 
-<p>This feature is supported in mobile applications only.</p>
+<p>The popup UI component is a small window for notifying the user or requesting user input. For more information, see the <a href="../../../../../org.tizen.native.mobile.apireference/group__Popup.html">Popup</a> API.</p>
 
-<p> The popup component shows a popup area that can contain:</p>
-<ul>
-<li>Title area with an icon and text (optional)</li>
-<li>Content area</li>
-<li>Action area with up to 3 buttons (optional)</li>
-</ul>
-
-<p>For more information, see the <a href="../../../../../org.tizen.native.mobile.apireference/group__Popup.html">Popup</a> API.</p>
-
-<p class="figure">Figure: Popup component</p> 
-<p align="center"><img alt="Popup component" src="../../../images/popup.png" /></p>
-      
-<p class="figure">Figure: Popup hierarchy</p> 
-<p align="center"><img alt="Popup hierarchy" src="../../../images/popup_tree.png" /></p>
-
-<h2 id="add">Adding a Popup Component</h2>
+<h2 id="basic">Basic Usage</h2>
 
-<p>To create a popup component, use the <span style="font-family: Courier New,Courier,monospace">elm_popup_add()</span> function:</p>
+<p>To use a popup component in your application:
+<ol>
+   <li>Add a popup component with the <span style="font-family: Courier New,Courier,monospace">elm_popup_add()</span> function:
 <pre class="prettyprint">
 Evas_Object *popup;
 Evas_Object *parent;
@@ -71,80 +57,31 @@ Evas_Object *parent;
 /* Create a popup */
 popup = elm_popup_add(parent);
 </pre>
-
-<h2 id="styles">Using the Popup Styles</h2>
-
-<p>The following table lists the available popup styles.</p>
-
-<table>
-<caption>Table: Popup styles</caption>
-<col width="20%"/>
-<col width="80%"/>
-<tbody>
-<tr>
- <th>Style</th>
- <th>Example</th>
-</tr>
- <tr>
- <td><span style="font-family: Courier New,Courier,monospace">elm/popup/base/default</span></td>
- <td align="center"><img alt="elm/popup/base/default" src="../../../images/popup_default.png" /></td>
- </tr>
- <tr>
- <td><span style="font-family: Courier New,Courier,monospace">elm/popup/base/toast</span></td>
- <td align="center"><img alt="elm/popup/base/toast" src="../../../images/popup_toast.png" /></td>
- </tr>
-  <tr>
- <td><span style="font-family: Courier New,Courier,monospace">elm/popup/base/theme_bg</span></td>
- <td align="center"><img alt="elm/popup/base/theme_bg" src="../../../images/popup_theme_bg.png" /></td>
- </tr>
- </tbody>
-</table>
-
-<p>To set the style to, for example, <span style="font-family: Courier New,Courier,monospace">toast</span>:</p>
+   </li>
+   <li>Set the title text using the <span style="font-family: Courier New,Courier,monospace">title,text</span> part name:
 <pre class="prettyprint">
-elm_object_style_set(popup, &quot;toast&quot;);
+elm_object_part_text_set(popup, &quot;title,text&quot;, &quot;Popup Title&quot;);
 </pre>
-
-<h2 id="areas">Setting the Popup Content</h2>
-
-<p>To set the popup content:</p>
-<ol>
-<li>
-<p>Configure the title area:</p>
-<ul>
-<li>Set the icon object using the <span style="font-family: Courier New,Courier,monospace">title,icon</span> part name.</li>
-<li>Set the title text as <span style="font-family: Courier New,Courier,monospace">Test popup</span> using the <span style="font-family: Courier New,Courier,monospace">title,text</span> part name.</li></ul>
-
+   </li>
+   <li>Set the content of the popup:</p>
+      <ul>
+         <li>Simple text:
 <pre class="prettyprint">
-Evas_Object *icon;
-
-/* Add an icon to the title area */
-elm_object_part_content_set(popup, &quot;title,icon&quot;, icon);
-
-/* Set the title text */
-elm_object_part_text_set(popup, &quot;title,text&quot;, &quot;Test popup&quot;);
+elm_object_text_set(popup, &quot;Popup text&quot;);
 </pre>
-</li>
-<li>
-<p>Set the content of the popup as:</p>
-<ul><li>Simple text:
-
-<pre class="prettyprint">
-elm_object_part_text_set(popup, &quot;default&quot;, &quot;Test popup&quot;);
-</pre></li>
-
-<li>Evas object:
-
+         </li>
+         <li>Evas object:
 <pre class="prettyprint">
 Evas_Object *content;
 
 elm_object_content_set(popup, content);
-</pre></li></ul>
-</li>
-<li>
-<p>Set the action area buttons.</p>
-<p>In the following example, the <strong>OK</strong> and <strong>Cancel</strong> buttons are created:</p>
-
+</pre>
+         </li>
+      </ul>
+   </li>
+   <li>
+      <p>Set the action area buttons.</p>
+      <p>In the following example, the <strong>OK</strong> and <strong>Cancel</strong> buttons are created:</p>
 <pre class="prettyprint">
 Evas_Object *button1;
 Evas_Object *button2;
@@ -157,48 +94,176 @@ button2 = elm_button_add(popup);
 elm_object_text_set(button2, &quot;Cancel&quot;);
 
 /* Set the buttons to the action area */
-elm_object_part_content_set(popup, &quot;button1&quot;, button1);
+elm_object_part_content_set(popup, &quot;button1&quot;;, button1);
 elm_object_part_content_set(popup, &quot;button2&quot;, button2);
 </pre>
-</li>
+   </li>
+   <li>Register the <a href="#callback">callback</a> functions.
+   <p>The following example shows how to define and register a callback for the <span style="font-family: Courier New,Courier,monospace">dismissed</span> signal:</p>
+<pre class="prettyprint">
+evas_object_smart_callback_add(popup, &quot;dismissed&quot;, dismissed_cb, data);
+
+void
+dismissed_cb(void *data, Evas_Object *obj, void *event_info)
+{
+&nbsp;&nbsp;&nbsp;&nbsp;evas_object_del(obj);
+}
+</pre>
+   </li>
 </ol>
-<h2 id="orientation">Configuring and Hiding the Popup</h2>
 
-<p>To configure the popup:</p>
+<p>The following example shows a simple use case of the popup component.</p>
 
-<ul>
-<li>Set the popup orientation with the <span style="font-family: Courier New,Courier,monospace">elm_popup_align_set()</span> function.
-<p>The second and third parameters have a value between 0.0 and 1.0, meaning the alignment of the popup within the parent object. The <span style="font-family: Courier New,Courier,monospace">ELM_NOTIFY_ALIGN_FILL</span> value is used to fill the popup in each axis direction.</p>
+<table border="0">
+   <caption>Example: Popup use case</caption>
+   <colgroup>
+      <col /><col />
+   </colgroup>
+   <tbody>
+      <tr>
+         <td style="text-align:left;margin-left:auto;margin-right:auto;">
 <pre class="prettyprint">
+Evas_Object *win;
+Evas_Object *conf;
+Evas_Object *nf;
+Evas_Object *popup;
+Evas_Object *button;
+
+/* Starting right after <a href="ui_layouts_n.htm#code">the basic EFL UI layout code</a> */
+/* (win - conformant - naviframe) */
+
+/* Add a popup and set a size hint to the popup */
+popup = elm_popup_add(nf);
 elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
-</pre></li>
+evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+
+/* Set a text to title and content part */
+elm_object_part_text_set(popup, &quot;title,text&quot;, &quot;Title&quot;);
+elm_object_text_set(popup, &quot;This Popup has title area, content area and action area set, &quot;
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;action area has two buttons OK and Cancel.&quot;);
+
+/* Add an &quot;OK&quot; button to popup */
+button = elm_button_add(popup);
+elm_object_style_set(button, &quot;popup&quot;);
+elm_object_text_set(button, &quot;OK&quot;);
+elm_object_part_content_set(popup, &quot;button1&quot;, button);
+
+/* Add a &quot;Cancel&quot; button to popup */
+button = elm_button_add(popup);
+elm_object_style_set(button, &quot;popup&quot;);
+elm_object_text_set(button, &quot;Cancel&quot;);
+elm_object_part_content_set(popup, &quot;button2&quot;, button);
+
+/* Add a callback function to popup */
+eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
+evas_object_smart_callback_add(popup, &quot;block,clicked&quot;, popup_block_clicked_cb, NULL);
+
+evas_object_show(popup);
+</pre>
+         </td>
+         <td style="text-align:center;margin-left:auto;margin-right:auto;">
+            <p align="center"><img alt="Alignment" src="../../../images/popup.png" /></p>
+         </td>
+      </tr>
+   </tbody>
+</table>
 
-<li>Hide the popup after a set time with the <span style="font-family: Courier New,Courier,monospace">elm_popup_timeout_set()</span> function.
-<p>To set the timeout to 5 seconds, after which the popup is hidden:</p>
+<h2 id="feature">Features</h2>
 
+<p>To configure the popup features:</p>
+<ul>
+<li>
+<p>Hide the popup after a set time with the <span style="font-family: Courier New,Courier,monospace">elm_popup_timeout_set()</span> function.</p>
+<p>In the following example, the timeout is set to 5 seconds, after which the popup is hidden:</p>
 <pre class="prettyprint">
 elm_popup_timeout_set(popup, 5.0);
 </pre>
 </li>
-
-<li>Dismiss the popup with a hide effect using the <span style="font-family: Courier New,Courier,monospace">elm_popup_dismiss()</span> function:
+<li>
+<p>Dismiss the popup with a hide effect using the <span style="font-family: Courier New,Courier,monospace">elm_popup_dismiss()</span> function:</p>
 <pre class="prettyprint">
 elm_popup_dismiss(popup);
 </pre>
-</li></ul>
-
-<h2 id="callback">Using the Popup Callbacks</h2>
-<p>To receive notifications about the popup events, listen to the following signals:</p>
-<ul>
-<li><span style="font-family: Courier New,Courier,monospace">timeout</span>: The popup is closed as a result of the timeout.
-</li>
-<li><span style="font-family: Courier New,Courier,monospace">block,clicked</span>: The user clicks on the blocked event area.
-<p>The blocked event area is the translucent region around the visible popup region.</p></li>
-<li><span style="font-family: Courier New,Courier,monospace">dismissed</span>: The popup is dismissed with a hide effect.
-<p>The <span style="font-family: Courier New,Courier,monospace">event_info</span> callback parameter is <span style="font-family: Courier New,Courier,monospace">NULL</span>.</p>
 </li>
 </ul>
 
+<h2 id="style">Styles</h2>
+
+<p>The following table lists the available component styles.</p>
+
+<table>
+   <caption>Table: Popup styles</caption>
+   <tbody>
+      <tr>
+         <th>Style</th>
+         <th>Sample</th>
+         <th>Text part</th>
+         <th>Swallow part</th>
+      </tr>
+      <tr>
+         <td><span style="font-family: Courier New,Courier,monospace">default</span></td>
+         <td align="center"><img alt="elm/button/base/default" src="../../../images/popup_default.png" /></td>
+         <td><span style="font-family: Courier New,Courier,monospace">elm.text</span>
+             <p><span style="font-family: Courier New,Courier,monospace">title,text</span></p>
+             <p><span style="font-family: Courier New,Courier,monospace">subtitle,text</span></p></td>
+         <td><span style="font-family: Courier New,Courier,monospace">elm.swallow.content</span>
+             <p><span style="font-family: Courier New,Courier,monospace">button1</span></p>
+             <p><span style="font-family: Courier New,Courier,monospace">button2</span></p>
+             <p><span style="font-family: Courier New,Courier,monospace">button3</span></p></td>
+      </tr>
+      <tr>
+         <td><span style="font-family: Courier New,Courier,monospace">toast</span></td>
+         <td align="center"><img alt="elm/button/base/default" src="../../../images/popup_toast.png" /></td>
+         <td><span style="font-family: Courier New,Courier,monospace">elm.text</span></td>
+         <td><span style="font-family: Courier New,Courier,monospace">elm.swallow.content</span></td>
+      </tr>
+      <tr>
+         <td><span style="font-family: Courier New,Courier,monospace">theme_bg</span></td>
+         <td align="center"><img alt="elm/button/base/default" src="../../../images/popup_theme_bg.png" /></td>
+         <td><span style="font-family: Courier New,Courier,monospace">elm.text</span>
+             <p><span style="font-family: Courier New,Courier,monospace">title,text</span></p>
+             <p><span style="font-family: Courier New,Courier,monospace">subtitle,text</span></p></td>
+         <td><span style="font-family: Courier New,Courier,monospace">elm.swallow.content</span>
+             <p><span style="font-family: Courier New,Courier,monospace">button1</span></p>
+             <p><span style="font-family: Courier New,Courier,monospace">button2</span></p>
+             <p><span style="font-family: Courier New,Courier,monospace">button3</span></p></td>
+      </tr>
+   </tbody>
+</table>
+
+<p>The <span style="font-family: Courier New,Courier,monospace">theme_bg</span> style is a unique style for supporting the genlist component&#39;s banded effect.</p>
+
+<h2 id="callback">Callbacks</h2>
+
+<p>You can register callback functions connected to the following signals for a popup object.
+
+<table border="1">
+   <caption>Table: Popup callback signals</caption>
+   <tbody>
+      <tr>
+         <th style="text-align:center;margin-left:auto;margin-right:auto;">Signal</th>
+         <th style="text-align:center;margin-left:auto;margin-right:auto;">Description</th>
+         <th style="text-align:center;margin-left:auto;margin-right:auto;">event_info</th>
+      </tr>
+      <tr>
+         <td><span style="font-family: Courier New,Courier,monospace">timeout</span></td>
+         <td>The popup is closed as a result of the timeout.</td>
+         <td><span style="font-family: Courier New,Courier,monospace;">NULL</span></td>
+      </tr>
+      <tr>
+         <td><span style="font-family: Courier New,Courier,monospace">block,clicked</span></td>
+         <td>The user clicks on the blocked event area.
+             The blocked event area is the translucent region around the visible popup region.</td>
+         <td><span style="font-family: Courier New,Courier,monospace;">NULL</span></td>
+      </tr>
+      <tr>
+         <td><span style="font-family: Courier New,Courier,monospace">dismissed</span></td>
+         <td>The popup is dismissed with a hide effect.</td>
+         <td><span style="font-family: Courier New,Courier,monospace;">NULL</span></td>
+      </tr>
+   </tbody>
+</table>
+
 <table class="note">
     <tbody>
         <tr>
@@ -210,22 +275,6 @@ elm_popup_dismiss(popup);
     </tbody>
 </table>
 
-<p>To register and define a callback for the <span style="font-family: Courier New,Courier,monospace">dismissed</span> signal:</p>
-
-<pre class="prettyprint">
-{
-&nbsp;&nbsp;&nbsp;&nbsp;evas_object_smart_callback_add(ctxpopup, &quot;dismissed&quot;, dismissed_cb, data);
-}
-
-/* Callback for the &quot;dismissed&quot; signal */
-/* Called when the popup is dismissed */
-void
-dismissed_cb(void *data, Evas_Object *obj, void *event_info)
-{
-&nbsp;&nbsp;&nbsp;&nbsp;dlog_print(DLOG_INFO, LOG_TAG, &quot;dismissed\n&quot;);
-}
-</pre>
-
 <table class="note">
     <tbody>
         <tr>